Salesforce Marketing Cloud REST API：認証とデータエクステンション連携の完全ガイド

背景と応用シナリオ

Salesforce 統合エンジニア (Salesforce Integration Engineer) として、私たちは日々、様々なシステム間のデータ連携という課題に取り組んでいます。特に Salesforce Marketing Cloud (以下、Marketing Cloud) は、企業のマーケティング活動の中核を担うプラットフォームであり、外部システムとのシームレスな連携がビジネスの成否を分けることも少なくありません。例えば、基幹システム (ERP) の購買データをリアルタイムで Marketing Cloud に連携し、購入後のフォローアップジャーニーを起動する、あるいは自社のウェブサイトで管理している会員情報を同期して、パーソナライズされたメールコンテンツを配信するといったシナリオは非常に一般的です。

これらの連携を実現するための最も強力なツールが、Marketing Cloud が提供する REST API (Representational State Transfer Application Programming Interface) です。この API を活用することで、外部アプリケーションからプログラムを通じて Marketing Cloud 内のデータや機能に安全にアクセスし、操作することが可能になります。しかし、その強力な機能を利用するためには、まず最初の関門である「認証」プロセスを正しく理解し、実装する必要があります。

本記事では、Salesforce 統合エンジニアの視点から、Marketing Cloud REST API の認証プロセス、特に OAuth 2.0 (オーオース 2.0) を利用したアクセストークンの取得方法と、そのトークンを使って最も頻繁に操作対象となる Data Extension (データエクステンション) からデータを取得する具体的な手順を、公式ドキュメントに基づいたコードサンプルと共に詳細に解説します。

原理説明

Marketing Cloud REST API との通信は、すべて OAuth 2.0 プロトコルに基づいた認証を必要とします。これは、ユーザー名とパスワードを直接 API リクエストに含めるのではなく、一時的な効力を持つ Access Token (アクセストークン) を使用してリクエストを認証する、安全性の高い仕組みです。

連携プロセス全体の流れは、大きく分けて以下の2つのステップで構成されます。

1. API インテグレーションの準備 (Marketing Cloud 側での設定)

まず、Marketing Cloud の管理画面 ([セットアップ] > [プラットフォームツール] > [アプリケーション] > [インストール済みパッケージ]) で、API 連携用の「インストール済みパッケージ」を作成します。このパッケージは、外部アプリケーションが Marketing Cloud API と通信するための窓口となります。

パッケージ作成時に重要なのは、以下の情報を取得し、安全に保管することです。

Client ID (クライアントID): アプリケーションを識別するための一意の ID。
Client Secret (クライアントシークレット): アプリケーションのパスワードに相当する秘密情報。
Authentication Base URI (認証ベース URI): アクセストークンを要求するための専用エンドポイントのドメイン部分。テナントごとに固有のサブドメイン (例: `https://your-subdomain.auth.marketingcloudapis.com/`) が割り当てられます。

さらに、このパッケージに「コンポーネント」として「API インテグレーション」を追加し、これから行う操作に必要な「スコープ (権限)」を付与します。例えば、Data Extension からデータを読み取るだけであれば、「データ > データエクステンション > 読み取り」の権限をチェックします。最小権限の原則に従い、必要な権限のみを付与することがセキュリティ上推奨されます。

2. アクセストークンの取得と API コール

設定が完了したら、いよいよプログラムから API を呼び出します。その手順は以下の通りです。

ステップ A: アクセストークンの要求
先ほど取得した Client ID, Client Secret, そして Authentication Base URI を使用して、Marketing Cloud の認証サーバー (`/v2/token` エンドポイント) に POST リクエストを送信します。リクエストボディには、認証タイプ (`grant_type`) や Client ID/Secret などの情報を含めます。認証に成功すると、レスポンスとして JSON 形式でアクセストークンと、その有効期限 (`expires_in`、秒単位) などが返却されます。

ステップ B: API リソースへのアクセス
取得したアクセストークンを、HTTP リクエストの `Authorization` ヘッダーに `Bearer [アクセストークン]` の形式で含めることで、Marketing Cloud の各種 API エンドポイントにアクセスできるようになります。例えば、特定の Data Extension からデータを取得したい場合は、その Data Extension の外部キーを指定して、データ取得用のエンドポイントに GET リクエストを送信します。

この2段階のプロセスにより、機密情報である Client Secret がリソースアクセスのたびにネットワーク上を流れることを防ぎ、安全な通信を実現しています。

示例代码

ここでは、実際に API を利用してアクセストークンを取得し、それを用いて特定の Data Extension からデータを取得するまでのコード例を、Salesforce 公式ドキュメントに基づいて示します。

1. アクセストークンの取得 (Request an Access Token)

まず、認証サーバーに対してアクセストークンを要求する POST リクエストを送信します。`your-subdomain` の部分は、ご自身の Marketing Cloud テナントの認証ベース URI に置き換えてください。

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_ACCOUNT_MID"
}

コードの解説:

POST /v2/token: アクセストークンを取得するための固定エンドポイントです。
Host: インストール済みパッケージで確認した「認証ベース URI」のホスト名です。
Content-Type: application/json: リクエストボディが JSON 形式であることを示します。
grant_type: "client_credentials": サーバー間の連携で最も一般的に使用される認証フローを指定します。
client_id: インストール済みパッケージのクライアント ID を指定します。
client_secret: インストール済みパッケージのクライアントシークレットを指定します。
account_id: (任意ですが推奨) 対象となるビジネスユニットの MID (Member ID) を指定します。これにより、トークンが特定のビジネスユニットに紐づけられます。

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

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "data_extensions_read",
  "rest_instance_url": "https://your-subdomain.rest.marketingcloudapis.com/"
}

