驗證及存取 Experience Platform API

Last update: Tue Jul 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

建立對象：

undefined
undefined
undefined
undefined

本檔案逐步說明如何存取Adobe Experience Platform開發人員帳戶，進而呼叫Experience Platform API。在本教學課程結束時，您將已產生或收集下列憑證，這些憑證需要作為所有Platform API呼叫中的標題：

{ACCESS_TOKEN}
{API_KEY}
{ORG_ID}

TIP

除了上述三個認證之外，許多Platform API也需要提供有效的{SANDBOX_NAME}作為標頭。請參閱沙箱總覽以取得有關沙箱的詳細資訊，並參閱沙箱管理端點檔案，以取得有關列出貴組織可用的沙箱的資訊。

為了維護應用程式和使用者的安全性，對Experience Platform API的所有請求都必須使用OAuth等標準進行驗證和授權。

本教學課程涵蓋如何收集驗證Platform API呼叫所需的認證，如下方流程圖所述。您可以在初始的一次性設定中收集大部分必要的認證。然而，存取權杖必須每24小時重新整理一次。

先決條件 prerequisites

為了成功呼叫Experience Platform API，您必須具備下列條件：

有權存取Adobe Experience Platform的組織。
能夠新增您為產品設定檔的開發人員和使用者的Admin Console管理員。
Experience Platform系統管理員，可授予您必要的屬性型存取控制項，以透過API在Experience Platform的不同部分執行讀取或寫入作業。

您也必須有Adobe ID才能完成本教學課程。如果您沒有Adobe ID，可以使用下列步驟建立一個：

移至Adobe Developer Console。
選取 建立新帳戶。
完成註冊程式。

取得Experience Platform的開發人員和使用者存取權 gain-developer-user-access

在Adobe Developer Console上建立整合之前，您的帳戶必須擁有Adobe Admin Console中Experience Platform產品設定檔的開發人員和使用者許可權。

取得開發人員存取權 gain-developer-access

請連絡貴組織的Admin Console管理員，使用Admin Console將您新增為Experience Platform產品設定檔的開發人員。請參閱Admin Console檔案以取得如何管理產品設定檔的開發人員存取權的特定指示。

一旦指派您為開發人員，您就可以開始在Adobe Developer Console中建立整合。這些整合是從外部應用程式和服務到Adobe API的管道。

取得使用者存取權 gain-user-access

您的Admin Console管理員也必須將您新增為相同產品設定檔的使用者。透過使用者存取權，您可以在UI中檢視您執行的API作業的結果。

如需詳細資訊，請參閱在 Admin Console中管理使用者群組的指南。

產生API金鑰（使用者端ID）和組織ID generate-credentials

NOTE

如果您是從Privacy ServiceAPI指南追蹤此檔案，您現在可以返回該指南以產生Privacy Service唯一的存取認證。

在透過Admin Console授予您開發人員和使用者存取Platform的許可權後，下一步就是在Adobe Developer Console中產生您的{ORG_ID}和{API_KEY}認證。這些認證只需產生一次，並可在未來平台API呼叫中重複使用。

將Experience Platform新增至專案 add-platform-to-project

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

建立新專案後，請在 專案概述 畫面上選取 新增API。

TIP

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

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

新增API 畫面會出現。選取Adobe Experience Platform的產品圖示，然後選擇 Experience PlatformAPI，再選取 下一步。

選取Experience PlatformAPI。

TIP

選取 檢視檔案 選項，在個別瀏覽器視窗中瀏覽至完整的Experience PlatformAPI參考檔案。

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

接著，選取OAuth伺服器對伺服器驗證型別，以產生存取權杖並存取Experience PlatformAPI。

IMPORTANT

OAuth Server-to-Server 方法是日後唯一支援的權杖產生方法。先前支援的 服務帳戶(JWT) 方法已過時，無法選取以進行新整合。雖然使用JWT驗證方法的現有整合可繼續運作至2025年1月1日，但Adobe強烈建議您在該日期之前將現有整合移轉至新的OAuth伺服器對伺服器方法。在[已棄用]{class="badge informative"}一節中取得詳細資訊{type=negative}產生JSON Web權杖(JWT)。

選取Experience PlatformAPI的OAuth伺服器對伺服器驗證方法。

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

在 設定API 畫面中，選取 AEP-Default-All-Users。

IMPORTANT

若要存取Platform中的特定功能，您還需要系統管理員授予您必要的屬性型存取控制許可權。請參閱取得必要的屬性型存取控制許可權一節中的詳細資訊。

選取整合的產品設定檔。

當您準備好時，選取 儲存已設定的API。

以下的影片教學課程也提供上述步驟的逐步解說，以設定與Experience Platform API的整合：

https://video.tv.adobe.com/v/28832/?learn=on

