Experience League

退出搜尋

Experience Cloud

Document Cloud

開始使用REST APIs

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

API 需求與建議

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

使用Audience Manager API程式碼時，請注意下列事項：

請求參數：除 非另有指定，否則所有請求參數都是必要的。
請求標題:使用 Adobe I/ 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支援兩種驗證方法。

JWT（服務帳戶）使用 Adobe I/O驗證。Adobe I/O 是Adobe的開發人員生態系統和社群。它包含所有Adobe產品的Adobe I/O開發人員工具和API和 API。這是設定和使用Adobe APIs的建議方式。
OAuth驗證（已過時）。雖然此方法已不再提倡，但具有現有OAuth整合的客戶仍可繼續使用此方法。

重要

根據您的驗證方法，您需要相應調整請求URLs。有關您應使用的主機名的詳細資訊，請參見Environments部分。

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 Developer Console。請洽詢您的組織管理員以取得存取要求。

驗證

請遵循下列步驟，使用Adobe I/O配置JWT (Service Account)驗證：

登入Adobe Developer Console。
按照服務帳戶連接中的步驟操作。
- 在步驟2:使用服務帳戶驗證將API新增至您的專案，請選擇Audience Manager API選項。
根據步驟3中的指示進行第一個API呼叫，以嘗試連接。

注意

要以自動方式配置和使用Audience Manager REST APIs，可以寫程式生成JWT。有關詳細說明，請參見JWT（服務帳戶）Authentication。

OAuth 驗證（已過時）

警告

Audience Manager REST API 現在已不建議使用Token驗 OAuth 2.0 證和續約方式。

請改用JWT（服務帳戶）驗證。

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

建立一般API用戶

我們建議您建立個別的技術使用者帳戶，以搭配Audience Manager API使用。這是一般帳戶，不會系結至您組織中的特定使用者或與其關聯。此類API使用者帳戶可協助您完成下列2項工作：

識別呼叫API的服務（例如，來自使用我們API的應用程式或來自發出API請求的其他工具的呼叫）。
不間斷地訪問API。當系結至特定人員的帳戶離開您的公司時，可能會將其刪除。這會使您無法使用可用的API程式碼。未系結至特定員工的一般帳戶可協助您避免此問題。

舉例來說，假設您想要使用大量管理工具一次變更許多區段，做為此類帳戶的使用案例。為此，您的使用者帳戶需要API存取權。請建立非特定的API使用者帳戶，該帳戶具有適當的認證、金鑰和機密，以進行API呼叫，而不是新增權限給特定使用者。如果您開發使用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會在原始Token過期後續約API存取權。如果請求，密碼工作流中的響應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從瀏覽器的JSON用戶端建立新存取Token的工作流程。

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

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

要對可用API方法進行調用，請執行以下操作：

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

可選API查詢參數

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

您可以將這些可選參數與返回對象all屬性的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

下表按方法列出用於傳入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 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`	伺服器遇到意外錯誤，無法完成請求。

adobe.com 上的資源

Third Party Integrations Third Party Data Customer Journey Analytics Mobile Analytics Audience Segmentation General Data Protection Regulation

本頁內容

檢視下一個:

隱私權（已更新）

使用條款