この `access_token` と `rest_instance_url` を次のステップで使用します。

2. Data Extension の行を取得 (Retrieve Data Extension Rows by Key)

次に、取得したアクセストークンを使って、特定の Data Extension からデータを取得します。ここでは、外部キー (External Key) が `Contact_Info_DE` である Data Extension を対象とします。

GET /data/v1/customobjectdata/key/Contact_Info_DE/rowset HTTP/1.1
Host: your-subdomain.rest.marketingcloudapis.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

コードの解説:

GET /data/v1/customobjectdata/key/{key}/rowset: Data Extension の行セットを取得するためのエンドポイントです。`{key}` の部分を対象の Data Extension の外部キーに置き換えます。
Host: 前のステップで取得した `rest_instance_url` のホスト名です。
Authorization: Bearer YOUR_ACCESS_TOKEN: これが認証の核となる部分です。「Bearer」という文字列に続けて、先ほど取得したアクセストークンを指定します。

このリクエストが成功すると、Data Extension 内のデータが JSON 配列として返されます。

{
    "items": [
        {
            "keys": {
                "email": "sample1@example.com"
            },
            "values": {
                "firstName": "Taro",
                "lastName": "Salesforce"
            }
        },
        {
            "keys": {
                "email": "sample2@example.com"
            },
            "values": {
                "firstName": "Hanako",
                "lastName": "Marketing"
            }
        }
    ],
    "page": 1,
    "pageSize": 50,
    "count": 2,
    "links": {}
}

これで、外部システムから Marketing Cloud の Data Extension データをプログラム経由で取得することができました。

注意事項

Marketing Cloud API を利用した連携を安定的に運用するためには、いくつかの重要な点に注意する必要があります。

権限 (Permissions)

API が期待通りに動作しない最も一般的な原因の一つが、権限不足です。インストール済みパッケージに設定されたスコープが、実行したい API 操作に対して十分であることを必ず確認してください。例えば、Data Extension にデータを書き込みたい場合は「データ > データエクステンション > 書き込み」(`data_extensions_write`) のスコープが必要です。エラーレスポンスで "authorization" や "permission" に関するメッセージが返された場合は、まずスコープ設定を見直しましょう。

API 制限 (API Limits)

Salesforce の他の製品と同様に、Marketing Cloud API にも利用制限 (ガバナ制限) が存在します。例えば、1分間あたりに実行できる API コール数などです。大量のデータを扱うバッチ処理などを設計する際には、これらの制限に抵触しないよう、API コールを適切な間隔で実行したり、一度に大量のデータを処理できるバルク系の API エンドポイントの利用を検討したりする必要があります。最新の制限値については、必ず公式のデベロッパー向けドキュメントで確認してください。

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

API 連携は常に成功するとは限りません。ネットワークの問題、不正なリクエスト、サーバー側の障害など、様々な理由でエラーが発生する可能性があります。堅牢な連携を構築するためには、API レスポンスの HTTP ステータスコードを常にチェックし、エラー発生時には適切な処理を行うロジックを実装することが不可欠です。例えば、`401 Unauthorized` が返された場合はアクセストークンの期限切れが考えられるため、トークンを再取得してリクエストをリトライする、`5xx` 系のサーバーエラーが返された場合は、時間を置いてから再試行する (指数バックオフ) といった処理を組み込みます。

トークン管理 (Token Management)

アクセストークンには有効期限 (`expires_in`) があります。API を呼び出すたびに新しいトークンを取得するのは非効率であり、API 制限にも抵触しやすくなります。ベストプラクティスは、一度取得したアクセストークンを有効期限が切れるまでキャッシュし、再利用することです。トークンの有効期限が近づいている、もしくは期限切れによって `401` エラーを受け取った場合にのみ、新しいトークンを再取得するように実装します。

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

本記事では、Salesforce 統合エンジニアの視点から、Marketing Cloud REST API の認証プロセスの基本と、Data Extension からデータを取得する具体的な方法を解説しました。OAuth 2.0 による認証は一見複雑に思えるかもしれませんが、一度その流れを理解すれば、様々な連携シナリオに応用できる非常に強力な基盤となります。

最後に、安定した API 連携を構築するためのベストプラクティスをいくつかまとめます。

認証情報の安全な保管: Client ID や Client Secret は、コード内にハードコーディングするのではなく、環境変数や、Salesforce Platform であれば「指定ログイン情報 (Named Credentials)」のような、安全な場所に保管してください。
ロギングの徹底: API リクエストの内容、レスポンスのステータスコードとボディを詳細にログとして記録することで、問題発生時の原因調査が格段に容易になります。
適切なエンドポイントの選択: Marketing Cloud には、単一レコードを操作する API だけでなく、複数のレコードを一度に処理する非同期のバルク API も用意されています。用途に応じて最適なエンドポイントを選択することで、パフォーマンスを向上させ、API 制限を回避できます。
公式ドキュメントの活用: API の仕様や制限は変更される可能性があります。常に developer.salesforce.com の公式ドキュメントを参照し、最新の情報を基に実装を行うことを心がけてください。

これらの原理とベストプラクティスを理解し、実践することで、Marketing Cloud をハブとした、信頼性の高いデータ連携基盤を構築することができるでしょう。

にゃんこのSalesforce日記

このブログを検索