開始使用REST APIs getting-started-with-rest-apis

關於一般需求、驗證、選擇性查詢引數、要求URLs和其他參考的資訊。

API需求與Recommendations api-requirements-recommendations

使用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資料時提供或傳入的變數。 將​ 斜體的 ​文字取代為您自己的程式碼、引數或其他必要資訊。

驗證 authentication

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

IMPORTANT
根據您的驗證方法,您需要相應地調整您的要求URLs。 如需您應使用之主機名稱的詳細資訊,請參閱環境區段。

使用Adobe Developer的OAuth伺服器對伺服器驗證 oauth-adobe-developer

本節說明如何收集驗證Audience ManagerAPI呼叫所需的認證,如下方流程圖所述。 您可以在初始的一次性設定中收集大部分必要的認證。 然而,存取權杖必須每24小時重新整理一次。

Audience Manager驗證流程圖。

Adobe Developer概觀 developer-overview

Adobe Developer是Adobe的開發人員生態系統和社群。 它包含所有Adobe產品🔗的API。

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

必備條件 prerequisites-server-to-server

設定OAuth Server-to-Server驗證之前,請確定您擁有Adobe DeveloperAdobe Developer Console的存取權。 如需存取要求,請聯絡您的組織管理員。

驗證 oauth

請依照下列步驟,使用Adobe Developer設定OAuth Server-to-Server驗證:

  1. 登入Adobe Developer Console
  2. 請依照OAuth伺服器對伺服器認證實作指南中的步驟操作。
  3. 根據步驟3的指示,進行您的第一個API呼叫以嘗試連線。
NOTE
若要以自動方式設定及使用Audience Manager REST APIs,您可以以程式設計方式輪換使用者端密碼。 如需詳細指示,請參閱開發人員檔案

將Audience Manager API新增至專案 add-aam-api-to-project

移至Adobe Developer Console並使用您的Adobe ID登入。 接下來,請依照教學課程中概述的步驟,在Adobe Developer Console檔案中建立空白專案

建立新專案後,請在​ Project Overview ​畫面上選取​ Add API

TIP
如果您已布建多個組織,請使用介面右上角的組織選擇器,以確保您位於所需的組織中。

Developer Console熒幕,醒目提示「新增API」選項。

Add an API ​畫面會出現。 選取Adobe Experience Cloud的產品圖示,然後選擇​ Audience Manager API ​再選取​ Next

選取Audience ManagerAPI。

TIP
選取​ View docs ​選項,在個別瀏覽器視窗中導覽至完整的Audience ManagerAPI參考檔案

選取OAuth伺服器對伺服器驗證型別 select-oauth-server-to-server

接著,選取驗證型別以產生存取權杖並存取Audience ManagerAPI。

IMPORTANT
選取​ OAuth Server-to-Server ​方法,因為這是唯一支援向前移動的方法。 Service Account (JWT) ​方法已過時。 雖然使用JWT驗證方法的整合功能在2025年1月1日之前將繼續運作,但Adobe強烈建議您在該日期之前將現有整合功能移轉至新的OAuth伺服器對伺服器方法。

選取OAuth驗證方法。

選取要整合的產品設定檔 select-product-profiles

在​ Configure API ​畫面中,選取所需的產品設定檔。 您整合的服務帳戶可透過此處選取的產品設定檔存取精細功能。

選取整合的產品設定檔。

準備好後選取​ Save configured API

收集認證 gather-credentials

將API新增至專案後,專案的​ Audience Manager API ​頁面會顯示所有呼叫Audience ManagerAPI時所需的下列認證:

在Developer Console中新增API後的 整合資訊。

  • {API_KEY} (Client ID)
  • {ORG_ID} (Organization ID)

產生存取權杖 generate-access-token

下一個步驟是產生{ACCESS_TOKEN}認證以用於Audience ManagerAPI呼叫。 不像{API_KEY}{ORG_ID}的值,必須每24小時產生一次新Token,才能繼續使用Audience ManagerAPI。 選取​ Generate access token,如下所示。

顯示如何產生存取權杖

測試API呼叫 test-api-call

