開始使用REST APIs

有關一般需求、驗證、可選查詢參數、請求URLs和其他參考的資訊。

API 需求與建議

使用Audience Manager API時,您必須且應該執行的操作。

使用Audience ManagerAPI代碼時,請注意以下事項:

  • 請求參數:除 非另有指定,否則所有請求參數都是必要的。
  • 請求標題:使用 AdobeI/ Otoken時,您必須提供 x-api-key 標題。您可依照服務帳戶整合頁面中的指示,取得API金鑰。
  • JSON內容類型: 指定 content-type: application/json ** accept: application/json 並在程式碼中。
  • 請求和回應:以 正確格式化的物件傳送 JSON 請求。Audience Manager 以格式化 JSON 資料回應。伺服器回應可包含要求的資料、狀態碼或兩者。
  • 存取: 您的 Audience Manager 顧問會提供您用戶端ID和金鑰,讓您提出 API 要求。
  • 檔案和程式碼範例: 斜體 ** 文字代表您在製作或接收資料時提供或傳入的 API 變數。以您自己的程式碼、參數或其他必要資訊取代​斜體​文字。

驗證

Audience Manager REST APIs支援兩種驗證方法。

重要

根據您的驗證方法,您需要相應調整請求URLs。 有關您應使用的主機名的詳細資訊,請參見Environments部分。

JWT (Service Account)使用Adobe I/O的驗證

Adobe I/O概述

Adobe I/O 是Adobe的開發人員生態系統和社群。它包含Adobe I/O開發人員工具,以及所有Adobe產品的API。

這是設定和使用Adobe APIs的建議方式。

必要條件

在配置JWT驗證之前,請務必存取Adobe中的Adobe I/O開發人員控制台。 請洽詢您的組織管理員以取得存取要求。

驗證

請遵循下列步驟,使用Adobe I/O配置JWT (Service Account)驗證:

  1. 登入Adobe開發人員主控台
  2. 按照服務帳戶連接中的步驟操作。
  3. 根據步驟3中的指示進行第一個API呼叫,以嘗試連接。
注意

要以自動方式配置和使用Audience Manager REST APIs,可以寫程式生成JWT。 有關詳細說明,請參見JWT(服務帳戶)Authentication

OAuth 驗證(已過時)

警告

Audience Manager REST API 現在已不建議使用Token驗 OAuth 2.0 證和續約方式。

請改用JWT(服務帳戶)驗證

Audience Manager REST API遵循代號驗證和續約的OAuth 2.0標準。 以下各節將說明如何驗證和開始使用API。

建立一般API用戶

我們建議您建立個別的技術使用者帳戶,以搭配Audience Manager API使用。這是一般帳戶,不會系結至您組織中的特定使用者或與其關聯。 此類API使用者帳戶可協助您完成下列2項工作:

  • 識別呼叫API的服務(例如,來自使用我們API的應用程式或來自發出API請求的其他工具的呼叫)。
  • 不間斷地訪問API。當系結至特定人員的帳戶離開您的公司時,可能會將其刪除。 這會使您無法使用可用的API程式碼。 未系結至特定員工的一般帳戶可協助您避免此問題。

舉例來說,假設您想要使用大量管理工具一次變更許多區段,做為此類帳戶的使用案例。 為此,您的使用者帳戶需要API存取權。 請建立非特定的API使用者帳戶,該帳戶具有適當的認證、金鑰和機密,以進行API呼叫,而不是新增權限給特定使用者。 如果您開發使用Audience Manager API的自己應用程式,這也很有用。

與您的Audience Manager顧問合作,以設定一般API僅限使用者帳戶。

密碼驗證工作流

密碼驗證安全訪問我們的REST API。 以下步驟概述瀏覽器中JSON用戶端的密碼驗證工作流程。

秘訣

如果將存取和重新整理Token儲存在資料庫中,請加密這些Token。

步驟1:請求API訪問

請洽詢您的合作夥伴解決方案經理。 他們會提供您API用戶端ID和密碼。 ID和密碼會將您驗證給API。

注意:如果您想要收到重新整理Token,請在您要求API存取時指定。

步驟2:請求代號

