【第119回】 REST API を使って待機アクティビティ上の連絡先を取得する方法
Salesforce Marketing Cloud 開発者のお助け機能であるデータビューを使用すると、あるジャーニーのメールアクティビティでメール送信した連絡先のリストを取得することができます。
しかし、データビューでは、Journey Builder の待機アクティビティを通過した人を取得することはできません。
もし、この取得を何らか行うには「連絡先の更新」というアクティビティを Journey Builder のパス上に設定して、そのアクティビティを通過した連絡先をデータエクステンションに溜めるような仕組みを作る必要があります。
しかし、この仕組みにも問題点があり、この「連絡先の更新」アクティビティは、事前にジャーニーパス上に準備をする必要があり、急遽その連絡先リストの取得が必要になっても、結果的には処理ができず、何ともユーザー泣かせの状態となっていました。今回は、遂にその悩みを解決する機能の紹介です。
これを行うには Summer '23 でリリースされた「REST API を介した Journey Builder 履歴のダウンロード」という機能を使用します。
この REST API を使用すると、直近 30 日分のジャーニー履歴を CSV または TSV ファイルでダウンロードできます。このファイルは 1 GB を超えない範囲で取得できます。取得内容が 1 GB を超えていないかを確認するための REST API も同時に発表されています。
▶ 履歴ダウンロード用の REST API は下記を参照
▶ ダウンロードファイルのサイズ確認用の REST API は下記を参照
今回の記事では REST API を使用します。
過去の記事「Marketing Cloud REST API 超入門」の Part.1 と Part.2 の記事で取得できる以下の 2 つが必要となりますので、事前に用意してください。
■ Part.1 の REST ベース URL
■ Part.2 の アクセストークン
以下のスコープが API セットアップで選択されている必要があります。
■ AUTOMATION - Journeys - Read
■ CONTACTS - List and Subscribers - Read
※ CONTACTS - List and Subscribers - Read の入力を忘れると連絡先がすべて「Contact Unknown」として表示されます。
それでは、待機アクティビティを通過した人を取得してみます。
まずは、待機アクティビティのアクティビティ ID を取得してください。アクティビティ ID の取得方法に関しては、以前に記事にしましたので下記をご確認ください。
続いて、Talend API Tester に移動します。新規リクエストを立ち上げてください。新規リクエストの画面を立ち上げたら、以下の情報を入力してください。入力後に「送信」ボタンを押します。
--- メソッド
POST
--- エンドポイント
https://[REST ベース URL].rest.marketingcloudapis.com/interaction/v1/interactions/journeyhistory/download?columns=ContactKey
--- ヘッダー
Content-Type：application/json
Authorization：Bearer [アクセストークン]
x-direct-pipe：true
--- ボディ（サンプル）
{
"activityIds": ["8bb8d44a-9576-4ec8-9b19-576c56ec1746"],
"statuses": ["complete"]
}ヘッダーで「x-direct-pipe：true」を設定することを忘れがちですので注意してください。あと、Body で "statuses" を設定しないと、連絡先が二重で取得されてしまいますので注意してください。statuses = complete で条件化するのは、ある程度、御作法としても良いのかもしれません。
また、今回の例では取得する項目を ContactKey のみとしています。取得する項目に関しては、エンドポイントにおいて、パラメーターで指定します。
パラメーターを無しにすると、以下が取得されます。
・TransactionTime（例：2024-06-13T14:24:26.687Z）
・ContactKey（例：BOR501）
・Status（例：Complete）
・DefinitionId（例：152018ff-d987-4797-bc1b-9566bb6120d2）
・DefinitionName（例：Test_Journey）
・ActivityId（例：8bb8d44a-9576-4ec8-9b19-576c56ec1746）
・ActivityName（例：1 日）
・ActivityType（例：WaitActivity）
もし、すべての取得可能な項目を選択したい場合は、パラメーターに以下をコピペして下さい。ContactKey の代わりにコピペする形になります。
ContactKey,ActivityId,ActivityName,ActivityType,ClientStatus,CreatedDate,DefinitionId,DefinitionInstanceId,DefinitionName,EndDate,EntrySource,EpochTimeInMilliseconds,EventId,EventName,Id,Message,OutcomeActivityId,SourceType,StartDate,Status,TransactionTime,Result.Status,Result.Tags,Result.Messages,Result.Outcome
送信の結果 200 OK でレスポンスがあれば、リクエストは成功です。
Talend API Tester の場合、右下の Download ボタンから CSV ファイルがダウンロードができますので、そちらから CSV ファイルを取得して、Marketing Cloud へ手動インポートするなどして活用してください。
ちなみに、今回入力した情報は、今後も Talend API Tester で使い回しができますので、必要に応じて保存してください。
【追記】 2024 年 2 月 8 日
もし、取得可能な 30 日間の中で、特定の時間帯の連絡先のみを取得したい場合は、以下のようなボディに変更して下さい。
※時間は UTC で記載する必要があります。以下のボディは、JST（日本のタイムゾーン UTC+9）で 2024 年 1 月 31 日の 8 時から 18 時までに待機アクティビティに到着した連絡先を取得する例です。それぞれの日付で 9 時間ずつ時間をマイナスして入力してください。
--- ボディ（サンプル）
{
"start": "2024-01-30T23:00:00Z",
"end": "2024-01-31T09:00:00Z",
"activityIds": ["f8acd255-19da-4d88-beaf-d2efba9b9279"],
"statuses": ["complete"]
}【追記】 2024 年 9 月 30 日
definitionIds はジャーニー ID ではなく、バージョン ID です。以下は、あるバージョンの目標達成となった連絡先を取得するサンプルコードと、あるバージョンの終了条件となった連絡先を取得するサンプルコードです。
※ 簡単にバージョン ID を取得する方法も以下の記事を参照して下さい。
--- 目標達成となった連絡先を取得するボディ（サンプル）
{
"definitionIds": ["a8787c44-d866-4b3a-bf71-f515b9a5c63f"],
"activityTypes": ["goalcriteriaactivity"]
}
--- 終了条件となった連絡先を取得するボディ（サンプル）
{
"definitionIds": ["86f7c10b-76fa-4f5f-94b5-8afc6d0509af"],
"statuses": ["ExitCriteriaMet"]
}
--- ジャーニーにエントリーした連絡先を取得するボディ（サンプル）
{
"definitionIds": ["370c64da-781b-4f67-a10a-7722b74e73bb"],
"activityTypes": ["startinteractionactivity"]
}今回は以上です。