開発者環境の設定

学習の目的

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

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

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

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

パッケージの作成

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

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

コンポーネント	パッケージを作成する理由
API 連携	サードパーティアプリケーションとの連携を作成し、そのために Marketing Cloud Engagement REST API へのアクセスが必要である。クライアント ID とクライアントシークレットを取得するには、API 連携コンポーネントを含むインストール済みパッケージを作成します。パッケージごとに1 つの API 連携を作成できます。
Marketing Cloud Engagement アプリケーション	Marketing Cloud Engagement 外でアプリケーションを作成し、Marketing Cloud Engagement に iFrame を使用して挿入したい。Marketing Cloud Engagement アプリケーションコンポーネントを含むインストール済みパッケージを作成します。パッケージごとに 1 つの Marketing Cloud Engagement アプリケーションを使用できます。アプリケーションが Marketing Cloud Engagement API にアクセスする必要がある場合は、API 連携コンポーネントも作成します。
カスタムコンテンツブロック	HTML の編集に Content Builder の CKEditor WYSIWYG を使用する代わりに、異なる WYSIWYG (QuillJS など) を使用したい。カスタムコンテンツブロックコンポーネントを含むインストール済みパッケージを作成します。
Journey Builder アクティビティ	ジャーニーで、サードパーティアプリケーション内の REST API 要求を起動するカスタムアクティビティが必要である。Journey Builder アクティビティコンポーネントを含むインストール済みパッケージを作成します。パッケージごとに複数の Journey Builder アクティビティを含めることができます。
Journey Builder エントリソース	ジャーニーで、サードパーティアプリケーションからの REST API 要求を使用したカスタムエントリソースが必要である。Journey Builder エントリソースコンポーネントを含むインストール済みパッケージを作成します。パッケージごとに複数の Journey Builder エントリソースを含めることができます。

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

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

連携の種別

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

連携の種別	説明	OAuth 許可種別
Web アプリ	Web アプリは、エンドユーザーのコンテキストで API 要求を実行します。これらの連携では、クライアントシークレットの機密性を維持できるため、クライアント ID とクライアントシークレットが発行されます。	認証コード
公開アプリ	公開アプリ (単一ページまたはモバイルアプリケーションなど) は、エンドユーザーのコンテキストで API 要求を実行します。これらの連携ではクライアントシークレットの機密性を維持できないため、クライアント ID のみが発行されます。	認証コード
サーバー間	サーバー間連携は、エンドユーザーコンテキスト、ユーザーのインタラクション、ユーザーインターフェースなしで、連携の代わりにタスクを実行します。ユーザーアカウントではなくサービスアカウントのコンテキストで API 要求を実行します。これらの連携ではクライアント資格情報の許可種別で使用するクライアント ID とクライアントシークレットが発行されます。	クライアント資格情報

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

プロパティの設定

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

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

[連絡先] の [オーディエンス] と [リストと購読者] の [書き込み] アクセス権が有効になっているスコープ編集インターフェース

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

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

資格情報の取得

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

コンポーネントの詳細で [クライアント ID] と [クライアントシークレット] が強調表示されているインストール済みパッケージの詳細ページ

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

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

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

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

アプリケーションは、Marketing Cloud Engagement で作成したパッケージ用に生成されたクライアント ID とクライアントシークレットを提供することでアクセストークンを要求します。
Marketing Cloud Engagement 認証サーバーはアクセストークンを返し、アプリケーションはこれを抽出します。
アプリケーションはアクセストークンを使用して、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 プロジェクトの手順を説明します。

開発者環境の設定

学習の目的

パッケージの作成

資格情報の取得

リソース