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

Adobe I/O Corporate

コンテンツ

概要

前回 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 にアクセスする事ができます。

  • Adobe Campaign Standard ご購入のお客様
  • Adobe の実装パートナー様 ➜ プロジェクト関係者から権限を付与
  • Solution Partner Program 様 ➜ Experience Cloud Sandbox ページからサンドボックスを申請

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

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

  • 所属組織の権限: システム管理者
  • ACS インスタンスレベルのユーザ権限: Administrators

 

公開鍵証明書の作成

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

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

Adobe Campaign 連携の作成

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

 

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

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

 

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

  • Name: 連携の名前。連携がどのインスタンスに使う物で、どんなユーザ権限で API を実行されるかを明記すると良いでしょう。
  • Description: この連携の説明。
  • Public keys certificates: 先述の公開鍵証明書(複数可)をアップロードします。
  • License: どんなインスタンス上で、どのユーザ権限で API を実行するかを指定します。この記事では「Administrators」を使用します。

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

 

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

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

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

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

セキュリティ

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

サマリー

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

  • Experience Cloud 上の所属組織で「システム管理者」権限
  • ACS インスタンスへのアクセス
  • CRT、CER、DER または PEM 形式の公開鍵証明書、それらに対応する秘密鍵

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

  • API はサーバ間通信にのみ使用する事
  • API の使用方法は API のレート制限を超えない事

今後連載のシナリオ

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

  1. クーポンキャンペーンを用いたユーザ追加・更新・サービスの購読
    • プロフィールの取得 API
    • プロフィールの購読状況の取得 API
    • プロフィールの追加 API
    • プロフィールのサービス購読 API
    • プロフィールのサービス購読解除 API
  2. ACS 上の会員データ同期ワークフローをトリガー
    • ワークフロー外部信号トリガー API
  3. 買い物かご放棄を検出時に通知メールを送信
    • Transactional event 送信 API

その他のトピック

関連リンク

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

投稿者

Baiz Yeh

POSTED ON 2018.08.30

Products Featured

関連製品はありません

Tags