入門 REST APIs

上次更新: 2023-05-21
  • 主題:
  • API
    檢視有關此主題的更多資訊

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

API 需求與建議

與 Audience Manager APIs

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

  • 請求參數: 除非另有指定,否則所有請求參數都是必需的。
  • 請求標題:使用 Adobe Developer 令牌,必須提供 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 Developer進行身份驗證

Adobe Developer概述

Adobe Developer 是Adobe的開發者生態系統和社區。 包括 所有Adobe產品的API

這是設定和使用的推薦方法 Adobe APIs。

必要條件

在配置之前 JWT 驗證,確保您有權訪問 Adobe Developer控制台Adobe Developer。 請與組織管理員聯繫以獲取訪問請求。

驗證

按照以下步驟配置 JWT (Service Account) 驗證 Adobe Developer:

  1. 登錄到 Adobe Developer控制台
  2. 按照中的步驟操作 服務帳戶連接
  3. 首先嘗試連接 API 根據來自 步驟3
注意

配置和使用 Audience Manager REST APIs 以自動方式生成 JWT 程式。 請參閱 JWT(服務帳戶)身份驗證 的上界。

技術帳戶RBAC權限

如果您的Audience Manager帳戶使用 基於角色的訪問控制,您必須建立Audience Manager技術用戶帳戶,並將其添加到Audience ManagerRBAC組中,該組將調用API。

按照以下步驟建立技術用戶帳戶並將其添加到RBAC組:

  1. 製作 GET 呼叫 https://aam.adobe.io/v1/users/self。 該呼叫將建立您可以在 Admin Console,也請參見Wiki頁。 Users 的子菜單。

    技術帳戶

  2. 登錄到您的Audience Manager帳戶 添加技術用戶帳戶 調用API的用戶組。

OAuth 身份驗證(不建議使用)

警告

Audience Manager REST API 令牌認證和更新 OAuth 2.0 現在已棄用。

請使用 JWT(服務帳戶)身份驗證 的雙曲餘切值。

的 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-only用戶帳戶。

密碼驗證工作流

密碼身份驗證安全訪問我們的 REST API。 以下步驟概述了來自 JSON 客戶端。

秘訣

如果將訪問和刷新令牌儲存在資料庫中,則加密它們。

步驟1:請求 API 訪問

請與合作夥伴解決方案經理聯繫。 他們會給你 API 客戶端ID和密碼。 ID和機密將您驗證到 API。

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

步驟2:請求令牌

將令牌請求傳遞給您的首選 JSON 客戶端。 生成請求時:

  • 使用 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 key表示在訪問令牌過期之前的秒數。 最佳做法是,在令牌暴露時使用較短的過期時間來限制暴露。

刷新令牌

刷新令牌續訂 API 原始令牌過期後的訪問。 如果請求,響應 JSON 在密碼工作流中包括刷新標籤。 如果未收到刷新令牌,請通過密碼驗證過程建立新令牌。

您還可以使用刷新令牌在現有訪問令牌過期之前生成新令牌。

如果訪問令牌已過期,則您將收到 401 Status Code 以及響應中的以下標題:

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

以下步驟概述了使用刷新令牌從 JSON 客戶端。

步驟1:請求新令牌

使用首選項傳遞刷新令牌請求 JSON 客戶端。 生成請求時:

  • 使用 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 並傳遞您先前訪問請求中收到的刷新令牌。 請求應如下所示:
    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 請求

呼叫要求 API 方法。

針對可用的呼叫 API 方法:

可選 API 查詢參數

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

可將這些可選參數與 API 返回的方法 全部 對象的屬性。 將查詢傳遞到 API。

參數 說明
page 按頁碼返回結果。 編號從0開始。
pageSize 設定請求返回的響應結果數(預設值為10)。
sortBy 根據指定的 JSON 屬性。
descending 按降序排序並返回結果。 ascending 為預設值。
search 根據要用作搜索參數的指定字串返回結果。 例如,假設您要查找所有模型的結果,這些模型在該項目的任何值欄位中都使用「Test」一詞。 您的示例請求可能如下所示: GET https://aam.adobe.io/v1/models/?search=Test。 可以搜索「」返回的任何值get all」對話框。
folderId 返回的所有ID traits 資料夾中。 並非所有方法都可用。
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

下表列出了請求 URLs 過去 API 請求,按方法。

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

請求 URLs 為 JWT 驗證

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/

請求 URLs 為 OAuth 身份驗證(不建議使用)

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提供對不同工作環境的訪問。 這些環境可幫助您針對不同的資料庫test代碼,而不會影響即時生產資料。 下表列出了 API 環境和相應的資源主機名。

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

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

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

版本

這些版本的新版本 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 伺服器遇到錯誤,導致無法完成請求。

此頁面上的