Platform 常見問答集與疑難排解指南

本檔案提供有關Adobe Experience Platform常見問題的解答，以及高階疑難排解指南，說明在任何Experience Platform API中可能遇到的常見錯誤。 有關各個Platform服務的故障排除指南，請參見下面的服務故障排除目錄。

常見問題集

以下是關於Adobe Experience Platform的常見問題的解答清單。

什麼是Experience Platform API?

Experience Platform 提供多個使用HTTP請求來存取資源的REST風格 Platform API。這些服務API每個都會顯示多個端點，並允許您執行列出(GET)、查閱(GET)、編輯(PUT和／或PATCH)和刪除(DELETE)資源的操作。 有關每項服務可用的特定端點和操作的詳細資訊，請參閱API參考文檔中的Adobe I/O。

如何設定API要求的格式？

請求格式會依使用的Platform API而異。 瞭解如何建構API呼叫的最佳方式，是依循您所使用之特定Platform服務的說明檔案中提供的範例。

閱讀範例API呼叫

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格式

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組織是什麼？

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請求中都需要API金鑰作為標題。 您可透過Adobe開發人員主控台找到。 在控制台內，在​Integrations​標籤上，導覽至​Overview​區段以取得特定整合，您將在​Client Credentials​下找到金鑰。 有關如何驗證到Platform的逐步說明，請參見驗證教程。

我要如何取得存取Token?

所有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

有關特定服務或端點可使用哪些查詢參數的詳細資訊，請參閱特定服務的文檔。

如何在PATCH請求中指定要更新的JSON欄位？

Platform API中的許多PATCH操作使用JSON Pointer字串來指示要更新的JSON屬性。 這些通常包含在使用JSON Patch格式的請求負載中。 如需這些技術所需語法的詳細資訊，請參閱API基礎指南。

我可以使用Postman呼叫Platform API嗎？

Postmanis 是可視化對REST風格的API呼叫的實用工具。本中篇貼文說明如何設定Postman以自動執行驗證，並使用它使用Experience Platform API。

Platform的系統需求為何？

視您使用的是UI或API而定，會套用下列系統需求：

對於基於UI的操作：

• 現代化、標準的網頁瀏覽器。 雖然建議使用最新版Chrome，但也支援目前和舊版的Firefox、Internet Explorer和Safari。
  • 每次發行新的主版本時，Platform會開始支援最新版本，而放棄支援第三個最新版本。
• 所有瀏覽器都必須啟用Cookie和JavaScript。

針對API和開發人員互動：

• 針對REST、串流和Webhook整合進行開發的開發環境。

錯誤和疑難排解

以下是使用任何Experience Platform服務時可能遇到的錯誤清單。 有關各個Platform服務的故障排除指南，請參見下面的服務故障排除目錄。

API狀態代碼

在任何Experience Platform API上都可能遇到以下狀態代碼。 每個原因都有各種原因，因此本節中的解釋是一般性的。 有關個別Platform服務中特定錯誤的詳細資訊，請參閱以下服務疑難排解目錄。

狀態代碼	說明	可能的原因
400	錯誤請求	請求的建構不當、遺失關鍵資訊及／或語法不正確。
401	驗證失敗	請求未通過驗證檢查。 您的存取Token可能遺失或無效。 如需詳細資訊，請參閱下方的OAuth Token錯誤一節。
403	禁止	已找到資源，但您沒有查看該資源的正確憑據。
404	找不到	在伺服器上找不到所請求的資源。 資源可能已刪除，或請求的路徑輸入錯誤。
500	內部伺服器錯誤	這是伺服器端錯誤。 如果您同時進行許多呼叫，可能已達到API限制，需要篩選結果。 （如需詳細資訊，請參閱篩選資料上的Catalog Service API開發人員指南子指南。） 請稍候片刻，然後再次嘗試您的請求，如果問題仍然存在，請聯絡您的管理員。

請求標題錯誤

Platform中的所有API呼叫都需要特定的請求標題。 若要瞭解個別服務需要哪些標題，請參閱API參考檔案。 要查找所需驗證標題的值，請參閱驗證教程。 如果在進行API呼叫時這些標題中有任何遺失或無效，可能會發生下列錯誤。

OAuth Token遺失

{
    "error_code": "403010",
    "message": "Oauth token is missing."
}

當API請求中缺少Authorization標題時，會顯示此錯誤訊息。 在再次嘗試之前，請確定授權標題已包含有效的存取Token。

OAuth Token無效

{
    "error_code": "401013",
    "message": "Oauth token is not valid"
}

當Authorization標題中提供的存取Token無效時，會顯示此錯誤訊息。 請確定Token已正確輸入，或在Adobe I/O主控台中產生新Token。

需要API金鑰

{
    "error_code": "403000",
    "message": "Api Key is required"
}

當API請求中遺失API金鑰標題(x-api-key)時，會顯示此錯誤訊息。 請先確定標題已包含有效的API金鑰，然後再再試一次。

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	沙盒疑難排解指南