Salesforce Marketing Cloud REST API連携のステップバイステップガイド

執筆者：Salesforce 統合エンジニア (Salesforce Integration Engineer)

背景と適用シナリオ

現代のデジタルマーケティングにおいて、顧客データは施策の成否を分ける最も重要な資産です。多くの企業では、顧客データが Sales Cloud、サービス、Eコマースプラットフォーム、基幹システムなど、複数のシステムに散在しています。これらのデータを Salesforce Marketing Cloud に集約し、一貫性のあるパーソナライズされた顧客体験を提供することが、エンゲージメント向上の鍵となります。

Salesforce 統合エンジニアとして、私たちの重要な責務の一つは、これらの分散したシステムと Marketing Cloud との間に、シームレスで信頼性の高いデータ連携を構築することです。例えば、以下のようなシナリオが考えられます。

リアルタイムな顧客データ同期：Eコマースサイトで新規会員登録があった際、その顧客情報をリアルタイムで Marketing Cloud のデータエクステンション (Data Extension) に追加し、即座にウェルカムジャーニーを開始させる。
購買データの連携：顧客が商品を購入した際に、その購買履歴データを Marketing Cloud に連携し、購入後のフォローアップメールや関連商品のレコメンデーションに活用する。
外部システムからのイベントトリガー：外部の在庫管理システムで「人気商品が再入荷した」というイベントが発生した際、その情報をトリガーとして Marketing Cloud のジャーニーを起動し、入荷待ちをしていた顧客リストへ一斉に通知を送る。

これらのシナリオを実現するために中心的な役割を果たすのが、Marketing Cloud が提供する REST API (Representational State Transfer Application Programming Interface) です。この API を利用することで、外部システムからプログラムを通じて Marketing Cloud のデータや機能を安全に操作できるようになります。本記事では、統合エンジニアの視点から、Marketing Cloud REST API を利用した連携の基本的な仕組みと実装方法について、具体的に解説していきます。

原理説明

Marketing Cloud REST API を利用した連携は、大きく分けて「認証」と「APIリクエスト」の2つのステップで構成されます。まずは、この基本原理を理解することが重要です。

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

Marketing Cloud の API は、OAuth 2.0 という業界標準のプロトコルで保護されています。外部アプリケーションが API にアクセスするためには、まず「アクセストークン (Access Token)」と呼ばれる一時的な鍵を取得する必要があります。このトークンは、リクエストが正当なアプリケーションから送られたものであることを証明する役割を果たします。

アクセストークンを取得する手順は以下の通りです。

インストール済みパッケージ (Installed Package) の作成：Marketing Cloud の [セットアップ] > [アプリケーション] > [インストール済みパッケージ] から、API連携用のパッケージを作成します。このパッケージは、API連携を行うアプリケーションの「身分証明書」のようなものです。
API 連携コンポーネントの追加：作成したパッケージに「API 連携」コンポーネントを追加し、サーバー間 (Server-to-Server) 連携タイプを選択します。
スコープ (Scope) の設定：API を通じて実行したい操作の権限（スコープ）を設定します。例えば、データエクステンションへのデータの読み書きを行いたい場合は、「データ > データエクステンション」の「読み取り」および「書き込み」権限を付与します。
認証情報 (Credentials) の取得：パッケージの作成が完了すると、クライアントID (Client ID)、クライアントシークレット (Client Secret)、そしてテナント固有の認証ベースURI (Authentication Base URI) が発行されます。これらの情報は、アクセストークンを取得するための重要な認証情報であり、厳重に管理する必要があります。
トークンリクエスト：取得した認証情報を使って、Marketing Cloud の認証エンドポイント (/v2/token) に POST リクエストを送信します。リクエストが成功すると、レスポンスとしてアクセストークンと、その有効期限 (expires_in) が返却されます。

このアクセストークンを、後続のすべての API リクエストの HTTP ヘッダーに含めることで、Marketing Cloud はリクエストを認証します。

2. APIリクエスト：エンドポイントへのデータ送信

