実装で学ぶ Adobe Campaign Standard API – 開発の準備編 #AdobeIO

コンテンツ

概要

前回 Experience Cloud ソリューションを紹介しましたが、今回は早速 Adobe Campaign Standard（以下ACS）の API を使用する開発環境の準備について説明したいと思います。

技術的な要件

ACS の API はサーバ間の API 通信にのみ使用できます。
また、ACS の API の使用はレート制限が適用されるため、このレート制限を超過する可能性があるようであれば、実装する前に API の使用計画を Adobe の担当者に一度ご相談ください。

インスタンスの準備

まず、必要になるのは、ACS のインスタンスへのアクセスです。Creative Cloud の API は Adobe ID を取得していればアクセスできる物が多いと思いますが、Adobe Campaign のように Experience Cloud のソリューションは基本的にご購入頂いている場合のみアクセス可能です。そのほか、Adobe のパートナー様であれば ACS にアクセスできる場合があります。Adobe の実装パートナー様の場合、プロジェクト関係者に権限を付与された後に、API にアクセスできます。また、Adobe の Solution Partner Program（SPP）のパートナー様は、SPP ポータルの Experience Cloud Sandbox ページからセルフサービスで ACS のインスタンスアクセスを申請できます。以下、これらの方法で ACS にアクセスする事ができます。

必要なユーザーアカウントと権限

ACS の API を運用する上で Adobe I/O で公開鍵証明書を管理する必要があります。そのため、API 連携の管理者アカウントは Experience Cloud 上の所属組織で「システム管理者」権限を付与されている事を確認してください。また、API で ACS のインスタンスを制御するには、操作するコンポーネントやサービスによって必要なユーザ権限が変わりますが、今後の連載で ACS の関連コンポーネントを設定しやすくするために、ここでは ACS インスタンスの「Administrators」ユーザ権限を付与します。
必要な権限を以下にまとめます。スクリーンショットを合わせてご確認ください。


https://blogs.adobe.com/japan-conversations/files/2018/08/0-1-user-account-2.png

公開鍵証明書の作成

ACS の API にアクセスするには JSON Web Token（JWT）と呼ばれるアクセストークンを使用します。有効な JWT を生成するには、予め I/O コンソールに公開鍵証明書をアップロードする必要があります。
I/O Console が対応する公開鍵証明書の形式は CRT、CER、DER または PEM です。異なる有効期間の証明書を複数アップロードできますので、API アクセスの運用モデルに従って使用する証明書の種類と有効期間を決めます。例えば、アクセス元サーバ単位で API アクセスを管理する場合、ドメインの SSL 証明書を使うと良いでしょう。開発者単位で API アクセスを管理する場合、開発者の公開鍵証明書を使うと良いでしょう。証明書を持っていない場合、認証局から購入するか、自己署名証明書を作成します。
簡単ですがここでは自己署名証明書の作成方法を紹介します。

openssl がある Unix-alike 環境で、以下のコマンドを入力します。

openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout my-private.key -out my-certificate_pub.crt

openssl の応答に合わせて証明書の情報を入力します。私は以下を入力しました。

