REST APIs快速入門

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

API 需求與建議

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

使用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。 如需您應使用之主機名稱的詳細資訊,請參閱環境區段。

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

Adobe I/O概述

Adobe I/O 是Adobe的開發人員生態系統和社群。其中包含適用於所有Adobe產品🔗Adobe I/O開發工具和API及API。

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

必要條件

在配置JWT身份驗證之前,請確保您有權訪問Adobe I/O中的Adobe開發人員控制台。 如需存取請求,請聯絡貴組織的管理員。

驗證

請依照下列步驟使用Adobe I/O配置JWT (Service Account)身份驗證:

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

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

技術帳戶RBAC權限

如果您的Audience Manager帳戶使用角色型存取控制,您必須建立Audience Manager技術使用者帳戶,並將其新增至將進行API呼叫的Audience ManagerRBAC群組。

請依照下列步驟建立技術使用者帳戶,並將其新增至RBAC群組:

  1. https://aam.adobe.io/v1/users/self發出GET呼叫。 此呼叫將建立技術使用者帳戶,您可在Users頁面的Admin Console中查看。

    技術帳戶

  2. 登入您的Audience Manager帳戶,並將技術使用者帳戶🔗新增至將進行API呼叫的使用者群組。

OAuth 驗證(已廢止)

警告

Audience Manager REST API 代號驗證和透過的續 OAuth 2.0 約現已過時。

請改用JWT(服務帳戶)Authentication

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

建立通用API用戶

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

  • 識別呼叫API的服務(例如,來自使用API的應用程式或來自提出API請求的其他工具的呼叫)。
  • 不間斷地訪問APIs。與特定人員系結的帳戶可能會在他們離開您的公司時刪除。 這會阻止您使用可用的API代碼。 未與特定員工綁定的通用帳戶有助於您避免此問題。

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

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

密碼驗證工作流程

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

秘訣

如果您將權杖儲存在資料庫中,請加密存取和重新整理權杖。

步驟1:請求API訪問

請連絡您的合作夥伴解決方案經理。 它們會提供您API用戶端ID和密碼。 ID和機密會驗證您API。

注意:如果要接收刷新令牌,請在請求API訪問時指定。

步驟2:要求Token

使用您慣用的JSON用戶端傳遞Token要求。 建置請求時:

  • 使用POST方法呼叫https://api.demdex.com/oauth/token
  • 將用戶端ID和密碼轉換為base-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:接收代號

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

{
    "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會續訂API存取權。 如果請求,密碼工作流中的響應JSON將包括刷新令牌。 如果您未收到重新整理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:請求新代號

使用您偏好的JSON用戶端傳遞重新整理Token請求。 建置請求時:

  • 使用POST方法呼叫https://api.demdex.com/oauth/token
  • 將用戶端ID和密碼轉換為base-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:接收新代號

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

{
    "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才能取得存取權並重新整理權杖。

發出已驗證的API請求

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

要對可用的API方法進行呼叫:

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

可選API查詢參數

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

您可以將這些可選參數與API方法搭配使用,這些方法會傳回物件的​all​屬性。 將查詢傳遞至API時,請在要求字串中設定這些選項。

參數 說明
page 按頁碼返回結果。 編號從0開始。
pageSize 設定請求傳回的回應結果數(預設為10)。
sortBy 根據指定的JSON屬性對結果進行排序並返回。
descending 按降序排序和返回結果。 ascending 為預設值。
search 根據您要用作搜索參數的指定字串返回結果。 例如,假設您想在該項目的任何值欄位中,找到所有具有「Test」字詞之模型的結果。 您的範例要求可能如下所示: 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 APIs提供對不同工作環境的訪問。 這些環境可協助您針對個別資料庫測試程式碼,而不會影響即時的生產資料。 下表列出可用的API環境和相應的資源主機名。

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

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

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

版本

這些APIs的新版本會定期發行。 新版本會增加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 伺服器遇到錯誤,使其無法完成請求。

本頁內容