Salesforce Marketing Cloud Journey Builder API連携 実践ガイド

日付:

背景と応用シナリオ

Salesforce インテグレーションエンジニアとして、私は日々、様々なシステム間のデータ連携を設計・構築しています。中でも、Salesforce Marketing Cloud と外部システムとの連携は、顧客体験を統一し、マーケティング活動の効果を最大化するために不可欠なプロジェクトです。Marketing Cloud は強力なマーケティングオートメーションプラットフォームですが、その真価は、CRM、データウェアハウス、自社開発アプリケーションといった他のシステムとシームレスに連携させることで発揮されます。

本記事では、インテグレーションエンジニアの視点から、Marketing Cloud の中でも特に重要な機能である Journey Builder のデータを、REST API を通じてプログラム的に取得する方法について解説します。

具体的な応用シナリオとしては、以下のようなケースが考えられます。

  • CRMへのジャーニー進捗状況の同期： 顧客が「ウェルカムジャーニー」のどのステップにいるか（例：「メール1送信済み」「分岐Aで待機中」など）を Sales Cloud や Service Cloud の取引先責任者レコードに表示し、営業担当者やサポート担当者が顧客の状況をリアルタイムで把握できるようにする。
  • カスタマーサービスポータルでの情報提供： 顧客がログインするマイページ上で、「お客様は現在、〇〇キャンペーンのステップ3です」といった情報を提供し、エンゲージメントを高める。
  • 外部システムでのアクション実行： 顧客がジャーニー内の特定のステップに到達したことをトリガーとして、外部のデータ分析基盤にログを送信したり、別のシステムでタスクを生成したりする。

これらのシナリオを実現するためには、Marketing Cloud の外から Journey Builder の情報にアクセスする必要があります。そのための標準的な方法が、REST API (Representational State Transfer API の略で、Webサービスの設計モデルの一つ) の活用です。これから、その具体的な連携手順を順を追って説明します。

原理説明

Marketing Cloud REST API を利用した Journey Builder との連携は、大きく分けて2つのステップで構成されます。

  1. 認証 (Authentication)： APIリクエストに必要な「鍵」を取得するプロセス。
  2. APIリクエスト (API Request)： 取得した「鍵」を使って、目的のデータ（今回はジャーニーの一覧）を要求するプロセス。

この連携は、サーバー間の通信（Server-to-Server Integration）であるため、認証には OAuth 2.0 Client Credentials Grant Flow という仕組みを利用します。これは、ユーザーの介在なしに、アプリケーションが自身のクレデンシャル（IDとシークレット）を使って認証を行うための標準的な方法です。

ステップ1：認証とアクセストークンの取得

まず、Marketing Cloud の管理画面で API 連携のための準備を行います。

1. Installed Package の作成：
Marketing Cloud の [セットアップ] > [アプリケーション] > [インストール済みパッケージ] へ移動し、新しいパッケージを作成します。このパッケージが、外部アプリケーションの「IDカード」のような役割を果たします。

2. APIコンポーネントの追加：
作成したパッケージに、「APIインテグレーション」コンポーネントを追加し、「サーバー間」の連携タイプを選択します。

3. スコープ（権限）の設定：
次に、この API 連携にどのような操作を許可するかを「スコープ」で定義します。今回は Journey Builder の情報を読み取る必要があるため、[ジャーニー] のセクションで [読み取り] (Read) 権限にチェックを入れます。ここで設定した権限以上の操作は、この連携では実行できません。

この設定を保存すると、連携に必要な以下の3つの重要な情報が生成されます。

  • Client ID (クライアントID)： アプリケーションを識別するための公開ID。
  • Client Secret (クライアントシークレット)： アプリケーションを認証するためのパスワード。絶対に外部に漏らしてはいけません。
  • Authentication Base URI (認証ベースURI)： 認証リクエストを送信するための専用URL。テナントごとに異なります。

