【第218回】 REST API を使ってすべてのエントリー情報を一括で取得する方法
現在アクティブ化されているジャーニーにおいて、どのデータエクステンションがエントリーソースとして使用されているのか、またそのジャーニーのスケジュール設定がどうなっているのか、気になったことはありませんか？
Salesforce Marketing Cloud において、それらを一括で閲覧できる便利な画面があればいいのに、と思ったことがある方もいらっしゃるかもしれません。
今回は、私の過去の記事「REST API を使ってすべての SQL クエリを一括で取得する方法」で紹介した技術を活用し、Journey Builder のエントリーソースにアクセスして、データエクステンション名やスケジュール設定を一括で取得する方法をご紹介します。
最終的には、すべてのエントリーソースの情報を、以下のようなエクセルで閲覧できるようにします。
■ 事前準備
今回の記事では、REST API を使用します。過去の連載「Marketing Cloud REST API 超入門」の Part.1 と Part.2 で紹介した以下の 2 つが必要です。
■ Part.1 で取得した「REST ベース URL」
■ Part.2 で取得した「アクセストークン」
今回、以下のスコープがセットアップで選択されている必要があります。
■ AUTOMATION - Journeys - Read
■ 使用する API の紹介 - GET: イベント定義
さて、今回取得するエントリーソースの設定情報は、「イベント定義」と呼ばれるものに含まれます。この「イベント定義」とは、今回の目的であるエントリーソースに限らず、例えば Wait Until Event のようなイベントトリガーによって待機解除される待機アクティビティなどでも利用される設定情報を指します。そのため、これらのイベント定義も今回の取得対象に含まれることを少し意識しておくと良いでしょう。
今回使用する API は、以下のヘルプドキュメントで紹介されています。しかし、提供されている情報がやや不足しているため、実際の利用時に役立つポイントや補足情報を加えながら解説していきます。
イベント定義が作成・更新さしてタイミングとは
エントリーソースのイベント定義は、「新規作成」または「更新」のいずれの場合でも、ジャーニーを「保存」したタイミングとなります。つまり、ジャーニーのドラフトで単にエントリーソースを配置し、設定しただけでは、イベント定義としては、まだ完成していません。
前述の Wait Until Event のようなイベントトリガーによって待機解除される待機アクティビティの場合は、アクティビティの設定が完了したタイミングでイベント定義が「新規作成」されます。つまり、アクティビティを作り直しする度に増えていくようなイメージです。
また、1 つのジャーニーに対して、必ずしも 1 つのイベント定義というわけではありません。例えば、同じジャーニー上でエントリーソースを作成して保存し、その後、削除して再作成するといったサイクルを繰り返すたびに、新しいイベント定義が作成されます。この時、削除されたイベント定義は画面上からは見えなくなりますが、バックエンドで履歴として残り続けます。そして、この履歴に保存期限は設定されていませんので、永久に取得対象になります。たとえジャーニーを削除したとしても消えません。
▶ REST API を使用して取得する主要なフィールドを補足しておきます。
1. id、eventDefinitionKey
これらは、イベント定義が作成される際に自動的に生成される、イベント定義固有の id と Key です。
2. dataExtensionId
これは、データエクステンションの外部キーとは異なります。イベントに関連付けられたデータエクステンションに固有のデータエクステンション ID であり、MC 画面からは取得できない ID となっています。
ちなみに、最終的にこの API を使って、データエクステンションの外部キーは取得できないことをお伝えしておきます。
3. type
type とは、イベント定義の「種別」を指します。前述の通り、イベント定義はエントリーソースのものに限られません。この type を使用して、API にパラメーターを付与することでフィルタリングが可能です。
以下は主要な type の例です：
- EmailAudience ⇒ 通常の Data Extension 送信
- AutomationAudience ⇒ Automation Studio 由来の Data Extension 送信
- APIEvent ⇒ API Event
- CloudPagesSmartCaptureSubmissionEvent ⇒ Cloudpages
- SalesforceObjectTriggerV2 ⇒ Salesforce Data
4. sourceApplicationExtensionId
これは上のイベント定義のタイプ（type）に対して固有の ID を指します。ただし、特に使用する機会はほとんどありません。
5. category
Audience カテゴリーと Event カテゴリーの 2 種類があります。
Audience：EmailAudience と AutomationAudience のタイプが含まれます
Event：Audience カテゴリー以外のイベント定義はこの Event になります
データを取得する際の目的に合わせて、この category をパラメーターに追加して、まずは大きく二分することをオススメします。
今回の記事では「どのデータエクステンションがエントリーソースとして使用されているのか」という目的になりますので、category=Audience のパラメーターを使用したいと思います。
6. iconUrl
従来と使い方が異なると思いますが、"API Event" type において、iconURL に "/images/icon_journeyBuilder-event-api-blue.svg" が入っている場合は、エントリーソースの API Event を指します。一方、例えば、イベントトリガーによって待機解除される待機アクティビティである Wait Until Event アクティビティの場合には "/images/xxx.svg" と入力されています。
7. name
エントリーソースのイベント定義の場合には、name はジャーニー名を指します。ただし、この名前は、エントリーソースが維持されている時点で最後に命名されていたジャーニー名が履歴として保存されます。
例えば、あるジャーニーのドラフトでジャーニー名が「A」となっているときに、エントリーソースを作成して保存すると、そのエントリーソースの name は「A」となります。その後、エントリーソースを削除し、新しいエントリーソースを設定した上で、ジャーニー名を「B」に変更して保存した場合、最初のエントリーソースは name: A として残ります。なぜなら、エントリーソース削除時の時点（維持された最後の時点）で、ジャーニー名が「A」だったからですね。一方で、新たに作成したエントリーソースは、ジャーニー名「B」のもとで作成されたため、name: B となります。
このように、同じドラフト上で作業していても、name が異なるケースが発生することがありますので注意して下さい。また、この name を使用して、API にパラメーターを付与することでフィルタリングが可能です。
※ Wait Until Event のようなイベントトリガーによって待機解除される待機アクティビティの場合は、name はそのイベント定義名そのものを指し、ジャーニー名ではないので注意して下さい。
8. dataExtensionName
エントリーソースで選択されているデータエクステンションの名前が表示されます。ただし、残念ながら、この dataExtensionName を使用して API にパラメーターを付与することでフィルタリングを行うことはできません。
9. interactionCount
これは、イベント定義がバージョンを超えて何回アクティブ化されたかをカウントしています。ただし、この情報を特に使用する機会はほとんどありません。
10. publishedInteractionCount
この publishedInteractionCount は重要なフィールドで、現在アクティブ化されているジャーニーかどうかを示しています。
1（True）：現在アクティブ化されているジャーニー
0（False）：現在アクティブ化されていないジャーニー
ただし、残念ながら、この publishedInteractionCount を使用して API にパラメーターを付与してフィルタリングすることはできません。後にエクセルで開いた時に、エクセル上でフィルタリングしてください。
11. metaData.scheduleFlowMode
このフィールドには、スケジュールの実行モードが含まれます。
一回実行（run once）
定期実行（recurring）
Automation Studio トリガー（automation）
※まだ、スケジュールが設定されていない場合は NULL になります。
12. metaData.runOnceScheduleMode
scheduleFlowMode が「一回実行」の場合のスケジュールモードが含まれます。
特定の日時（onSchedule）
アクティベーション時（onPublish）
※ scheduleFlowMode が「定期的」「オートメーション」 の場合は NULL になります。
13. metaData.criteriaDescription
エントリーソース設定時に、フィルター設定した場合にこちらにその条件がテキスト表示されます。エントリーソースにフィルター条件がかかっているジャーニーを探す際に重宝します。
■ REST API の設定方法
それでは、まず Talend API Tester で以下の設定を行ってください。
--- メソッド
GET
--- エンドポイント
https://[REST ベース URL].rest.marketingcloudapis.com/interaction/v1/eventDefinitions?$page=1&$pagesize=10000&category=Audience
--- ヘッダー
Content-Type：application/json
Authorization：Bearer [アクセストークン] 注意点
GET メソッドであるため、ボディの入力は不要です。
$page=1&$pagesize=1000 のようなページサイズのパラメーターを入力しない場合は、デフォルトで最大 50 個のイベント定義が取得されます。
category=Audience パラメーターを入力すると、エントリーソースがデータエクステンションのものに限定して取得されます。
■ JSON ファイルの取得と処理
これを Talend API Tester で実行すると、イベント定義が JSON 形式で取得できます。私のデモ環境では、349 件のイベント定義が取得できました。
次に、この JSON をダウンロードしてください。
「eventDefinitions.json」という名前の JSON ファイルがダウンロードできたと思います。
この JSON ファイルが取得できたら、エクセルを「新規」で開き「データ」タブをクリックします。
続いて、「データの取得」から「ファイルから」→「JSON から」を選択すると、参照が開きますので、先ほどダウンロードした JSON ファイルを選択してください。
すると、Power Query エディターが自動的に立ち上がるので、List の部分をクリックしてください。
下記画面になったら、「テーブルへの変換」をクリックします。
以下のポップアップが表示されますが、デフォルトのまま OK をクリックして先に進んでください。
続いて、下記の赤枠のアイコンをクリックしてください。
ここで、列の選択画面が出ますので、今回は以下の 5 つを選択して OK をクリックしてください。
- name：ジャーニー名
- dataExtensionName：データエクステンション名
- metaData（※次の展開のために必須）
- publishedInteractionCount：ジャーニーがアクティブ化されているか？
- schedule（※次の展開のために必須）
続いて、metadata の右側にある下記の赤枠のアイコンをクリックします。
ここでは、以下の 3 つを選択して OK をクリックしてください。
- metaData.criteriaDescription：エントリーソースのフィルター条件
- metaData.scheduleFlowMode：スケジュールの実行モード
- metaData.runOnceScheduleMode：一回実行時のスケジュールモード
最後に、schedule の右側にある下記の赤枠のアイコンをクリックします。
ここでは、以下の 6 つを選択して OK をクリックしてください。
- schedule.startDateTime：スケジュール開始日時
- schedule.endDateTime：スケジュール終了日時
- schedule.timeZone：スケジュールが設定されたタイムゾーン
- schedule.occurrences：予定されたスケジュールの実行回数
- schedule.endType：スケジュールの終了方法（回数 or 期日）
- schedule.frequency：スケジュールの頻度（日次・週次・月次など）
以上です。現在、最終的に展開されるプレビューが表示されていると思いますので、「閉じて読み込む」ボタンから「閉じて読み込む」をクリックしてください。
これで、349 個の イベント定義がエクセルで 1 行ごと展開されました。
完成です。このエクセルの表示順は、古いジャーニーから並んでいます。
■ 追加 Tips
もし、現在アクティブ化しているジャーニーだけに絞りたい場合は、エクセルのフィルター機能を使って、publishedInteractionCount を 1 でフィルタリングしてみて下さい。
さらに、schedule.endDateTime を昇順に並び替えて、本日以降のスケジュールを探してください。それらが、ジャーニーがアクティブ化されており、本日以降に実行が予定されているジャーニーの一覧になります。👈😄
いかがでしたでしょうか。
今回紹介した方法で、REST API を使って Salesforce Marketing Cloud の Journey Builder のエントリーソースにアクセスして、データエクステンション名やスケジュール設定を一括で取得し、効率的に管理できるようになりましたね。ぜひ、この方法を積極的に活用してみてください。
今回は以上です。