アクセストークンを取得したら、次はいよいよ目的の操作を行うための API リクエストを送信します。Marketing Cloud REST API には、様々なリソースを操作するための「エンドポイント (Endpoint)」が用意されています。

例えば、データエクステンションに行を挿入する場合、一般的に /data/v1/async/dataextensions/{key}/rows というエンドポイントを使用します。ここで {key} は、対象となるデータエクステンションの外部キー (External Key) に置き換えます。

リクエストの構成要素は以下の通りです。

HTTP メソッド：操作の種類を指定します。データの作成や追加には POST、更新には PUT や PATCH、取得には GET、削除には DELETE を使用します。
エンドポイント URL：操作対象のリソースを指定する URL です。テナント固有の REST ベース URI に、特定のエンドポイントパスを連結します。
HTTP ヘッダー：認証情報やリクエストボディの形式を指定します。最低限、Authorization ヘッダーに Bearer [アクセストークン] を、Content-Type ヘッダーに application/json を指定する必要があります。
リクエストボディ (Payload)：送信するデータ本体です。JSON 形式で、API の仕様に沿った構造で記述します。データエクステンションへの行挿入の場合、追加したい行のデータを配列として含めます。

このリクエストを Marketing Cloud の API サーバーに送信し、サーバーがリクエストを正常に処理すると、成功を示す HTTP ステータスコード (例: 202 Accepted) と、処理結果に関する情報を含むレスポンスボディが返されます。

示例代码

ここでは、具体的に2つのステップのコード例を示します。1つ目はアクセストークンを取得するリクエスト、2つ目はそのトークンを使用してデータエクステンションに非同期でデータを挿入するリクエストです。

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

まず、Marketing Cloud の認証エンドポイントに対して、クライアントIDとクライアントシークレットを送信し、アクセストークンを取得します。以下のコードは、cURL を使用したリクエストの例です。

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: アクセストークンを取得するためのエンドポイントと HTTP メソッドです。
Host: {YOUR_SUBDOMAIN}.auth.marketingcloudapis.com: インストール済みパッケージから取得したテナント固有の「認証ベースURI」を指定します。
Content-Type: application/json: リクエストボディが JSON 形式であることを示します。
grant_type: "client_credentials": サーバー間連携でトークンを取得する際の OAuth 2.0 のグラントタイプです。固定値として指定します。
client_id: インストール済みパッケージのクライアントIDに置き換えます。
client_secret: インストール済みパッケージのクライアントシークレットに置き換えます。
account_id: (任意ですが推奨) 操作対象のビジネスユニットの MID (Member ID) を指定します。これにより、トークンが特定のビジネスユニットに紐づけられます。

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

{
    "access_token": "xxxxxxxxxxxxxxxxxxxx",
    "token_type": "Bearer",
    "expires_in": 1080,
    "scope": "data_extensions_read data_extensions_write",
    "rest_instance_url": "https://{YOUR_SUBDOMAIN}.rest.marketingcloudapis.com/"
}

このレスポンスに含まれる access_token と rest_instance_url を次のステップで使用します。

2. データエクステンションへの非同期での行挿入

次に、取得したアクセストークンを使って、特定のデータエクステンションに新しい行を挿入します。大量のデータを扱う場合は、サーバーの応答を待たずにリクエストを完了できる非同期 API の利用が推奨されます。

POST /data/v1/async/dataextensions/key:{YOUR_DATA_EXTENSION_EXTERNAL_KEY}/rows
Host: {YOUR_SUBDOMAIN}.rest.marketingcloudapis.com
Authorization: Bearer {YOUR_ACCESS_TOKEN}
Content-Type: application/json

{
   "items": [
      {
         "FirstName": "John",
         "LastName": "Smith",
         "Email": "john.smith@salesforce.com"
      },
      {
         "FirstName": "Jane",
         "LastName": "Doe",
         "Email": "jane.doe@salesforce.com"
      }
   ]
}

コード解説：