Country Name (2 letter code) [XX]:jp State or Province Name (full name) []:Tokyo Locality Name (eg, city) [Default City]:Osaki Organization Name (eg, company) [Default Company Ltd]:Adobe Organizational Unit Name (eg, section) []:Japan R&D Common Name (eg, your name or your server's hostname) []:example.com Email Address []:example@example.com

これで１年間有効な公開鍵証明書「my-certificate_pub.crt」が作成されます。

Adobe Campaign 連携の作成

ACS のインスタンスとユーザアカウントの準備ができたら、Adobe I/O で ACS にアクセスするための連携（Integration）を作成します。
https://www.adobe.io/ の、「Console」のリンクから Adobe I/O Console を開きます。ここでは作成済みの連携が表示されます。複数の組織に関わっている方は適切な組織を選んでください。「New integration」をクリックして新しい連携を作成します。


https://blogs.adobe.com/japan-conversations/files/2018/08/1-0-top-page.png

https://blogs.adobe.com/japan-conversations/files/2018/08/1-1-create-create-integration.png

この連携の目的を選びます。ACS の API にアクセスしたいので、「Access an API」を選択し、「Continue」をクリックします。


https://blogs.adobe.com/japan-conversations/files/2018/08/1-2-create-access-an-api.png

次は、Experience Cloud の下にある「Adobe Campaign」を選択し、「Continue」をクリックします。次の画面も「Continue」をクリックします。
もしここで「Adobe Campaign」を選択できない時は、アクセス権限を付与されていない可能性がありますので、プロジェクト関係者に相談してみてください。


https://blogs.adobe.com/japan-conversations/files/2018/08/1-3-create-adobe-campaign.png

https://blogs.adobe.com/japan-conversations/files/2018/08/1-4-create-create-new.png

次は連携の詳細設定です。

必要事項を記入し終わったら「Continue」をクリックし、次の画面で「Continue to integration details」をクリックします。


https://blogs.adobe.com/japan-conversations/files/2018/08/1-5-create-integration-details.png

https://blogs.adobe.com/japan-conversations/files/2018/08/1-6-create-integration-created.png

各連携には、固有のクライアント認証情報が含まれています。これらの資格情報は、アプリケーションを識別し、Adobe 製品に API アクセスを許可するために使われます。
この画面では連携の認証情報が色々とありますが、「API Key (Client ID)」は Adobe I/O に対しこの連携を識別するもので、すべての API コールに使われます。また、「Add a public key」をクリックする事でいつでも公開鍵証明書を追加できます。
続けて、上の「JWT」をクリックします。


https://blogs.adobe.com/japan-conversations/files/2018/08/1-7-integration-overview.png

それでは JWT を生成します。JWT は、識別情報と認証情報を秘密鍵で署名し API 連携に必要な資格情報をカプセル化した物です。この JWT を使って API のアクセストークンを生成する事ができます。
JWT の生成方法は、

  1. アップロードした公開鍵証明書に対応する秘密鍵を貼り付けます。JWT の生成はすべてブラウザ側で行われ、公開鍵証明書と秘密鍵の関連性の確認は行われないため、関係ない秘密鍵を使っていないか確認してください。
  2. 「Generate JWT」をクリックします
  3. JWT がブラウザ側の処理で生成されます（秘密鍵が Adobe に送信される事はありません）


https://blogs.adobe.com/japan-conversations/files/2018/08/1-8-1-jwt.png

左下に表示されているのが生成された JWT で、右下に表示されているのは JWT を使ってアクセストークンを生成する cURL のコマンドです。JWT はいつでもここで作る事ができますが、秘密鍵を変えない限りずっと使えますので、大切に保存しておくことをお勧めします


https://blogs.adobe.com/japan-conversations/files/2018/08/1-8-jwt.png

セキュリティ

各連携には、固有のクライアント認証情報が含まれています。これらの資格情報は、アプリケーションを識別し、Adobe 製品に API アクセスを許可するために使われます。
API キー（またはクライアント ID）は公開情報と考えられます。すべての API コールに API キーを含めて連携を識別する事ができます。
Client Secret や JWT は一種のパスワードとして考えられますので、取り扱いに注意が必要です。連携の資格情報を安全に保管するには、決してソースコードにそれらを含めたり、環境変数に含めたり、セキュリティで保護されていない電子メールや通信で送信したりしないでください。

サマリー

まとめますと、ACS の API を使う開発を始めるには以下のものが必要です：

開発そのものには必要ないですが、開発する前に注意すること：

今後連載のシナリオ

具体的な実装については次回の記事から詳しく説明しますが、キャンペーンを運営する上で３つの事例を用いて Adobe I/O によるマーケティングオートメーションを実現する方法を紹介していきたいと思います。

  1. クーポンキャンペーンを用いたユーザ追加・更新・サービスの購読
  1. ACS 上の会員データ同期ワークフローをトリガー
  1. 買い物かご放棄を検出時に通知メールを送信

その他のトピック

関連リンク

本記事の内容は2018年8月現在の情報のものであり、今後変更される可能性があります。あらかじめご了承ください。

投稿者

Baiz Yeh