Salesforce Marketing Cloud REST API を活用した Journey Builder 連携のマスターガイド

背景と応用シナリオ

Salesforce Integration Engineer (Salesforce 統合エンジニア) として、私たちは日々、異なるシステム間のシームレスなデータ連携という課題に取り組んでいます。特に、企業のマーケティング活動の中核をなす Salesforce Marketing Cloud は、他のシステムとの連携がその価値を最大化する鍵となります。中でも Journey Builder は、顧客の行動や属性に基づいてパーソナライズされたコミュニケーションを自動化する強力なツールですが、その真価は外部イベントをトリガーとしてリアルタイムにジャーニーを開始できるかどうかにかかっています。

例えば、以下のようなシナリオを考えてみましょう。

シナリオ1：ECサイトでのカート放棄

顧客がECサイトで商品をカートに追加したものの、購入せずにサイトを離脱しました。この「カート放棄」というイベントをリアルタイムで検知し、Marketing Cloud の Journey Builder に連携することで、「お買い忘れはありませんか？」といったリマインドメールを自動送信するジャーニーを開始できます。これにより、コンバージョン率の向上が期待できます。

シナリオ2：Sales Cloud での新規リード作成

営業担当者が Sales Cloud に新しいリードを登録しました。この登録イベントをトリガーに、リードに対して自動的にウェルカムメールシリーズを配信するジャーニーを開始します。これにより、リードナーチャリング（見込み顧客育成）のプロセスを自動化し、営業効率を高めることができます。

シナリオ3：モバイルアプリでの特定アクション

ユーザーが企業のモバイルアプリで特定のアクション（例：特定機能の初回利用、ポイント獲得など）を実行しました。このアクションを Journey Builder に連携し、関連情報や次のアクションを促すプッシュ通知を送信するジャーニーを開始します。

これらのシナリオを実現するためには、外部システム（ECサイト、Sales Cloud、モバイルアプリなど）から Marketing Cloud へ、安全かつ確実にデータを送信する仕組みが必要です。ここで中心的な役割を果たすのが、Marketing Cloud REST API です。本記事では、統合エンジニアの視点から、Marketing Cloud の REST API を使用して外部システムのイベントを Journey Builder に連携させるための技術的な原理、実装方法、そして注意点について詳しく解説します。

原理説明

Journey Builder との API 連携は、主に2つのステップで構成されます。まず、API へのアクセス権を取得するための認証プロセス、次に、特定のジャーニーにコンタクトを投入するためのイベント発火プロセスです。

1. 認証：OAuth 2.0 アクセストークンの取得

Marketing Cloud の API は、OAuth 2.0 プロトコルに基づいた認証を採用しています。API リクエストを送信する前に、まず認証エンドポイントに対して Client ID と Client Secret を送信し、Access Token (アクセストークン) を取得する必要があります。

この Client ID と Client Secret は、Marketing Cloud の [セットアップ] > [アプリケーション] > [インストール済みパッケージ] で作成した API Integration コンポーネントから取得します。このパッケージには、API がどの程度の権限を持つかを定義するスコープ設定も含まれています。Journey Builder 連携には、少なくとも「Journeys: Read」および「Event Notifications: Execute」の権限が必要です。

取得したアクセストークンには有効期限があるため、通常はトークンをキャッシュし、期限が切れた場合に再取得するロジックを実装するのが一般的です。

2. イベント発火：Journey Builder API エンドポイントへのリクエスト

アクセストークンを取得したら、次に Journey Builder のイベント発火用エンドポイント (/interaction/v1/events) に POST リクエストを送信します。このリクエストのペイロード（本文）に、ジャーニーに投入したいコンタクトの情報や、ジャーニーの識別に必要な情報を含めます。

リクエストペイロードの主要なキーは以下の通りです。