將Token請求傳入您偏好的JSON用戶端。 建立請求時:

  • 使用POST方法調用https://api.demdex.com/oauth/token
  • 將您的用戶端ID和密碼轉換為基本64編碼字串。 在轉換程式中,以冒號分隔ID和密碼。 例如,憑據testId : testSecret轉換為dGVzdElkOnRlc3RTZWNyZXQ=
  • 傳入HTTP headers Authorization:Basic <base-64 clientID:clientSecret>Content-Type: application/x-www-form-urlencoded。 例如,您的標題可能如下所示:
    Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
    Content-Type: application/x-www-form-urlencoded
  • 按如下方式設定請求正文:

    grant_type=password&username=<your-AudienceManager-user-name>&password=<your-AudienceManager-password>

步驟3:接收Token

JSON回應包含您的存取Token。 回應應如下所示:

{
    "access_token": "28fed402-eafd-456c-9341-ac753f25bbbc",
    "token_type": "bearer",
    "refresh_token": "b27122c0-b0c7-4b39-a71b-1547a3b3b88e",
    "expires_in": 21922,
    "scope": "read write"
}

expires_in金鑰代表存取Token過期前的秒數。 最佳實務是,使用較短的過期時間,在代號曝光時限制曝光。

重新整理Token

重新整理Token會在原始Token過期後續約API存取權。 如果請求,密碼工作流中的響應JSON包括刷新標籤。 如果您未收到重新整理Token,請透過密碼驗證程式建立新Token。

您也可以使用重新整理Token,在現有存取Token過期之前產生新Token。

如果您的存取Token已過期,您會在回應中收到401 Status Code和下列標題:

WWW-Authenticate: Bearer realm="oauth", error="invalid_token", error_description="Access token expired: <token>"

下列步驟概述了使用重新整理Token從瀏覽器的JSON用戶端建立新存取Token的工作流程。

步驟1:請求新Token

將重新整理Token請求傳入您偏好的JSON用戶端。 建立請求時:

  • 使用POST方法調用https://api.demdex.com/oauth/token
  • 將您的用戶端ID和密碼轉換為基本64編碼字串。 在轉換程式中,以冒號分隔ID和密碼。 例如,憑據testId : testSecret轉換為dGVzdElkOnRlc3RTZWNyZXQ=
  • 傳入HTTP標題Authorization:Basic <base-64 clientID:clientSecret>Content-Type: application/x-www-form-urlencoded。 例如,您的標題可能如下所示:
    Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
    Content-Type: application/x-www-form-urlencoded
  • 在請求內文中,指定grant_type:refresh_token並傳遞您在先前存取請求中收到的重新整理Token。 請求應如下所示:
    grant_type=refresh_token&refresh_token=b27122c0-b0c7-4b39-a71b-1547a3b3b88e

步驟2:接收新Token

JSON回應包含您的新存取Token。 回應應如下所示:

{
    "access_token": "4fdfc261-2ffc-4fb7-8dbd-64221714c45f",
    "token_type": "bearer",
    "refresh_token": "295fa487-1825-4caa-a715-80b81ac17dae",
    "expires_in": 21922,
    "scope": "read write"
}

授權碼與隱式驗證

Audience Manager REST API支援授權碼和隱式驗證。 若要使用這些存取方法,您的使用者必須登入https://api.demdex.com/oauth/authorize才能取得存取和重新整理Token。

進行驗證API請求

在您收到驗證Token後呼叫API方法的需求。

要對可用API方法進行調用,請執行以下操作:

  • HTTP標題中,設定Authorization: Bearer <token>
  • 使用JWT(服務帳戶)Authentication時,您需要提供x-api-key標題,該標題與您的client_id相同。 您可從Adobe I/O整合頁面取得client_id
  • 呼叫所需的API方法。

可選API查詢參數

設定可用於返回對象所有屬性的方法的可選參數。

您可以將這些可選參數與返回對象​all​屬性的API方法一起使用。 將查詢傳入API時,請在請求字串中設定這些選項。

參數 說明
page 依頁碼傳回結果。 編號從0開始。
pageSize 設定請求傳回的回應結果數目(預設值為10)。
sortBy 根據指定的JSON屬性排序並返回結果。
descending 以遞減順序排序和傳回結果。 ascending 為預設值。
search 根據您要用作搜尋參數的指定字串傳回結果。 例如,假設您想要在該項目的任何值欄位中,尋找具有「測試」字詞的所有模型的結果。 您的範例要求可能如下所示: GET https://aam.adobe.io/v1/models/?search=Test。 您可以搜尋"get all"方法傳回的任何值。
folderId 傳回指定資料夾內traits的所有ID。 並非所有方法都適用。
permissions 根據指定的權限傳回區段清單。 READ 為預設值。權限包括:
  • READ :傳回並檢視區段的相關資訊。
  • WRITE :用 PUT 於更新區段。
  • CREATE :用 POST 於建立區段。
  • DELETE : 刪除區段. 需要存取基本特徵(如果有)。 例如,若您要移除屬於某個群體的特徵,您需要有權利加以刪除。

