【第42回】 Marketing Cloud REST API 超入門 Part.3 - リクエスト送信

2023年4月12日 07:42

今回で全 3 回に分けて書いてきた「Marketing Cloud REST API 超入門」の連載は、最終回となります。このシリーズでは、Marketing Cloud REST API の基本を一歩ずつ解説してきました。

これまでに扱った内容は以下の通りです。

① API 連携のインターフェース設定～ Talend API Tester のインストール
② 認証サーバーへ「アクセストークン」を要求
③ リソースサーバーへ「リクエスト」を送信

今回の Part.3 を実行するには以下が必要となります。
・ Part.1 の REST ベース URL
・ Part.2 の アクセストークン

今回の Part.3 では、実際に REST API を使用してリソースサーバーへリクエストを送信し、Marketing Cloud の機能を操作していきます。

■ リソースサーバーへ「リクエスト」を送信

今回は代表的なシナリオとして、Journey Builder で「API イベント」というエントリーソースを使ったジャーニーを作成し、API を使用してジャーニーをトリガーする手順を紹介します。

Step 1: データエクステンションの作成

まず、「API イベント」エントリーソース用のデータエクステンションを作成します。

標準データエクステンションで構いませんので、新規でデータエクステンションを作成してください。

このデータエクステンションは「送信可能」で設定する必要があります。

また、その購読者を「一度のみ」エントリーさせたい場合は、プライマリキーを設定してください。「何度も」エントリーさせたい場合は、プライマリーキーの設定は不要です。

そして、フィールドは「Id」「Email」「Name」「Eventdate」の 4 つで作成しました。このデータエクステンションに、API で連携された連絡先データが格納されます。

Step 2: Journey Builder の設定

次に、Journey Builder に移動し、「API イベント」エントリーソースを配置します。その後、以下の手順で設定を進めます。

「API イベント」エントリーソースをクリックして、「イベントを作成」をクリックしてください。

表示される「データエクステンションの選択」をクリックします。

ここで、先ほど Step 1 で作成したデータエクステンションを選択します。

「完了」ボタンをクリックします。

この設定が完了しましたら、イベント定義キーが発行されますので、メモ帳などにコピペしておきます。「APIEvent-」の部分から必要です。

その後は、メールアクティビティをセットして、すべてのジャーニーの設定が完了したら「アクテイブ化」ボタンをクリックしてください。

これで、ジャーニーはアクテイブ化されましたので、後は API を実行するだけとなります。

Step 3: Talend API Tester でのリクエスト送信

それでは Talend API Tester に移動して「リクエストを追加」をクリックしてください。

リクエストを新規で追加して「リクエストを開く」をクリックします。

メソッドから POST を選択します。

エンドポイントに、Part.1 で取得した「REST ベース URL」を使って以下のように入力してください。

https://[REST ベース URL].rest.marketingcloudapis.com/interaction/v1/events

「ヘッダーを追加」をクリックします。

ヘッダーの左窓に「Auth」と入力して、サジェスチョンから Authorization を選択します。

まず、ヘッダーの右窓に「Bearer」（ベアラー）と入力します。

そして、Bearer の後ろに半角スペースを開けて、Part.2 で取得済みのアクセストークンを入力します。

アクセストークンの有効期限は 18 分間です。期限切れの場合は、再度 Part.2 に戻ってアクセストークンを取得し直してください。

ボディに以下の JSON を貼り付けます。

{
  "contactKey": "連絡先キー",
  "eventDefinitionKey": "APIEvent- イベント定義キー",
  "data": {
    "id": "連絡先キー", // 上の連絡先キーと同じもので OK です
    "email": "メールアドレス",
    "name": "名前",
    "eventDate": " 2023/01/01 "
  }
}

入力が完了したら「送信」ボタンをクリックします。

レスポンスが 201 Created で返ってきたら成功です。

この設定は再利用できますので Talend API Tester に保存しておきましょう。

Step 4: 結果の確認と保存

Journey Builder に遷移し、1 件の連絡先がエントリーされていることを確認します。

また、エントリーソースのデータエクステンションにも、1 件格納されていることを確認します。成功です。

サンプルコードのまとめ

それでは、最後に、今回のサンプルコードをまとめておきます。

--- メソッド 
POST

--- エンドポイント
https://[REST ベース URL].rest.marketingcloudapis.com/interaction/v1/events

--- ヘッダー 
Content-Type：application/json 
Authorization：Bearer [アクセストークン] 

--- ボディ（サンプル）
{
  "contactKey": "連絡先キー",
  "eventDefinitionKey": "APIEvent- イベント定義キー",
  "data": {
    "id": "連絡先キー", // 上の連絡先キーと同じもので OK です
    "email": "メールアドレス",
    "name": "名前",
    "eventDate": " 2023/01/01 "
  }
}

＜エラー対処のポイント＞
・ "data" を記述した際、最後に「 , 」が残っているとエラーになります。
・連絡先キーだけをプライマリーキーとして設定すると 2 回目以降のエントリー時に重複が発生してエラーとなります。
・ジャーニーがアクティブ化していないとエラーになります。
・スコープが正しく設定されているかを確認してください。
＜interaction/v1/events の場合＞
■ AUTOMATION - Journeys - Read
■ CONTACTS - List and Subscribers - Read

以上です。

いかがでしたでしょうか？

これで、Marketing Cloud REST API の基本操作が完了しました。テスターを使って API を実行する流れがつかめたのではないでしょうか？このシリーズで扱わなかった他の API 機能については、別の機会にご紹介して行きます。

今回は以上です。