開発者環境の設定

学習の目的

この単元を完了すると、次のことができるようになります。

• さまざまな種別の連携コンポーネントについて説明する。
• Marketing Cloud Engagement アカウントで拡張されたインストール済みパッケージを作成する。
• API 連携の認証のための資格情報を取得する。

何も開発しないままでこのバッジが終わってしまうのではないかと思いましたか?心配はいりません。Marketing Cloud Engagement の開発者ツールや管理概念について学習したことを活用するときが来ました。この単元では、開発者環境を設定する手順について順を追って説明します。そして、次の単元では、セットアップを検証するための簡単なプロジェクトを試します。 

これらの手順を Marketing Cloud Engagement アカウントで実行してみたいですか? このモジュールの手順を実行するには、インストール済みパッケージに対する「管理」権限が必要です。この権限を有効にするには、Marketing Cloud Engagement 管理者にお問い合わせください。

パッケージの作成

開発者環境を設定する最初のステップは、Marketing Cloud Engagement アカウントでインストール済みパッケージを作成することです。パッケージとは、カスタム機能を作成、管理するコンポーネントで構成されるコンテナです。つまり、パッケージで何ができるかはコンポーネントによって決まります。 

なぜパッケージを作成するのでしょうか? パッケージを使用すると、たとえば API 連携を作成したり、カスタムアプリケーションをインストールしたり、カスタム Journey Builder コンポーネントを追加したりでき、そのすべてを Marketing Cloud Engagement アカウント内の他のビジネスユニットと共有できます。パッケージを作成する理由の例として次のものが挙げられます。

このテストでは、拡張パッケージの開発環境を設定します。 

1. Marketing Cloud Engagement で、[Setup (セットアップ)] に移動します。
2. [プラットフォームツール] で、[アプリ] を展開し、[インストール済みパッケージ] をクリックします。
3. [新規] をクリックします。
4. パッケージに名前と説明を入力して、最初のパッケージだと簡単にわかるようにします。
5. パッケージを保存します。パッケージが保存されると、パッケージの詳細を表示できます。
6. [コンポーネント] で、[コンポーネントの追加] をクリックします。
7. このステップでは、コンポーネントの種別を選択します。今回のテストには、[API 連携] を選択します。

連携の種別

次に連携の種別を [Web アプリ]、[公開アプリ]、[サーバー間] から選択します。これらの種別の連携では、OAuth 2.0 プロトコルを使用してアクセストークンを取得します。それぞれについて簡単に説明します。

今回のテストでは、[サーバー間] を選択して [次へ] をクリックします。

プロパティの設定

コンポーネント追加の最後の手順では、プロパティを設定する必要があります。連携内に含めるプラットフォーム機能のスコープを有効にします。この API 連携では連絡先の更新を許可しますか? 新しいメールを作成しますか? API スコープは、API 要求が適切な機能にアクセスできるようにする権限のグループを表します。プロパティには、Web アプリと公開アプリのリダイレクト URI を含めることもできます。

今回のテストでは、[連絡先] の [オーディエンス] と [リストと購読者] の両方で [書き込み] アクセス権が有効になっていることを確認します。 

[保存] をクリックしてコンポーネントを終了します。

保存した後に、スコープを変更する必要が生じても、問題ありません。[編集] をクリックし、必要に応じてスコープを調整します。各ルートに必要なスコープを理解するには、Salesforce Developers の「REST API Permission IDs and Scopes (REST API の権限 ID とスコープ)」を参照してください。

資格情報の取得

パッケージが作成され、コンポーネントが追加されたので、次は連携に使用する認証の資格情報を指定する必要があります。簡単です。インストール済みパッケージで API 連携を作成すると、Marketing Cloud Engagement 認証サーバーでクライアント ID とクライアントシークレットが生成されます。先ほど作成したインストール済みパッケージのコンポーネントを確認してみましょう。クライアント ID とクライアントシークレットがある場合は、コンポーネントの詳細の下に表示されます。 

上の画像でクライアント ID とクライアントシークレットがぼかしてあるのはなぜなのか不思議に思うかもしれません。クライアント ID とクライアントシークレットは、常に安全に保存する必要があります。この情報を JavaScript 経由でクライアント側に公開したり、モバイルアプリケーションに保存したりしないでください。

サーバー間連携のアクセストークン