收集認證 gather-credentials

將API新增至專案後，專案的 Experience Platform API 頁面會顯示所有呼叫Experience Platform API時所需的下列認證：

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

{API_KEY} （使用者端識別碼）
{ORG_ID} （組織識別碼）

產生存取權杖 generate-access-token

下一步是產生{ACCESS_TOKEN}認證以用於Platform API呼叫。不像{API_KEY}和{ORG_ID}的值，必須每24小時產生一次新Token，才能繼續使用Platform API。選取 產生存取權杖，如下所示。

顯示如何產生存取權杖

TIP

您也可以使用Postman環境和集合來產生存取權杖。如需詳細資訊，請閱讀有關使用Postman驗證和測試API呼叫的章節。

[已棄用]{class="badge negative"}產生JSON Web權杖(JWT) jwt

WARNING

不建議使用產生存取權杖的JWT方法。所有新的整合都必須使用OAuth伺服器對伺服器驗證方法來建立。 Adobe也要求您在2025年1月1日前將現有的整合移轉至OAuth方法，以便您的整合能繼續運作。請參閱下列重要檔案：

檢視已棄用的資訊

下一步是根據您的帳戶憑證產生JSON Web權杖(JWT)。此值用於產生您的{ACCESS_TOKEN}認證，以用於Platform API呼叫，必須每24小時重新產生一次。

note important
IMPORTANT
在本教學課程中，以下步驟會概述如何在Developer Console中產生JWT。不過，此產生方法只應用於測試和評估目的。
如要正常使用，必須自動產生JWT。如需如何以程式設計方式產生JWT的詳細資訊，請參閱Adobe Developer上的服務帳戶驗證指南。

在左側導覽中選取 服務帳戶(JWT)，然後選取 產生JWT。

在 產生自訂JWT 下提供的文字方塊中，貼上您先前在將Platform API新增至服務帳戶時產生的私密金鑰內容。然後，選取 產生Token。

頁面會更新以顯示產生的JWT，以及可讓您產生存取權杖的範例cURL命令。在本教學課程中，請選取 產生的JWT 旁的複製，將權杖複製到剪貼簿。

產生存取權杖

產生JWT後，您可以在API呼叫中使用它來產生您的{ACCESS_TOKEN}。不像{API_KEY}和{ORG_ID}的值，必須每24小時產生一次新Token，才能繼續使用Platform API。

要求

以下請求會根據承載中提供的認證產生新的{ACCESS_TOKEN}。此端點僅接受表單資料作為其裝載，因此必須向其指定multipart/form-data的Content-Type標頭。

code language-shell
`curl -X POST https://ims-na1.adobelogin.com/ims/exchange/jwt \ -H 'Content-Type: multipart/form-data' \ -F 'client_id={API_KEY}' \ -F 'client_secret={SECRET}' \ -F 'jwt_token={JWT}'`

table 0-row-2 1-row-2 2-row-2 3-row-2
屬性	說明
`{API_KEY}`	您在先前的步驟中擷取的`{API_KEY}` （使用者端識別碼）。
`{SECRET}`	您在先前步驟中擷取的使用者端密碼。
`{JWT}`	您在先前步驟產生的JWT。

note note
NOTE
您可以使用相同的API金鑰、使用者端密碼和JWT，為每個工作階段產生新的存取權杖。這可讓您在應用程式中自動產生存取權杖。

回應

code language-json
`{ "token_type": "bearer", "access_token": "{ACCESS_TOKEN}", "expires_in": 86399992 }`

table 0-row-2 1-row-2 2-row-2 3-row-2
屬性	說明
`token_type`	型別 of 正在傳回權杖。對於存取權杖，此值一律為`bearer`。
`access_token`	產生的`{ACCESS_TOKEN}`。所有Platform API呼叫都需要以這個值做為`Authentication`標題，且前置詞為`Bearer`。
`expires_in`	存取Token過期前的剩餘毫秒數。此值達到0後，必須產生新的存取權杖才能繼續使用Platform API。

測試存取認證 test-credentials

收集完所有三個必要的認證（存取權杖、API金鑰和組織ID）後，您可以嘗試進行下列API呼叫。此呼叫列出貴組織可用的所有標準Experience Data Model (XDM)類別。在Postman中匯入並執行呼叫。

recommendation-more-help

要求

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: {{ORG_ID}}'

回應

如果您的回應與下方所示的回應類似，表示您的認證有效且運作正常。（此回應已因空間而遭截斷。）

{
  "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"
    }
  ]
}

style

shade-box

IMPORTANT

雖然上述呼叫足以測試您的存取認證，但請注意，您若沒有正確的屬性型存取控制許可權，將無法存取或修改數個資源。閱讀以下 取得必要的屬性型存取控制許可權 章節中的詳細資訊。