これらの情報を使って、外部アプリケーションは Marketing Cloud の認証エンドポイント (/v2/token) に POST リクエストを送信します。認証が成功すると、Marketing Cloud は Access Token (アクセストークン) を返却します。このアクセストークンが、後続の API リクエストで「認証済みの証」として機能する一時的な鍵となります。

ステップ2：Journey Builder API へのリクエスト

アクセストークンを取得したら、いよいよ Journey Builder のデータを取得します。

取得したアクセストークンを、HTTPリクエストの Authorization ヘッダーに Bearer トークンとして含めます。形式は Authorization: Bearer [ここにアクセストークン] となります。

このヘッダーを付与した上で、Journey Builder API のエンドポイントに対して GET リクエストを送信します。例えば、アカウント内に存在する全てのジャーニーの一覧を取得するためのエンドポイントは /interaction/v1/interactions です。

リクエストが成功すると、API はジャーニーの一覧を JSON 形式で返却します。この JSON データには、各ジャーニーのID、名前、バージョン、ステータス（実行中、停止中など）といった詳細な情報が含まれています。外部アプリケーションは、このレスポンスを解析し、必要な情報を抽出して利用することになります。

示例代码

以下に、Salesforce 公式ドキュメントに基づいた具体的な API リクエストの例を示します。

1. アクセストークンの取得

まず、認証ベースURIに存在する /v2/token エンドポイントに対して、Client ID と Client Secret を含む POST リクエストを送信します。 

POST https://YOUR_SUBDOMAIN.auth.marketingcloudapis.com/v2/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

コメント：

  • YOUR_SUBDOMAIN、YOUR_CLIENT_ID、YOUR_CLIENT_SECRET は、ご自身の環境の Installed Package から取得した値に置き換えてください。
  • grant_type に client_credentials を指定するのが、サーバー間認証の合図です。

成功すると、以下のような JSON レスポンスが返されます。 

{
  "access_token": "THIS_IS_YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "journeys_read",
  "rest_instance_url": "https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com/"
}

コメント：

  • access_token：これが後続のリクエストで使用する鍵です。
  • expires_in：トークンの有効期間（秒）です。この例では3600秒（1時間）です。
  • rest_instance_url：APIリクエストのベースとなるURLです。このURLを利用することを強く推奨します。

2. ジャーニー一覧の取得

次に、上記で取得した access_token を使って、Journey Builder API にリクエストを送信します。 

GET https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com/interaction/v1/interactions
Authorization: Bearer THIS_IS_YOUR_ACCESS_TOKEN
Content-Type: application/json

コメント：

  • エンドポイントは、前のレスポンスで得られた rest_instance_url にパス /interaction/v1/interactions を結合したものです。
  • Authorization ヘッダーに、Bearer という接頭辞とともにアクセストークンを指定している点に注意してください。

成功すると、ジャーニーの一覧が JSON 配列として返されます。 

{
  "count": 2,
  "page": 1,
  "pageSize": 50,
  "items": [
    {
      "id": "c1f72863-754e-486e-b286-932d88c009d9",
      "name": "Welcome Journey",
      "version": 3,
      "status": "Running",
      "createdDate": "2023-01-15T10:00:00.000Z",
      "modifiedDate": "2023-02-20T11:30:00.000Z"
    },
    {
      "id": "e5a87901-a35b-4b1d-8c22-b5b63428d05a",
      "name": "Re-engagement Campaign",
      "version": 1,
      "status": "Stopped",
      "createdDate": "2023-03-01T09:00:00.000Z",
      "modifiedDate": "2023-03-05T14:00:00.000Z"
    }
  ]
}

コメント：

  • items 配列に、各ジャーニーの情報がオブジェクトとして格納されています。
  • status を見ることで、ジャーニーが現在アクティブ（Running）かどうかが分かります。
  • この id を使うことで、さらに特定のジャーニーの詳細情報を取得するAPI (/interaction/v1/interactions/{id}) を呼び出すことも可能です。