クライアント資格情報フローでは、クライアントアプリケーションはクライアント ID とクライアントシークレットを使用して Marketing Cloud Engagement 認証サーバーからアクセストークンを要求します。アクセストークンによって、Marketing Cloud Engagement の REST サービスと SOAP サービスへのアクセス権がアプリケーションに付与されます。(クライアント資格情報の許可種別では、更新トークンはありません。) 

このしくみは次のとおりです。

1. アプリケーションは、Marketing Cloud Engagement で作成したパッケージ用に生成されたクライアント ID とクライアントシークレットを提供することでアクセストークンを要求します。
2. Marketing Cloud Engagement 認証サーバーはアクセストークンを返し、アプリケーションはこれを抽出します。
3. アプリケーションはアクセストークンを使用して、Marketing Cloud Engagement リソースや、トークン応答の一部として返された REST または SOAP ベース URL にアクセスします。

では、アプリケーションは、この単元で取り上げているサーバー間連携のアクセストークンをどのようにして要求するのでしょうか? インストール済みパッケージで API 連携を作成したときに提供された認証ベース URI に v2/token を追加して、要求の静的エンドポイントを作成します。インストール済みパッケージで API 連携を作成したときに提供されたクライアント ID とクライアントシークレットを提供して、アクセストークンを要求します。

アクセストークンの有効期限が切れた場合、アプリケーションは前回と同じ v2/token ルートを使用して新しいアクセストークンを要求する必要があります。アクセストークンの有効期間は 20 分です。次に要求の例を示します。

Host: https://YOUR_SUBDOMAIN.auth.marketingcloudapis.com
POST /v2/token
Content-Type: application/json
{
"grant_type": "client_credentials",
"client_id": "7a9j47upktedde30uedl822p",
"client_secret": "1955278925675241571",
"scope": "list_and_subscribers_write audiences_write",
"account_id": "12345"
}

この例では、API 要求に対して有効になっている権限がスコープに反映されていて、アカウント ID はアカウントの MID になっています。

次に、Marketing Cloud Engagement がアクセストークンを返します。アプリケーションはアクセストークンを抽出して安全に保存する必要があります。次に応答の例を示します。

HTTP/1.1 200 OK
{
"access_token":"eyJhbLciOiJIPzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjIifQ.eyJhY2Nlc3NfdG9rZW4iOiJhYmJUQTlpSHZqRjkyd3Jkb0xWZEFCaloiLCJjbGllbnRfaWQiOiI3ZTRmYW1xaWUzcWtzdzlhNDRrcmxvZDgiLCJlaWQiOjEwNzU3Njc2LCJzdGFja19rZXkiOiJRQTFTMSJ9.wSFfEdeNrkoiU_tnmJ2ihm8iUqnJKlZoI3GlavTGBhs.hU4EsiC1e9txh_TCt90YlI2l7xZZ5E6_oa0xku3Jj9CCk1B72M4bhO3kUIyhwfVuB0MFbL0y9KD_RRFzg-nuqPgjPyONnby-iWopdZPBHd-3woupxCMST5-vfJO9qAED9qiUfYLS4WmHRuJTCX4NPScyu8BdROTVEe-D3iAoAeFoJX_rLZ9d5eEhIn1AvkYgoj9siuxAprHEvmySTgNIXkQA6uT_IQ-H1dbfOyJmlFKpYzvhvHb0KH7NJ24zy5bd2MQ5",
"expires_in":1200,
"token_type":"Bearer",
"rest_instance_url":"mc563885gzs27c5t9-63k636tzgm.rest.marketingcloudapis.com",
"soap_instance_url":"mc563885gzs27c5t9-63k636tzgm.soap.marketingcloudapis.com",
"scope": "list_and_subscribers_write audiences_write"
}

試してみる準備はできていますか? 次の単元では、セットアップを検証するための簡単な Marketing Cloud Engagement プロジェクトの手順を説明します。

リソース

• Salesforce 開発者: Access Token for Server-to-Server Integrations (サーバー間連携のアクセストークン)
• Salesforce 開発者: 拡張されたパッケージでの OAuth 2.0 API 連携の作成
• Salesforce 開発者: Marketing Cloud Engagement Developers の「Get Started (はじめに)」
• Salesforce 開発者: Installed Package Definitions (インストール済みパッケージの定義)
• Salesforce 開発者: REST API Permission IDs and Scopes (REST API の権限 ID とスコープ)