ContactKey: ジャーニーに投入するコンタクトの一意の識別子です。通常、Salesforce CRM と連携している場合は Lead ID や Contact ID、ECサイトなどでは顧客IDが使用されます。Marketing Cloud 内でこのキーによってコンタクトが一意に識別されます。
EventDefinitionKey: どのジャーニーのどのエントリソース（入口）にコンタクトを投入するかを識別するためのキーです。これは、Journey Builder で「API イベント」をエントリソースとして設定した際に自動的に生成される一意の文字列です。
Data: ジャーニー内でパーソナライズに使用するための追加データを含むオブジェクトです。例えば、メールの文面に顧客の名前や購入しようとしていた商品名を入れたい場合、この Data オブジェクトにそれらの情報を含めて送信します。このデータは、ジャーニー設定時に作成したデータエクステンションの各フィールドに対応している必要があります。

この API リクエストが Marketing Cloud に正常に受理されると、指定された EventDefinitionKey に紐づくジャーニーに、ContactKey で指定されたコンタクトが投入され、ジャーニーが開始されます。このプロセスは非同期で処理されるため、API はリクエストを受理した時点で即座にレスポンス（通常は 202 Accepted）を返します。実際のジャーニーへの投入は、その後バックグラウンドで処理されます。

示例代码

ここでは、実際に Journey Builder にコンタクトを投入するまでの API リクエストの例を2段階に分けて示します。これらのコードは Salesforce の公式開発者ドキュメントに基づいています。

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

まず、Marketing Cloud の認証エンドポイントに POST リクエストを送信してアクセストークンを取得します。YOUR_SUBDOMAIN、YOUR_CLIENT_ID、YOUR_CLIENT_SECRET はご自身の環境の値に置き換えてください。

POST /v2/token HTTP/1.1
Host: YOUR_SUBDOMAIN.auth.marketingcloudapis.com
Content-Type: application/json

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

詳細な注釈:

POST /v2/token: OAuth 2.0 のトークンを取得するための標準的なエンドポイントです。
Host: この URL は、お使いの Marketing Cloud アカウントに固有のテナントサブドメイン (TSSD) を含みます。[セットアップ] > [インストール済みパッケージ] で確認できます。
grant_type: "client_credentials" は、サーバー間の連携で使用される認証フローを指定します。
client_id: インストール済みパッケージのクライアントIDです。
client_secret: インストール済みパッケージのクライアントシークレットです。
account_id: (任意) 連携対象のビジネスユニットの MID (Member ID) を指定します。親アカウントの認証情報で子ビジネスユニットの API を操作する場合に必要です。

このリクエストが成功すると、以下のような JSON レスポンスが返却されます。この中の access_token を次のステップで使用します。

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

ステップ2：Journey Builder イベントの発火

取得したアクセストークンを使用して、Journey Builder のイベント発火エンドポイントに POST リクエストを送信します。

POST /interaction/v1/events HTTP/1.1
Host: YOUR_SUBDOMAIN.rest.marketingcloudapis.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
    "ContactKey": "user@example.com",
    "EventDefinitionKey": "APIEvent-a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
    "Data": {
        "EmailAddress": "user@example.com",
        "FirstName": "Taro",
        "LastName": "Salesforce",
        "OrderID": "ORDER-12345",
        "OrderTotal": 9800
    }
}

詳細な注釈:

POST /interaction/v1/events: Journey Builder にコンタクトを投入するための専用エンドポイントです。
Host: トークン取得時のレスポンスに含まれていた rest_instance_url のホスト部分を使用します。
Authorization: Bearer YOUR_ACCESS_TOKEN: HTTP ヘッダーに、ステップ1で取得したアクセストークンを "Bearer" スキームで指定します。これが認証情報となります。
ContactKey: コンタクトを一意に識別するキー。ここではメールアドレスをキーとして使用しています。
EventDefinitionKey: Journey Builder の API イベントで設定された一意のキー。このキーによって、どのジャーニーに投入するかが決まります。
Data: ジャーニーに渡すデータオブジェクト。ここに格納されたキー (EmailAddress, FirstName など) は、ジャーニーのエントリソースとして設定したデータエクステンションの列名と一致している必要があります。これらの値は、メールコンテンツのパーソナライズ (例: %%FirstName%%) や、ジャーニー内の分岐ロジック (例: OrderTotal が 5000円以上か) などに利用できます。

注意事項

統合エンジニアとして、API 連携を実装する際には以下の点に特に注意する必要があります。