使用個別的索引鍵值配對指定多個權限。例如,若要傳回僅具有READWRITE權限的區段清單,請傳入"permissions":"READ""permissions":"WRITE"
includePermissions (Boolean)設為true以傳回區段的權限。 預設為 false.

關於頁面選項的附註

當未指定頁面資訊​時,請求會傳回純JSON,產生陣列。​如果指定了頁面資訊​**,則返回的清單將被包在JSON對象中,該對象包含有關總結果和當前頁面的資訊。 您使用頁面選項的範例要求看起來可能類似下列:

GET https://aam.adobe.io/v1/models/?page=1&pageSize=2&search=Test

API URLs

URLs 請求、測試和生產環境以及版本。

請求 URLs

下表按方法列出用於傳入API請求的請求URLs。

根據您使用的驗證方法,您需要根據下表調整您的請求URLs。

JWT驗證的請求URLs

API 方法 請求 URL
Algorithmic Modeling https://aam.adobe.io/v1/models/
Data Source https://aam.adobe.io/v1/datasources/
Derived Signals https://aam.adobe.io/v1/signals/derived/
Destinations https://aam.adobe.io/v1/destinations/
Domains https://aam.adobe.io/v1/partner-sites/
Folders 特徵: https://aam.adobe.io/v1/folders/traits /
區段: https://aam.adobe.io/v1/folders/segments /
Schema https://aam.adobe.io/v1/schemas/
Segments https://aam.adobe.io/v1/segments/
Traits https://aam.adobe.io/v1/traits/
Trait Types https://aam.adobe.io/v1/customer-trait-types
Taxonomy https://aam.adobe.io/v1/taxonomies/0/

要求OAuth驗證URLs(已過時)

API 方法 請求 URL
Algorithmic Modeling https://api.demdex.com/v1/models/
Data Source https://api.demdex.com/v1/datasources/
Derived Signals https://api.demdex.com/v1/signals/derived/
Destinations https://api.demdex.com/v1/destinations/
Domains https://api.demdex.com/v1/partner-sites/
Folders 特徵: https://api.demdex.com/v1/folders/traits /
區段: https://api.demdex.com/v1/folders/segments /
Schema https://api.demdex.com/v1/schemas/
Segments https://api.demdex.com/v1/segments/
Traits https://api.demdex.com/v1/traits/
Trait Types https://api.demdex.com/v1/customer-trait-types
Taxonomy https://api.demdex.com/v1/taxonomies/0/

環境

Audience Manager API提供對不同工作環境的訪問。 這些環境可協助您針對個別資料庫測試程式碼,而不會影響即時的生產資料。 下表列出了可用的API環境和相應的資源主機名。

根據您使用的驗證方法,您需要根據下表調整您的環境URLs。

環境 JWT驗證的主機名 OAuth驗證的主機名
生產 https://aam.adobe.io/... https://api.demdex.com/...
測試版 https://aam-beta.adobe.io/... https://api-beta.demdex.com/...
注意

Audience Manager測試版環境是生產環境的較小規模的獨立版本。 您必須在此環境中輸入並收集您要測試的所有資料。

版本

這些API的新版本會定期發行。 新版本會遞增API版本號碼。 在請求URL中,版本號被引用為v<version number>,如下例所示:

https://<host>/v1/...

已定義的響應代碼

HTTP 狀態代碼和由返回的響應文本 Audience Manager REST API。

回應碼ID 回應文字 定義
200 OK 請求已成功處理。 將視需要傳回預期的內容或資料。
201 Created 已建立資源。 傳回PUTPOST請求。
204 No Content 已刪除資源。 回應主體將為空。
400 Bad Request 伺服器不瞭解請求。 通常是由於語法格式錯誤所致。 請檢查您的要求,然後再試一次。
403 Forbidden 您沒有資源的存取權。
404 Not Found 找不到指定路徑的資源。
409 Conflict 由於資源狀態衝突,無法完成請求。
500 Server Error 伺服器遇到意外錯誤,無法完成請求。

本頁內容

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now