【第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 は下記を参照

Journeys and Events | Marketing Cloud APIs and SDKs | Salesforce Developers

▶ ダウンロードファイルのサイズ確認用の REST API は下記を参照

Journeys and Events | Marketing Cloud APIs and SDKs | Salesforce Developers

---

今回の記事では 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」として表示されます。

REST API Permission IDs and Scopes | Marketing Cloud Engagement APIs and Programmatic Languages | Salesforce Developers

---

それでは、待機アクティビティを通過した人を取得してみます。

まずは、待機アクティビティのアクティビティ 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"]
}

今回は以上です。

Click here for English version

Extracting Contacts Passing Through Wait activities Using Journey Builder REST API

次の記事はこちら

前回の記事はこちら

私の note のトップページはこちら

Nobuyuki Watanabe｜note