Adobe Audience Manager API を使ってみよう #AdobeIO

03-02-2020

Adobe I/O デベロッパーブログをご愛読頂きましてありがとうございます。

この投稿では、Adobe Audience Manager で用意されている API をご紹介したいと思います。この API を使うことで、Trait や Segment をまとめて作成したり、既存の設定内容をまとめて更新したりなど、普段 UI で行うには手間のかかる作業を一括で行うことができます。また、API を使って皆さまがお使いの他のシステムと Audience Manager とを連携させることも可能です。

本投稿では、皆様からのお問い合わせが多く利用頻度の高い、Trait の作成と Segment 情報の取得という 2つの利用例を使って API の利用方法をご紹介いたします。

Adobe Audience Manager とは

ここで、少しだけ Adobe Audience Manager について紹介いたします。Adobe Audience Manager は、Adobe Experience Cloud の中でデータ管理プラットフォーム (DMP) 機能を提供する製品です。Adobe Analytics などで収集したオンラインデータや、皆さまの会社の CRM データなどのオフラインデータを統合して、一貫した完成度の高い顧客プロファイルを作成することができます。加えて、Audience Marketplace にて提供・販売されているデータプロバイダーのオーディエンスデータを取り込んだり、お互いにデータ連携を合意した Audience Manager 利用者同士でオーディエンスデータを交換することで、自社で保有するデータを超えた、よりリッチな顧客プロファイルを作成することも可能です。こうして得られた顧客プロファイルから、様々なオーディエンスセグメントを作成し活用することができます。例えば、Adobe Target などの LPO ツールと連携することで自社サイト訪問者へのおもてなし（パーソナライゼーション）や、レコメンデーションを行ったり、Adobe Campaign や Marketo Engage などの MA ツールと連携することでよりリッチなカスタマージャーニーを作成したり、より最適なタイミング、タッチポイントで顧客にアプローチすることが可能になったり、また、Adobe Advertising Cloud などの広告ソリューションと連携することでより最適な広告配信が可能になります。

Adobe Audience Manager はデータの取り込みやデータの配信先として実に多くのパートナーと連携しています。Adobe Experience Cloud の各製品との連携はもちろんのこと、こちらの Adobe Exchange に掲載されている各企業のサービスとシームレスなデータ連携がなされています。その連携を支えている一つが Adobe Audience Manager API です。多彩な機能を API で提供することで、様々なシステムと連携することが可能となっており、Audience Manager の更なる活用につながっています。

それでは、実際に API の利用方法について見ていきましょう。

事前準備

Adobe Audience Manager (以降では AAM と表記します) API を利用するには、事前にご準備いただくことがいくつかあります。

AAM のユーザーアカウント（必須）
AAM API を利用するには、AAM へアクセスできるユーザーアカウントが必要となります。利用できる API の権限は、この AAM のユーザーアカウントに付与されているアクセス権と同じ権限となりますので、事前に AAM ユーザーアカウントに必要な権限を付与（または削除）してください。ユーザーアカウント権限の設定につきましてはこちらの製品ヘルプをご参照ください。
AAM API を利用するための、クライアント ID（カスタマー ID とも呼ばれます）および API シークレット（必須）****
上記の AAM ユーザーアカウントに加えて、API を利用するためのクライアント ID (Client ID) と API シークレット (API secret) が必要となります。AAM カスタマーケアチームへご連絡いただき、アカウント情報を入手してください。
API リクエストを実行、確認するためのソフトウェア（任意）
本投稿では、Postman というツールを使って API の実行例を紹介しています。もし本投稿と同じく Postman を使って試してみたいという方は、こちらより入手していただけます。もちろん、cURL やその他皆さまが普段お使いのツールをご利用いただくことも可能ですので、Postman での実行例を参考に適宜読み替えていただきお試しください。

以上で事前準備は完了です。それでは、AAM API を実行してみましょう！

Access Token を取得する