取得驗證持有人權杖後,請執行API呼叫以測試您現在可以存取Audience ManagerAPI。

  1. 瀏覽至API參考檔案

  2. 選取​ Authorize ​並貼上您在產生存取權杖步驟中取得的存取權杖。

    授權API呼叫

  3. 執行/datasources API端點的GET呼叫,以擷取所有全域可用的資料來源清單,如API參考檔案中所述。 選取​ Try it out,接著選取​ Execute,如下所示。

    執行API呼叫

recommendation-more-help
API要求
code language-shell
curl -X 'GET' \
  'https://api.demdex.com/v1/datasources/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer your-access-token'
如果使用正確的持有人權杖,則為API回應

使用有效的存取Token時,API端點會傳回200回應,以及包含您的組織有權存取之所有全域資料來源的回應主體。

code language-json
[
  {
    "pid": 1794,
    "name": "testdatasource1",
    "description": "Test data source",
    "status": "ACTIVE",
    "integrationCode": "test_ds1",
    "dataExportRestrictions": [],
    "updateTime": 1595340792000,
    "crUID": 0,
    "upUID": 15910,
    "linkNamespace": false,
    "type": "GENERAL",
    "subIdType": "CROSS_DEVICE_PERSON",
    "inboundS2S": true,
    "outboundS2S": true,
    "useAudienceManagerVisitorID": false,
    "allowDataSharing": true,
    "masterDataSourceIdProvider": true,
    "uniqueTraitIntegrationCodes": false,
    "uniqueSegmentIntegrationCodes": false,
    "marketingCloudVisitorIdVersion": 0,
    "idType": "CROSS_DEVICE",
    "samplingEndTime": 1596550392825,
    "allowDeviceGraphSharing": false,
    "supportsAuthenticatedProfile": true,
    "deviceGraph": false,
    "authenticatedProfileName": "testdatasource1",
    "deviceGraphName": "",
    "customNamespaceId": 29769,
    "customNamespaceCode": "silviu_ds1",
    "customerProfileDataRetention": 62208000,
    "samplingStartTime": 1595340792825,
    "dataSourceId": 29769,
    "containerIds": [],
    "samplingEnabled": false
  },
  {
    "pid": 1794,
    "name": "AAM Test Company Audiences",
    "description": "Automatically generated trait data source",
    "status": "ACTIVE",
    "integrationCode": "adobe-provided",
    "dataExportRestrictions": [
      "PII"
    ],

    [...]

[已棄用]{class="badge negative"}使用Adobe Developer的JWT (Service Account)驗證 jwt

檢視已棄用的JWT (Service Account)取得驗證權杖方法的相關資訊。

Adobe Developer概觀 adobeio

Adobe Developer是Adobe的開發人員生態系統和社群。 它包含所有Adobe產品🔗的API。

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

必備條件 prerequisites

設定JWT驗證之前,請確定您擁有Adobe DeveloperAdobe Developer Console的存取權。 如需存取要求,請聯絡您的組織管理員。

驗證 auth

請依照下列步驟,使用Adobe Developer設定JWT (Service Account)驗證:

  1. 登入Adobe Developer Console
  2. 請依照服務帳戶連線中的步驟操作。
  3. 根據步驟3的指示,進行您的第一個API呼叫以嘗試連線。
note note
NOTE
若要以自動方式設定及使用Audience Manager REST APIs,您可以以程式設計方式產生JWT。 如需詳細指示,請參閱JWT (服務帳戶)驗證

技術帳戶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呼叫的使用者群組。

[已棄用]{class="badge negative"}OAuth驗證(已棄用) oauth-deprecated

檢視已棄用的舊版OAuth取得驗證Token的驗證方法相關資訊。
note warning
WARNING
Audience Manager REST API權杖驗證和透過OAuth 2.0的續約現在已被取代。
請改用JWT (服務帳戶)驗證

Audience Manager REST API遵循權杖驗證和更新的OAuth 2.0標準。 以下各節說明如何驗證並開始使用API。

建立一般API使用者 requirements

建議您建立個別的技術使用者帳戶來使用Audience Manager API。這是一般帳戶,不會繫結至組織中的特定使用者或與其相關聯。 此型別的API使用者帳戶可協助您完成2件事:

  • 識別呼叫API的服務(例如,使用我們API的應用程式呼叫,或其他發出API要求的工具呼叫)。
  • 提供對API的不中斷存取。繫結至特定人員的帳戶可能會在離開您的公司時刪除。 這會使您無法使用可用的API程式碼。 未與特定員工繫結的一般帳戶可協助您避免此問題。

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

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

密碼驗證工作流程 password-authentication-workflow

密碼驗證可安全存取我們的REST API。 以下步驟概述來自瀏覽器中JSON使用者端的密碼驗證工作流程。

note tip
TIP
如果您將Token儲存在資料庫中,請加密存取並重新整理Token。

步驟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回應包含您的存取權杖。 回應應如下所示:

code language-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 refresh-token

重新整理Token在原始的Token過期後更新API存取權。 若有要求,密碼工作流程中的回應JSON會包含重新整理權杖。 如果您沒有收到重新整理權杖,請透過密碼驗證程式建立新的權杖。

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

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

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

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

步驟1:要求新Token

傳入重新整理Token要求給您偏好的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:接收新Token

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

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

授權代碼和隱含驗證 authentication-code-implicit

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

提出已驗證的API要求 authenticated-api-requests

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

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

  • HTTP標頭中,設定Authorization: Bearer <token>
  • 使用JWT (服務帳戶)驗證時,您需要提供x-api-key標頭,此標頭將與您的client_id相同。 您可以從Adobe Developer整合頁面取得您的client_id
  • 呼叫必要的API方法。

選用的API查詢引數 optional-api-query-parameters

設定傳回物件所有屬性的方法可用的選用引數。

您可以使用這些選擇性引數搭配API方法,傳回物件的​ 所有 ​屬性。 將該查詢傳入API時,在要求字串中設定這些選項。

參數
說明
page
依頁碼傳回結果。 編號從0開始。
pageSize
設定要求傳回的回應結果數目(預設為10)。
sortBy
根據指定的JSON屬性排序並傳回結果。
descending
以遞減順序排序並傳回結果。 ascending為預設值。
search
根據您要用作搜尋引數的指定字串傳回結果。 例如,假設您想要尋找在該專案的任何值欄位中有「Test」字詞的所有模型的結果。 您的範例請求可能如下所示: GET https://aam.adobe.io/v1/models/?search=Test。 您可以搜尋"get all"方法傳回的任何值。
folderId
傳回指定資料夾中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 api-urls

請求、中繼和生產環境及版本的URLs。

要求URLs request-urls

下表列出用來以方法傳入API個要求的要求URLs。

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

要求URLs [建議]{class="badge positive"}[已棄用]{class="badge negative"}透過Adobe Developer進行JWT驗證 request-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已棄用]{class="badge negative"}OAuth驗證 request-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/

環境 environments

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

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

環境
JWT驗證的主機名稱
OAuth驗證的主機名稱
生產
https://aam.adobe.io/...
https://api.demdex.com/...
Beta
https://aam-beta.adobe.io/...
https://api-beta.demdex.com/...
NOTE
Audience Manager Beta版環境是生產環境的較小規模、獨立版本。 您想要測試的所有資料都必須在此環境中輸入和收集。

版本 versions

這些API的新版本會定期發行。 新發行版本會增加API版本編號。 請求URL中以v<version number>參照的版本號碼,如下列範例所示:

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

已定義的回應代碼 response-codes-defined

Audience Manager REST API傳回的HTTP狀態代碼和回應文字。

回應代碼ID
回應文字
定義
200
OK
已成功處理要求。 如有必要,將傳回預期的內容或資料。
201
Created
已建立資源。 傳回PUTPOST的要求。
204
No Content
已刪除資源。 回應本文將為空白。
400
Bad Request
伺服器不瞭解此要求。 通常是因為語法錯誤。 請檢查您的請求,然後再試一次。
403
Forbidden
您無權存取資源。
404
Not Found
找不到指定路徑的資源。
409
Conflict
由於與資源的狀態衝突,無法完成要求。
500
Server Error
伺服器發生未預期的錯誤,因此無法完成要求。
de293fbf-b489-49b0-8daa-51ed303af695