Show Menu
主題×

Getting Started with REST APIs

Information about general requirements, authentication, optional query parameters, request URLs, and other references.

API 需求與建議

您使用s時必須且應該做的 Audience Manager​API事。
  • 請求參數: 除非另有指定,否則所有請求參數都為必要參數。
  • 請求標題 :使用 Adobe I/O Token時 ,您必須提供標 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 I/O開發人員工具,以及所有Adobe產品 的API和API
這是設定和使用的建議方式 Adobe​APIs。

必要條件

在設定驗 JWT 證之前,請務必存取 Adobe I/O中的 Adobe Developer Console 。 請洽詢您的組織管理員以取得存取要求。

驗證

請依照下列步驟,使用下列 JWT (Service Account) 程式設定驗證 Adobe I/O:
  1. 請遵循「服務帳戶 連線」中的步驟
  2. 根據步驟3的指示進行第 API 一次呼叫,以嘗試連
要以自動方式配置和使 Audience Manager 用, REST APIs 可以以寫程式方式生成該 JWT 檔案。 有關詳 細說明,請參見JWT (服務帳戶)驗證。

OAuth 驗證(已過時)

Audience Manager REST API 現在已不建議使用Token驗 OAuth 2.0 證和續約方式。
The Audience Manager​REST API token驗 OAuth 2.0 證和續約標準。 以下各節將說明如何驗證並開始使用 API。

建立一般使 API 用者

我們建議您建立個別的技術使用者帳戶,以便使用 Audience Manager​APIs。這是一般帳戶,不會系結至您組織中的特定使用者或與其關聯。 此類型的使 API 用者帳戶可協助您完成2項工作:
  • 識別呼叫的服務 API (例如,來自使用我們的應用程式或提出請 API求的其他工具的呼 API 叫)。
  • 不間斷地存取 APIs。當系結至特定人員的帳戶離開您的公司時,可能會將其刪除。 這會使您無法使用可用的程 API 式碼。 未系結至特定員工的一般帳戶可協助您避免此問題。
舉例來說,假設您想要使用批量管理工具一次變更許多區段,或是用於此類型 的帳戶 。 為此,您的使用者帳戶需要存 API 取權。 請建立非特定的使用者帳戶,該帳戶具有適當的認證、金鑰 API 和密碼,以進行呼叫,而不是新增權限給特定 API 使用者。 如果您開發使用s的應用程式,這個功能也會很有 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, API 在原始Token過期後續約存取權。 如果請求,密碼工作 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從瀏覽器用戶端建立新存取Token JSON 的工作流程。

步驟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 請求

在您收到驗 API 證Token後呼叫方法的要求。
若要對可用方法進行呼 API 叫:

可選 API 查詢參數

設定可用於返回對象所有屬性的方法的可選參數。
您可將這些可選參數與傳 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 : 刪除區段. 需要存取基本特徵(如果有)。 例如,若您要移除屬於某個群體的特徵,您需要有權利加以刪除。
使用個別的索引鍵值配對指定多個權限。 例如,若要傳回僅具有和權限的 READ WRITE 段清單,請傳入 "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可讓您存取不同的工作環境。 這些環境可協助您針對個別資料庫測試程式碼,而不會影響即時的生產資料。 下表列出了可用環境 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
已建立資源。 傳回 PUT 和請 POST 求。
204
No Content
已刪除資源。 回應主體將為空。
400
Bad Request
伺服器不瞭解請求。 通常是由於語法格式錯誤所致。 請檢查您的要求,然後再試一次。
403
Forbidden
您沒有資源的存取權。
404
Not Found
找不到指定路徑的資源。
409
Conflict
由於資源狀態衝突,無法完成請求。
500
Server Error
伺服器遇到意外錯誤,無法完成請求。