Traits API や Segments API など AAM API を実行するには、いずれも Access Token が必要となりますので、まず最初にこの Access Token を取得します。
（執筆時点の 2020年 2月現在、Adobe Audience Manager API は Adobe Audience Manager の製品機能として提供しており、Adobe I/O API としての提供とは異なっております。そのため Token の取得方法などが異っていますのでご注意ください。）

この Access Token を取得する際に設定するパラメーターの中に、クライアント ID と API シークレットをセミコロン (:) で連結した文字列を Base64 でエンコードした値が必要となります。（Base64 でのエンコードは、オンラインでエンコードする方法などもあります。例「base64 encode」で検索した場合）

例えば、クライアント ID が mycompany、API シークレットが abcdefghijklmnopqrstuvwxyz0123456789 の場合、

クライアント ID と API シークレットをセミコロンで連結する (<client ID>:<API secret>)
例: mycompany:abcdefghijklmnopqrstuvwxyz0123456789
Base64 でエンコードする
例: bXljb21wYW55OmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1Njc4OQ==

それでは、Access Token を取得してみましょう。_<>_で記載されている部分は、適宜ご自身のアカウント情報に置き換えてください。すべての値を設定したら、「Send」ボタンをクリックします。

Method: POST
URL: https://api.demdex.com/oauth/token
Headers:
- Accept : application/json
- Authorization : Basic <上記の Base64 でエンコードしたクライアント ID と API シークレット>
Form Type: x-www-form-urlencoded
Request Body: （以下 key-value ペア）
- grant_type : password
- username : <AAM アカウントのユーザー名>
- password : <AAM アカウントのユーザーパスワード>

*Access Token を取得するためのアカウント情報をセットし、「Send」をクリックすると、成功すればこのように Access Token などが JSON 形式で返ってくる*

TIPS: Postman をお使いの場合、ここで取得した access_token の値を Environments に登録しておくと、この後の Traits API や Segments API の実行の際に便利です。さらに、「Tests」に下記のコードを設定しておくと、上述の API を実行した際に得られる応答内の access_token の値を、token という変数名に自動的に設定することができます。

var responseJsonData = JSON.parse(responseBody)
pm.environment.set("token", responseJsonData.access_token);

返ってきた JSON 内の “access_token” の値を変数 “token” に設定するスクリプト

なお、cURLではこのような形でリクエストを実行できます。

curl -X POST -H "Accept: application/json" \\
-H "Authorization: Basic <上記の Base64 でエンコードしたクライアント ID と API シークレット>" \\
-H "Cache-Control: no-cache" \\
-H "Content-Type:application/x-www-form-urlencoded" \\
-d 'grant_type=password&username=<AAM アカウントのユーザー名>&password=<AAM アカウントのユーザーパスワード>' https://api.demdex.com/oauth/token

Adobe Audience Manager API を実行する

Access Token が取得できましたら、この Access Token を使って自由に AAM API を実行することができます。（ただし、実行できる API は AAM アカウントに与えられた権限に限ります。）

ここでは AAM API を使った Trait の新規作成と、作成済みのセグメント情報を取得、の 2つについてご紹介します。

Trait を作成する

Traits API を使って Trait を作成してみましょう。Traits API について詳しくは、Audience Manager REST API の Traits API (英語) をご参照ください。

Method: POST
URL: https://api.demdex.com/v1/traits/
Authorization:
- TYPE: Bearer Token
- Token: <上記で作成した Access Token>
- このキャプチャでは、先述のスクリプトを使って変数 “token” に設定した値を参照しています。
Headers:
- Accept: application/json
- Content-Type: application/json
- Headers タブに Accept, Content-Type を指定
Request Body: （raw を選択）
- Request Body に、新規に作成する Trait の情報を設定します。パラメーターについては、Audience Manager REST API > Traits API より、Request Body > Model をご参照ください
- https://blog.adobe.com/media_2ed694195f29234bdfb9152a6ad1d1e3c75a968e.gif
- Traits API の POST /traits/ にて Request Body の Model を開くと、各種設定値を確認することができます
- 以下は必須のパラメーターのみ設定した場合となります。上述の Audience Manager REST API ドキュメントの Model 内に赤の * が付いているパラメーターが必須の設定項目となります。

