快速入門 REST APIs getting-started-with-rest-apis
有關一般需求、驗證、選用查詢引數、請求的資訊 URLs和其他參照。
API需求與Recommendations api-requirements-recommendations
使用時,請注意下列事項 AUDIENCE MANAGER API 程式碼:
- 要求引數: 除非另有指定,否則所有要求引數皆為必要。
- 請求標頭:使用時 Adobe Developer Token,您必須提供
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 支援三種驗證方法。
-
badge positive 建議 OAuth伺服器對伺服器驗證 使用 Adobe開發人員主控台. Adobe Developer 是Adobe的開發人員生態系統和社群。 內容包括 適用於所有Adobe產品的API. 這是設定和使用的建議方式 Adobe APIs. 深入瞭解 OAuth伺服器對伺服器驗證 (在Adobe開發人員檔案中)。
-
badge negative 已棄用 JWT (服務帳戶)驗證 使用 Adobe開發人員主控台. Adobe Developer 是Adobe的開發人員生態系統和社群。 內容包括 適用於所有Adobe產品的API.
-
badge negative 已棄用 舊版OAuth驗證. 雖然此方法已過時,但擁有現有 OAuth 整合可繼續使用此方法。
使用Adobe Developer的OAuth伺服器對伺服器驗證 oauth-adobe-developer
本節說明如何收集驗證Audience ManagerAPI呼叫所需的認證,如下方流程圖所述。 您可以在初始的一次性設定中收集大部分必要的認證。 然而,存取權杖必須每24小時重新整理一次。
Adobe Developer概觀 developer-overview
Adobe Developer 是Adobe的開發人員生態系統和社群。 內容包括 適用於所有Adobe產品的API.
這是設定和使用的建議方式 Adobe APIs.
必備條件 prerequisites-server-to-server
設定之前 OAuth Server-to-Server 驗證,確定您擁有 Adobe Developer Console 在 Adobe Developer. 如需存取要求,請聯絡您的組織管理員。
驗證 oauth
請依照下列步驟進行設定 OAuth Server-to-Server 驗證使用 Adobe Developer:
- 登入 Adobe Developer Console.
- 請依照以下檔案中的步驟操作: OAuth伺服器對伺服器認證實作指南.
- 期間 步驟2:使用服務帳戶驗證新增API至您的專案,選擇 Audience Manager API 選項。
- 請先建立連線,然後再試一次 API 根據的指示呼叫 步驟3.
將Audience Manager API新增至專案 add-aam-api-to-project
前往 Adobe Developer Console 並使用您的Adobe ID登入。 接下來,請依照教學課程中概述的步驟進行 建立空白專案 在Adobe Developer Console檔案中。
建立新專案後,選取 Add API 於 Project Overview 畫面。
此 Add an API 畫面隨即顯示。 選取Adobe Experience Cloud的產品圖示,然後選擇 Audience Manager API 在選取之前 Next.
選取OAuth伺服器對伺服器驗證型別 select-oauth-server-to-server
接著,選取驗證型別以產生存取權杖並存取Audience ManagerAPI。
選取要整合的產品設定檔 select-product-profiles
在 Configure API 畫面中,選取所需的產品設定檔。 您整合的服務帳戶可透過此處選取的產品設定檔存取精細功能。
選取 Save configured API 當您準備好時。
收集認證 gather-credentials
將API新增至專案後, Audience Manager API 專案的頁面會顯示所有Audience ManagerAPI呼叫所需的下列認證:
{API_KEY}
(Client ID){ORG_ID}
(Organization ID)
產生存取權杖 generate-access-token
下一步是產生 {ACCESS_TOKEN}
用於Audience Manager API呼叫的認證。 不像 {API_KEY}
和 {ORG_ID}
,則必須每24小時產生新Token以繼續使用Audience ManagerAPI。 選取 Generate access token,如下所示。
測試API呼叫 test-api-call
取得驗證持有人權杖後,請執行API呼叫以測試您現在可以存取Audience ManagerAPI。
code language-shell |
---|
|
使用有效的存取Token時,API端點會傳回200回應,以及包含您的組織有權存取之所有全域資料來源的回應主體。
code language-json |
---|
|
已棄用JWT (Service Account)使用Adobe Developer進行驗證 jwt
Adobe Developer概觀 adobeio
Adobe Developer 是Adobe的開發人員生態系統和社群。 內容包括 適用於所有Adobe產品的API.
這是設定和使用的建議方式 Adobe APIs.
必備條件 prerequisites
設定之前 JWT 驗證,確定您擁有 Adobe Developer Console 在 Adobe Developer. 如需存取要求,請聯絡您的組織管理員。
驗證 auth
請依照下列步驟進行設定 JWT (Service Account) 驗證使用 Adobe Developer:
- 登入 Adobe Developer Console.
- 請依照中的步驟操作 服務帳戶連線.
- 期間 步驟2:使用服務帳戶驗證新增API至您的專案,選擇 Audience Manager API 選項。
- 請先建立連線,然後再試一次 API 根據的指示呼叫 步驟3.
note note |
---|
NOTE |
若要設定與使用 Audience Manager REST APIs 您可以透過自動化方式產生 JWT 以程式設計方式。 另請參閱 JWT (服務帳戶)驗證 以取得詳細指示。 |
技術帳戶RBAC許可權
如果您的Audience Manager帳戶使用 角色型存取控制,您必須建立Audience Manager技術使用者帳戶,並將其新增至將進行API呼叫的Audience ManagerRBAC群組。
請依照下列步驟建立技術使用者帳戶,並將其新增至RBAC群組:
-
建立
GET
呼叫https://aam.adobe.io/v1/users/self
. 通話會建立您可在中看到的技術使用者帳戶 Admin Console,在 Users 頁面。 -
登入您的Audience Manager帳戶並 新增技術使用者帳戶 至將進行API呼叫的使用者群組。
已棄用OAuth 驗證(已棄用) oauth-deprecated
note warning |
---|
WARNING |
Audience Manager REST API 權杖驗證和續約,透過 OAuth 2.0 現已棄用。 |
請使用 JWT (服務帳戶)驗證 而非。 |
此 Audience Manager REST API 追蹤 OAuth 2.0 權杖驗證和續約的標準。 以下各節將說明如何驗證並開始使用 APIs.
建立一般 API 使用者 requirements
建議您另外建立一個技術使用者帳戶,以便使用 Audience Manager APIs.這是一般帳戶,不會繫結至組織中的特定使用者或與其相關聯。 此型別 API 使用者帳戶可協助您完成2件事:
- 識別呼叫的服務 API (例如,來自使用我們的應用程式的呼叫 API或從其他製作工具 API 請求)。
- 提供對的不中斷存取 APIs.與特定人員繫結的帳戶可能會在他們離開您的公司時刪除。 這會導致您無法使用可用的 API 程式碼。 未與特定員工繫結的一般帳戶可協助您避免此問題。
在此型別的帳戶範例或使用案例中,假設您想使用一次變更許多區段 大量管理工具. 若要這麼做,您的使用者帳戶需要 API 存取。 不要將許可權新增到特定使用者,請建立非特定, API 具有適當認證、金鑰和密碼的使用者帳戶 API 呼叫。 如果您開發自己的應用程式來使用 Audience Manager APIs.
使用您的 Audience Manager 顧問以設定通用、 API-only使用者帳戶。
密碼驗證工作流程 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 |
---|
|
此 expires_in
key代表存取Token過期前的秒數。 如果代號公開時,最佳做法就是使用較短的到期時間來限制曝光。
重新整理Token refresh-token
重新整理Token更新 API 在原始Token過期後存取。 若有要求,回應會顯示 JSON 在密碼工作流程中,包含重新整理權杖。 如果您沒有收到重新整理權杖,請透過密碼驗證程式建立新的權杖。
您也可以使用重新整理權杖,在現有存取權杖過期之前產生新權杖。
如果您的存取權杖已過期,您將會收到 401 Status Code
和回應中的下列標頭:
WWW-Authenticate: Bearer realm="oauth", error="invalid_token", error_description="Access token expired: <token>"
下列步驟概述使用重新整理權杖從建立新存取權杖的工作流程 JSON 使用者端。
步驟1:要求新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
並傳入您先前存取請求中收到的重新整理Token。 要求應如下所示:grant_type=refresh_token&refresh_token=b27122c0-b0c7-4b39-a71b-1547a3b3b88e
步驟2:接收新Token
此 JSON 回應包含您的新存取權杖。 回應應如下所示:
code language-json |
---|
|
授權代碼和隱含驗證 authentication-code-implicit
此 Audience Manager REST API 支援授權代碼和隱含驗證。 若要使用這些存取方法,您的使用者需要登入 https://api.demdex.com/oauth/authorize
以取得存取權並重新整理Token。
進行驗證 API 請求 authenticated-api-requests
通話需求 API 方法會在您收到驗證權杖之後。
對可用發出呼叫的方式 API 方法:
- 在
HTTP
標題,設定Authorization: Bearer <token>
. - 使用時 JWT (服務帳戶)驗證,您必須提供
x-api-key
標頭,將會與您的client_id
. 您可以取得您的client_id
從 Adobe Developer整合 頁面。 - 呼叫必要的 API 方法。
可選 API 查詢引數 optional-api-query-parameters
設定傳回物件所有屬性的方法可用的選用引數。
您可以使用這些選擇性引數搭配 API 傳回的方法 全部 物件的屬性。 將此查詢傳入時,請在要求字串中設定這些選項 API.
page
pageSize
sortBy
descending
ascending
是預設值。search
GET https://aam.adobe.io/v1/models/?search=Test
. 您可以搜尋「」傳回的任何值get all"方法。folderId
permissions
根據指定的許可權傳回區段清單。 READ
是預設值。 許可權包括:
READ
:傳回並檢視區段的相關資訊。WRITE
:使用PUT
更新區段。CREATE
:使用POST
以建立區段。DELETE
:刪除區段。 需要存取基礎特徵(如果有)。 例如,如果您想要移除區段,則需要擁有刪除屬於該區段之特徵的許可權。
使用不同的索引鍵值配對指定多個許可權。 例如,若要傳回含有以下專案的區段清單: READ
和 WRITE
僅限許可權,傳入 "permissions":"READ"
, "permissions":"WRITE"
.
includePermissions
true
以傳回該區段的許可權。 預設為 false
.關於頁面選項的附註
頁面資訊時間 不是 指定,要求會傳回plain JSON 結果會出現在陣列中。 若頁面資訊 是 指定,則傳回的清單會包裝在 JSON 包含總結果和目前頁面相關資訊的物件。 您使用頁面選項的範例請求看起來可能類似這樣:
GET https://aam.adobe.io/v1/models/?page=1&pageSize=2&search=Test
API URLs api-urls
URLs 請求、測試和生產環境及版本。
請求 URLs request-urls
下表列出請求 URLs 用於傳入 API 請求,依方法。
根據您使用的驗證方法,您需要調整請求 URLs 根據下表。
請求 URLs 針對建議已棄用JWT 透過Adobe Developer驗證 request-urls-jwt
https://aam.adobe.io/v1/models/
https://aam.adobe.io/v1/datasources/
https://aam.adobe.io/v1/signals/derived/
https://aam.adobe.io/v1/destinations/
https://aam.adobe.io/v1/partner-sites/
https://aam.adobe.io/v1/folders/traits /
區段:
https://aam.adobe.io/v1/folders/segments /
https://aam.adobe.io/v1/schemas/
https://aam.adobe.io/v1/segments/
https://aam.adobe.io/v1/traits/
https://aam.adobe.io/v1/customer-trait-types
https://aam.adobe.io/v1/taxonomies/0/
請求 URLs 針對已棄用OAuth 驗證 request-urls-oauth
https://api.demdex.com/v1/models/
https://api.demdex.com/v1/datasources/
https://api.demdex.com/v1/signals/derived/
https://api.demdex.com/v1/destinations/
https://api.demdex.com/v1/partner-sites/
https://api.demdex.com/v1/folders/traits /
區段:
https://api.demdex.com/v1/folders/segments /
https://api.demdex.com/v1/schemas/
https://api.demdex.com/v1/segments/
https://api.demdex.com/v1/traits/
https://api.demdex.com/v1/customer-trait-types
https://api.demdex.com/v1/taxonomies/0/
環境 environments
此 Audience Manager API提供不同工作環境的存取權。 這些環境可協助您針對個別資料庫測試程式碼,而不會影響即時生產資料。 下表列出可用的 API 環境和對應的資源主機名稱。
根據您使用的驗證方法,您需要調整環境 URLs 根據下表。
https://aam.adobe.io/...
https://api.demdex.com/...
https://aam-beta.adobe.io/...
https://api-beta.demdex.com/...
版本 versions
這些檔案的新版本 API會定期發行。 新發行版本會增加 API 版本號碼。 請求中參考了版本號碼 URL 作為 v<version number>
如下列範例所示:
https://<host>/v1/...
已定義的回應代碼 response-codes-defined
HTTP
狀態代碼和傳回的回應文字 Audience Manager REST API.
200
OK
201
Created
PUT
和 POST
要求。204
No Content
400
Bad Request
403
Forbidden
404
Not Found
409
Conflict
500
Server Error