権限 (Permissions)

API 連携に使用するインストール済みパッケージには、必要最小限の権限を付与することがセキュリティのベストプラクティスです。Journey Builder へのイベント投入の場合、主に以下の権限が必要です。

Journeys: Read (ジャーニーの情報を読み取るために必要となる場合があります)
Event Notifications: Execute (API イベントを発火させるための中心的な権限)
Contacts: Read, Write (コンタクト情報を参照・更新する場合)
Data Extensions: Read, Write (エントリソースのデータエクステンションに書き込むため)

本番環境にデプロイする前に、必要な権限スコープを正確に特定し、設定してください。

API 制限 (API Limits)

Salesforce Marketing Cloud には、プラットフォームの安定性を保つための API レート制限が存在します。短時間に大量のリクエストを送信すると、Throttling (スロットリング) が発生し、API リクエストが拒否される可能性があります (例: HTTP 429 Too Many Requests)。

特に、大規模なキャンペーンやリアルタイム性が高い連携を実装する場合は、1分あたりや1時間あたりのリクエスト数を考慮した設計が必要です。必要に応じて、リクエストをキューイングして順次処理する、指数バックオフ付きのリトライロジックを実装するなどの対策を講じる必要があります。最新の API 制限については、Salesforce Trust サイトや公式ドキュメントで常に確認してください。

エラー処理 (Error Handling)

堅牢な統合を構築するためには、適切なエラーハンドリングが不可欠です。Journey Builder API が返す主要な HTTP ステータスコードとその意味を理解しておく必要があります。

202 Accepted: リクエストは正常に受理されました。イベントは非同期で処理されます。これが成功のレスポンスです。
400 Bad Request: リクエストの形式が正しくありません。ペイロードの JSON 構造や必須キーの欠落などを確認してください。レスポンスボディに詳細なエラーメッセージが含まれることが多いです。
401 Unauthorized: アクセストークンが無効、または期限切れです。トークンを再取得してリクエストを再試行する必要があります。
403 Forbidden: 認証は成功しましたが、要求された操作を実行する権限がありません。インストール済みパッケージの権限スコープを確認してください。

API コールを行うクライアント側では、これらのステータスコードに応じてログ出力、アラート通知、リトライ処理などを適切に実装することが重要です。

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

本記事では、Salesforce Integration Engineer の視点から、Marketing Cloud REST API を用いて Journey Builder と外部システムを連携させる方法を解説しました。認証からイベント発火までのプロセス、具体的なコード例、そして実装における注意点を網羅しました。

この連携を成功させるためのベストプラクティスを以下にまとめます。

専用の API ユーザーとパッケージ: 連携ごとに専用のインストール済みパッケージを作成し、必要最小限の権限を割り当てます。これにより、セキュリティリスクを最小化し、問題発生時の影響範囲を特定しやすくなります。
認証情報の安全な管理: Client ID や Client Secret、アクセストークンなどの認証情報は、コード内にハードコーディングせず、AWS Secrets Manager や Azure Key Vault のようなシークレット管理サービス、または安全な環境変数を使用して管理します。
スケーラブルな設計: 将来のトラフィック増加を見越して、API のレート制限を考慮した設計を行います。非同期処理やキューイングメカニズムの導入を検討し、システムのボトルネックとならないようにします。
詳細なロギング: API リクエストの内容、レスポンスのステータスコード、エラーメッセージなどを詳細にログとして記録します。これにより、障害発生時の原因調査が迅速に行えます。
徹底したテスト: 本番環境にデプロイする前に、Marketing Cloud のサンドボックス環境やテスト用のビジネスユニットを使用して、正常系・異常系の両方のシナリオを十分にテストします。特に、データ形式の違いや境界値のテストは重要です。

Marketing Cloud REST API を活用することで、顧客接点をリアルタイムで捉え、パーソナライズされたマーケティングオートメーションを実現できます。私たち統合エンジニアは、これらの技術を深く理解し、ビジネス価値を最大化する堅牢でスケーラブルなシステム連携を構築する責務を担っています。

にゃんこのSalesforce日記

このブログを検索