{
  "folderId": <新規に作成する Trait の保存先 Trait フォルダーの ID>,
  "dataSourceId": <新規に作成する Trait が紐づく Data Source ID>,
  "name": "<新規に作成する Trait 名>",
  "traitType": "<新規に作成する Trait のタイプ>"
}
 
 
例：
{
  "folderId": 123456,
  "dataSourceId": 345678,
  "name": "my Trait",
  "traitType": "RULE_BASED_TRAIT"
}

- https://blog.adobe.com/media_30383ad481bdbf1da3855e527fd6236f97ca5df4.gif
- Request Body に必須項目だけ指定するとこのような感じに

すべての設定が完了しましたら、「Send」ボタンを押して実行してください。
問題が無ければ Status: 201 Created となり、以下のような応答を得ることができ Trait が作成されます。

{
    "createTime": 1576495964000,
    "updateTime": 1576495964000,
    "sid": 12345678,
    "traitType": "RULE_BASED_TRAIT",
    "name": "my Trait",
    "description": "",
    "url": "mycompany.demdex.net/event?d_sid=12345678",
    "permissions": [
        "READ",
        "WRITE",
        "CREATE",
        "DELETE",
        "MAP_TO_SEGMENTS",
        "MAP_TO_MODELS",
        "CREATE_ALGO_TRAITS"
    ],
    "pid": 4567,
    "crUID": 12345,
    "upUID": 12345,
    "ttl": 120,
    "traitRuleVersion": 0,
    "type": 0,
    "backfillStatus": "NONE",
    "dataSourceId": 345678,
    "folderId": 123456
}

Segment 情報を取得する

次に、こちらも利用シーンの多い「作成済みの Segment ついて Segment 名や Description の情報を取得する」場合に使用する Segments API をご紹介します。Segments API について詳しくは、こちらも Audience Manager REST API > Segments API (英語) をご参照ください。

Method: GET
URL: https://api.demdex.com/v1/segments/{sid}
- {sid} の部分に、情報を取得したい Segment ID を指定してください
Authorization:
- TYPE: Bearer Token
- Token: <上記で作成した Access Token>
Headers:
- Accept: application/json
Request Body:
- （特に要りません）

こちらが実行結果例となります。

{
    "pid": 4567,
    "sid": 12345678,
    "mergeRuleDataSourceId": 37483,
    "name": "会員リピーター",
    "description": "AAM API テスト用",
    "status": "ACTIVE",
    "createTime": 1464765164000,
    "updateTime": 1464856296000,
    "crUID": 12345,
    "upUID": 12345,
    "integrationCode": "member_repeat",
    "segmentRule": "(1234567T) AND (7654321T)",
    "segmentRuleVersion": 1,
    "folderId": 54321,
    "permissions": [
        "READ",
        "WRITE",
        "CREATE",
        "DELETE",
        "MAP_TO_DESTINATIONS",
        "MAP_TO_MODELS"
    ],
    "legacyId": 987654,
    "dataSourceId": 345678
}

*Segments API の GET segment/{sid} を実行した結果例*

以上、利用シーンの多い 2つの API を例にあげて、AAM API の利用方法について順を追ってご紹介しました。

終わりに

いかがでしたでしょうか？Access Token を取得し、Audience Manager REST API を使って AAM の様々な機能をお使いいただくことができますので、ぜひ AAM API を活用していただき業務にお役立ていただけましたら、そしてさらに AAM をご活用いただけましたら幸いです。

* 本投稿は 2020年 2月時点での内容を記載しております。実行いただく前にぜひ一度最新情報をご確認いただくことをお勧めいたします。

参考リンク

製品ヘルプ: Audience Manager API の概要について
- Audience Manager API Introduction (英語)
- Audience Manager API の概要 (日本語)
API ドキュメント
- Audience Manager REST API (英語)
Postman

Adobe I/O コーポレートニュース