本檔案提供有關Adobe Experience Platform常見問題的解答,以及高階疑難排解指南,說明在任何Experience Platform API中可能遇到的常見錯誤。 有關各個Platform服務的故障排除指南,請參見下面的服務故障排除目錄。
以下是關於Adobe Experience Platform的常見問題的解答清單。
Experience Platform 提供多個使用HTTP請求來存取資源的REST風格 Platform API。這些服務API每個都會顯示多個端點,並允許您執行列出(GET)、查閱(GET)、編輯(PUT和/或PATCH)和刪除(DELETE)資源的操作。 有關每項服務可用的特定端點和操作的詳細資訊,請參閱API參考文檔中的Adobe I/O。
請求格式會依使用的Platform API而異。 瞭解如何建構API呼叫的最佳方式,是依循您所使用之特定Platform服務的說明檔案中提供的範例。
Experience Platform的檔案以兩種不同的方式顯示範例API呼叫。 首先,調用以API格式顯示,模板表示僅顯示操作(GET、POST、PUT、PATCH、DELETE)和所使用的端點(例如/global/classes
)。 有些範本也會顯示變數的位置,以協助說明呼叫應如何制定,例如GET /{VARIABLE}/classes/{ANOTHER_VARIABLE}
。
然後,呼叫在Request中顯示為cURL命令,其中包含成功與API互動所需的必要標題和完整「基本路徑」。 基本路徑應預先附加到所有端點。 例如,前述的/global/classes
端點變為https://platform.adobe.io/data/foundation/schemaregistry/global/classes
。 您會在整個檔案中看到API格式/請求模式,而且在對平台API進行自己的呼叫時,預期會使用範例「請求」中顯示的完整路徑。
以下是範例API要求,示範您在說明檔案中將會遇到的格式。
API格式
API格式顯示所使用的操作(GET)和端點。 變數會以大括弧表示(在本例中為{CONTAINER_ID}
)。
GET /{CONTAINER_ID}/classes
請求
在此範例請求中,API格式的變數會在請求路徑中指定實際值。 所有必要的標題也會顯示,例如範例標題值或應包含敏感資訊(例如安全性Token和存取ID)的變數。
curl -X GET \
https://platform.adobe.io/data/foundation/schemaregistry/global/classes \
-H 'Accept: application/vnd.adobe.xed-id+json' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
回應
此回應說明您在成功呼叫API後,會根據所傳送的請求收到哪些訊息。 有時候,回應會因空間而截斷,這表示您可能會看到範例中顯示的更多資訊或其他資訊。
{
"results": [
{
"title": "XDM ExperienceEvent",
"$id": "https://ns.adobe.com/xdm/context/experienceevent",
"meta:altId": "_xdm.context.experienceevent",
"version": "1"
},
{
"title": "XDM Individual Profile",
"$id": "https://ns.adobe.com/xdm/context/profile",
"meta:altId": "_xdm.context.profile",
"version": "1"
}
],
"_links": {}
}
如需平台API中特定端點的詳細資訊,包括必要的標頭和請求主體,請參閱API參考檔案。
IMS組織是客戶的Adobe表示。 任何授權的Adobe解決方案皆與此客戶組織整合。 當IMS組織有權使用Experience Platform時,它可指派存取權給開發人員。 IMS組織ID(x-gw-ims-org-id
)代表應執行API呼叫的組織,因此在所有API請求中都是必要的標題。 此ID可透過Adobe開發人員主控台找到:在Integrations標籤中,導覽至Overview區段以取得任何特定整合,以在Client Credentials下尋找ID。 有關如何驗證到Platform的逐步說明,請參見驗證教程。
所有API請求中都需要API金鑰作為標題。 您可透過Adobe開發人員主控台找到。 在控制台內,在Integrations標籤上,導覽至Overview區段以取得特定整合,您將在Client Credentials下找到金鑰。 有關如何驗證到Platform的逐步說明,請參見驗證教程。
所有API呼叫的「授權」標題中都需要存取Token。 只要您擁有IMS組織整合的存取權,就可使用curl
命令產生。 存取Token僅有24小時有效,之後必須產生新Token才能繼續使用API。 有關生成訪問Token的詳細資訊,請參閱驗證教程。
有些Platform API端點會接受查詢參數,以找出特定資訊並篩選回應中傳回的結果。 查詢參數會附加至具有問號(?
)符號的請求路徑,後面接著使用格式paramName=paramValue
的一或多個查詢參數。 在單一呼叫中結合多個參數時,您必須使用&符號(&
)來分隔個別參數。 下列範例說明如何使用多個查詢參數的請求在檔案中呈現。
常用查詢參數的範例包括:
GET /tenant/schemas?orderby=title
GET /datasets?limit=36&start=10
GET /batches?createdAfter=1559775880000&orderBy=desc:created
有關特定服務或端點可使用哪些查詢參數的詳細資訊,請參閱特定服務的文檔。
Platform API中的許多PATCH操作使用JSON Pointer字串來指示要更新的JSON屬性。 這些通常包含在使用JSON Patch格式的請求負載中。 如需這些技術所需語法的詳細資訊,請參閱API基礎指南。
Postmanis 是可視化對REST風格的API呼叫的實用工具。本中篇貼文說明如何設定Postman以自動執行驗證,並使用它使用Experience Platform API。
視您使用的是UI或API而定,會套用下列系統需求:
對於基於UI的操作:
針對API和開發人員互動:
以下是使用任何Experience Platform服務時可能遇到的錯誤清單。 有關各個Platform服務的故障排除指南,請參見下面的服務故障排除目錄。
在任何Experience Platform API上都可能遇到以下狀態代碼。 每個原因都有各種原因,因此本節中的解釋是一般性的。 有關個別Platform服務中特定錯誤的詳細資訊,請參閱以下服務疑難排解目錄。
狀態代碼 | 說明 | 可能的原因 |
---|---|---|
400 | 錯誤請求 | 請求的建構不當、遺失關鍵資訊及/或語法不正確。 |
401 | 驗證失敗 | 請求未通過驗證檢查。 您的存取Token可能遺失或無效。 如需詳細資訊,請參閱下方的OAuth Token錯誤一節。 |
403 | 禁止 | 已找到資源,但您沒有查看該資源的正確憑據。 |
404 | 找不到 | 在伺服器上找不到所請求的資源。 資源可能已刪除,或請求的路徑輸入錯誤。 |
500 | 內部伺服器錯誤 | 這是伺服器端錯誤。 如果您同時進行許多呼叫,可能已達到API限制,需要篩選結果。 (如需詳細資訊,請參閱篩選資料上的Catalog Service API開發人員指南子指南。) 請稍候片刻,然後再次嘗試您的請求,如果問題仍然存在,請聯絡您的管理員。 |
Platform中的所有API呼叫都需要特定的請求標題。 若要瞭解個別服務需要哪些標題,請參閱API參考檔案。 要查找所需驗證標題的值,請參閱驗證教程。 如果在進行API呼叫時這些標題中有任何遺失或無效,可能會發生下列錯誤。
{
"error_code": "403010",
"message": "Oauth token is missing."
}
當API請求中缺少Authorization
標題時,會顯示此錯誤訊息。 在再次嘗試之前,請確定授權標題已包含有效的存取Token。
{
"error_code": "401013",
"message": "Oauth token is not valid"
}
當Authorization
標題中提供的存取Token無效時,會顯示此錯誤訊息。 請確定Token已正確輸入,或在Adobe I/O主控台中產生新Token。
{
"error_code": "403000",
"message": "Api Key is required"
}
當API請求中遺失API金鑰標題(x-api-key
)時,會顯示此錯誤訊息。 請先確定標題已包含有效的API金鑰,然後再再試一次。
{
"error_code": "403003",
"message": "Api Key is invalid"
}
當提供的API金鑰標題(x-api-key
)的值無效時,會顯示此錯誤訊息。 請確定您已正確輸入密鑰,然後再次嘗試。 如果您不知道您的API金鑰,則可在Adobe I/O控制台中找到:在Integrations標籤中,導覽至Overview區段以取得特定整合,以在Client Credentials下尋找API金鑰。
{
"error_code": "400003",
"message": "Missing header"
}
當API請求中遺失IMS組織標題(x-gw-ims-org-id
)時,會顯示此錯誤訊息。 請確定標題已包含在您IMS組織的ID中,然後再試一次。
{
"error_code": "403025",
"message": "Profile is not valid"
}
當使用者或Adobe I/O整合(由Authorization
標題中的存取Token識別)無權呼叫Experience Platform API(用於x-gw-ims-org-id
標題中提供的IMS組織)時,會顯示此錯誤訊息。 請確定您已在頁首中為您的IMS組織提供正確的ID,然後再次嘗試。 如果您不知道您的組織ID,可在Adobe I/O控制台中找到:在Integrations標籤中,導覽至Overview區段以取得特定整合,以在Client Credentials下尋找ID。
{
"type": "/placeholder/type/uri",
"status": 400,
"title": "BadRequestError",
"detail": "A valid content-type must be specified"
}
當POST、PUT或PATCH請求的標題無效或缺少Content-Type
標題時,將顯示此錯誤消息。 請確定請求中包含標題,且其值為application/json
。
以下是Experience Platform API的疑難排解指南和API參考檔案清單。 每個疑難排解指南都提供有關個別Platform服務所特有問題的常見問答和解決方案。 API參考檔案提供每個服務所有可用端點的完整指南,並顯示您可能收到的範例要求主體、回應和錯誤碼。
服務 | API 參考 | 疑難排解 |
---|---|---|
存取控制 | 存取控制API | 存取控制疑難排解指南 |
Adobe Experience Platform資料擷取 | Data Ingestion API | 批次擷取疑難排解 指南串流擷取疑難排解指南 |
Adobe Experience Platform資料科學工作區 | Sensei Machine Learning API | Data Science Workspace 疑難排解指南 |
Adobe Experience Platform資料管理 | Policy Service API | |
Adobe Experience Platform Identity Service | Identity Service API | Identity Service 疑難排解指南 |
Adobe Experience Platform查詢服務 | Query Service API | Query Service 疑難排解指南 |
Adobe Experience Platform Segmentation | Segmentation API | |
Catalog Service | Catalog Service API | |
Experience Data Model (XDM) | Schema Registry API | XDM System 常見問答集與疑難排解指南 |
Flow Service (Sources 和 Destinations) | Flow Service API | |
Real-time Customer Profile | Real-time Customer Profile API | Profile 疑難排解指南 |
沙盒 | 沙盒API | 沙盒疑難排解指南 |