POST /data/v1/async/dataextensions/key:{YOUR_DATA_EXTENSION_EXTERNAL_KEY}/rows: データエクステンションに行を非同期で挿入するためのエンドポイントです。{YOUR_DATA_EXTENSION_EXTERNAL_KEY} の部分を、対象となるデータエクステンションの外部キーに置き換えます。
Host: {YOUR_SUBDOMAIN}.rest.marketingcloudapis.com: トークン取得時のレスポンスに含まれていた rest_instance_url のホスト部分を指定します。
Authorization: Bearer {YOUR_ACCESS_TOKEN}: HTTP 認証ヘッダーです。Bearer の後に、ステップ1で取得したアクセストークンを付与します。
items: 挿入したいデータの配列です。各オブジェクトはデータエクステンションの一行に対応します。オブジェクトのキーはデータエクステンションの列名（フィールド名）と一致させる必要があります。

非同期リクエストのため、この API は即座に 202 Accepted ステータスコードとリクエストIDを返します。実際のデータ挿入処理はバックグラウンドで実行されます。

注意事項

API 連携を実装する際には、以下の点に注意する必要があります。

権限 (Permissions)：インストール済みパッケージに設定するスコープは、必要最小限の原則に従ってください。データ挿入のみが必要な連携であれば、「書き込み」権限のみを付与し、「読み取り」や「削除」の権限は与えないようにすることで、セキュリティリスクを低減できます。
API 制限 (API Limits)：Marketing Cloud の API には、1分間あたりや1日あたりのコール数に制限があります。この制限を超えると、API リクエストが一時的にブロック（スロットリング）される可能性があります。大量のデータを扱う場合は、API コール数を抑えるために一度のリクエストで複数行をまとめて送信するバルク処理を実装したり、非同期 API を活用したりするなどの工夫が必要です。
エラーハンドリング (Error Handling)：API 連携は常に成功するとは限りません。ネットワークの問題、認証情報の誤り、リクエストデータの形式不良など、様々な原因でエラーが発生します。API のレスポンスに含まれる HTTP ステータスコード（例：400 Bad Request, 401 Unauthorized, 403 Forbidden, 500 Internal Server Error）を必ず確認し、エラーの種類に応じた再試行ロジックや、管理者への通知機能を実装することが、安定したシステム運用には不可欠です。
認証情報の管理：クライアントIDとクライアントシークレットは、パスワードと同様に機密情報です。ソースコード内に直接ハードコーディングするのではなく、環境変数やセキュアなクレデンシャル管理システム（例: AWS Secrets Manager, Azure Key Vault）を利用して、安全に保管・管理してください。

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

Salesforce Marketing Cloud の REST API は、外部システムとのデータ連携を実現し、マーケティング活動を自動化・高度化するための強力なツールです。統合エンジニアとして、その仕組みを正しく理解し、堅牢な連携を構築することが求められます。

最後に、API 連携を成功させるためのベストプラクティスをまとめます。

目的の明確化と適切な API の選定：「何をしたいのか」を明確にし、それに最も適した API（REST/SOAP）やエンドポイントを選定します。大量データ処理には非同期 API、単一の即時性が求められる処理には同期 API を使い分けるなど、特性を理解した上で設計します。
アクセストークンの効率的な管理：アクセストークンには有効期限があります。毎回リクエストのたびに新しいトークンを取得するのではなく、取得したトークンを有効期限が切れるまでキャッシュして再利用することで、不要な認証リクエストを減らし、パフォーマンスを向上させることができます。
包括的なロギング：API リクエストの内容、レスポンスのステータスコード、レスポンスボディ、処理時間などを詳細にログとして記録します。問題が発生した際に、原因の特定とデバッグを迅速に行うための重要な情報源となります。
スケーラビリティを考慮した設計：将来的なデータ量の増加やリクエスト頻度の増大を見越して、API 制限に抵触しないような設計を心がけます。キューイングシステムを導入してリクエストを平準化するなどのアーキテクチャも検討しましょう。

これらの原理とベストプラクティスを踏まえ、安全で効率的な Marketing Cloud 連携を実装し、ビジネス価値の最大化に貢献していきましょう。

にゃんこのSalesforce日記

このブログを検索