注意事項

権限とスコープ (Permissions and Scope)

APIリクエストが 403 Forbidden エラーで失敗する場合、最も一般的な原因は権限不足です。Installed Package の設定で、実行したい操作に対応するスコープ（例：`journeys_read`）が有効になっているかを必ず確認してください。最小権限の原則に従い、必要以上の権限を与えないこともセキュリティ上重要です。

API制限 (API Limits)

Marketing Cloud の API には、プラットフォームの安定性を保つためのレート制限（一定時間内に呼び出せる回数の上限）が設けられています。大量のデータを頻繁に取得するような処理を実装すると、この制限に抵触し、429 Too Many Requests エラーが返される可能性があります。インテグレーションを設計する際は、APIコールを効率化し、エラー発生時に備えてリトライ処理（指数バックオフ付きが望ましい）を組み込むことが不可欠です。

エラーハンドリング (Error Handling)

堅牢なインテグレーションを構築するためには、エラーハンドリングが欠かせません。以下のような一般的なHTTPステータスコードへの対応を考慮する必要があります。

  • 400 Bad Request: リクエストの形式が正しくない（例：JSONの構文エラー）。
  • 401 Unauthorized: アクセストークンが無効、または有効期限が切れている。この場合、トークンを再取得してからリクエストを再試行する必要があります。
  • 403 Forbidden: 認証は成功したが、要求した操作を実行する権限がない。スコープ設定を見直してください。
  • 5xx Server Error: Marketing Cloud 側で一時的な問題が発生している。時間をおいてからリトライするのが一般的な対処法です。

トークン管理 (Token Management)

アクセストークンには有効期限（通常1時間）があります。APIリクエストのたびに新しいトークンを取得するのは非効率であり、認証サーバーのレート制限に達するリスクもあります。ベストプラクティスは、取得したアクセストークンをその有効期限とともにキャッシュ（一時保存）し、期限が切れる直前になるまで再利用することです。期限が近づいたら、新しいトークンを再取得してキャッシュを更新する、というロジックを実装してください。

まとめとベストプラクティス

本記事では、Salesforce インテグレーションエンジニアの視点から、Marketing Cloud の Journey Builder API と連携するための基本的な手順と注意点を解説しました。認証を通じてアクセストークンを取得し、それを使って目的の API エンドポイントを呼び出す、という一連の流れをご理解いただけたかと思います。

最後に、実務でインテグレーションを構築する上でのベストプラクティスをいくつか紹介します。

  1. 安全なクレデンシャル管理：
    Client ID や Client Secret をコード内にハードコーディングすることは絶対に避けてください。AWS Secret Manager や Azure Key Vault といったシークレット管理サービス、あるいはインテグレーションを実行するサーバーの環境変数などを利用して、安全に管理しましょう。Salesforce Platform から連携する場合は、「指定ログイン情報 (Named Credential)」を使うのが最も安全で推奨される方法です。
  2. ロギングと監視：
    APIの連携状況を把握するために、リクエストとレスポンス、特にエラー発生時の情報を詳細にログとして記録することが重要です。これにより、問題が発生した際のトラブルシューティングが迅速に行えます。
  3. 適切なツールの選択：
    REST API はリアルタイムに近いデータ取得には非常に有効ですが、何百万件ものトラッキングデータを一括で抽出するようなバルク処理には不向きです。そのような場合は、Automation Studio の「データ抽出アクティビティ」と「ファイル転送アクティビティ」を組み合わせて、データをファイルとしてSFTPサーバーに出力し、それを処理する、というバッチ処理のアプローチがより効率的です。常に要件に合った最適な技術を選択することが、優れたインテグレーションエンジニアの仕事です。

Marketing Cloud API を活用することで、マーケティング活動のデータを組織全体の資産として有効活用する道が拓かれます。本記事が、その一助となれば幸いです。

コメント

コメントを投稿