HTTP API連線

總覽

HTTP API目的地為 Adobe Experience Platform 可協助您將設定檔資料傳送至協力廠商HTTP端點的串流目的地。

若要將設定檔資料傳送至HTTP端點，您必須先 連接到目標 in Adobe Experience Platform.

使用案例

HTTP API目的地可讓您將XDM設定檔資料和對象區段匯出至一般HTTP端點。 在此，您可以執行自己的分析，或對匯出為Experience Platform外的設定檔資料執行任何其他可能需要的操作。

HTTP端點可以是客戶自己的系統或協力廠商解決方案。

匯出類型和頻率

有關目標導出類型和頻率的資訊，請參閱下表。

先決條件

若要使用HTTP API目的地將資料匯出Experience Platform，您必須符合下列必要條件：

• 您必須有支援REST API的HTTP端點。
• 您的HTTP端點必須支援Experience Platform設定檔架構。 HTTP API目的地不支援轉換為第三方裝載結構。 請參閱 匯出的資料 區段，以取得Experience Platform輸出結構的範例。
• 您的HTTP端點必須支援標頭。

IP位址允許清單

為符合客戶的安全性和法規遵循需求，Experience Platform提供靜態IP清單，您可以將這些IP放入HTTP API目的地允許清單中。 請參閱 串流目的地的IP位址允許清單 以取得允許清單的完整IP清單。

支援的驗證類型

HTTP API目的地支援數種驗證類型至HTTP端點：

• 沒有驗證的HTTP端點；
• 承載令牌驗證；
• OAuth 2.0用戶端認證 使用body表單進行驗證，使用 client ID, client secret 和 grant type ，如下列範例所示。

curl --location --request POST '<YOUR_API_ENDPOINT>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>'

• OAuth 2.0用戶端認證 具有基本授權，具有包含URL編碼的授權標題 client ID 和 client secret.

curl --location --request POST 'https://some-api.com/token' \
--header 'Authorization: Basic base64(clientId:clientSecret)' \
--header 'Content-type: application/x-www-form-urlencoded; charset=UTF-8' \
--data-urlencode 'grant_type=client_credentials'

• OAuth 2.0密碼授予.

連接到目標

若要連線至此目的地，請依照 目的地設定教學課程. 連接到此目的地時，必須提供以下資訊：

驗證資訊

承載令牌驗證

如果您選取 承載令牌 要連接到HTTP端點的驗證類型，請輸入以下欄位，然後選取 連接到目標:

• 承載令牌:插入承載令牌以驗證到您的HTTP位置。

無驗證

如果您選取 無 連接到HTTP端點的身份驗證類型：

當您選取此驗證開啟時，您只需要選取 連接到目標 並建立與端點的連線。

OAuth 2密碼驗證

如果您選取 OAuth 2密碼 要連接到HTTP端點的驗證類型，請輸入以下欄位，然後選取 連接到目標:

• 存取權杖URL:您發出存取權杖的URL，並選擇性地重新整理權杖。
• 用戶端ID:此 client ID 由系統指派給Adobe Experience Platform。
• 用戶端密碼:此 client secret 由系統指派給Adobe Experience Platform。
• 使用者名稱:用於訪問HTTP端點的用戶名。
• 密碼:訪問HTTP端點的密碼。

OAuth 2用戶端認證驗證

如果您選取 OAuth 2用戶端認證 要連接到HTTP端點的驗證類型，請輸入以下欄位，然後選取 連接到目標:

• 存取權杖URL:您發出存取權杖的URL，並選擇性地重新整理權杖。
• 用戶端ID:此 client ID 由系統指派給Adobe Experience Platform。
• 用戶端密碼:此 client secret 由系統指派給Adobe Experience Platform。
• 客戶端憑據類型:選取端點支援的OAuth2用戶端憑證授予類型：
  • 體型編碼:在此情況下， client ID 和 client secret 包括 在請求正文中 傳送至您的目的地。 如需範例，請參閱 支援的驗證類型 區段。
  • 基本授權:在此情況下， client ID 和 client secret 包括 在 Authorization 標題 編碼並傳送至目的地後。 如需範例，請參閱 支援的驗證類型 區段。

填寫目的地詳細資訊

若要設定目的地的詳細資訊，請填寫下方的必填和選填欄位。 UI中欄位旁的星號表示該欄位為必要欄位。

• 名稱:輸入一個名稱，您將用該名稱來識別此目標。
• 說明:輸入說明，以便您在未來識別此目的地。
• 標題:依照以下格式，輸入您要納入目的地呼叫的任何自訂標題： header1:value1,header2:value2,...headerN:valueN.
• HTTP端點:您要將設定檔資料傳送至的HTTP端點URL。
• 查詢參數:您可以選擇將查詢參數新增至HTTP端點URL。 使用的查詢參數格式如下： parameter1=value&parameter2=value.
• 包含區段名稱:如果要讓資料匯出包含要匯出的區段名稱，請切換。 如需選取此選項的資料匯出範例，請參閱 匯出的資料 下文一節。
• 包含區段時間戳記:如果您希望資料匯出包含建立和更新區段時的UNIX時間戳記，以及將區段對應至要啟用的目的地時的UNIX時間戳記，則切換。 如需選取此選項的資料匯出範例，請參閱 匯出的資料 下文一節。

啟用警報

您可以啟用警報，接收有關資料流到目標狀態的通知。 從清單中選擇要訂閱的警報，以接收有關資料流狀態的通知。 如需警報的詳細資訊，請參閱 使用UI訂閱目的地警報.

完成提供目標連接的詳細資訊後，請選擇 下一個.

啟用此目的地的區段

請參閱 對串流設定檔匯出目的地啟用受眾資料 以取得啟用受眾區段至此目的地的指示。

目標屬性

在 選擇屬性 步驟，Adobe建議您從 聯合方案. 選取唯一識別碼，以及您要匯出至目的地的任何其他XDM欄位。

設定檔匯出行為

Experience Platform會最佳化將設定檔匯出行為匯出至您的HTTP API目的地，以僅在符合區段資格或其他重大事件後發生設定檔的相關更新時，將資料匯出至API端點。 設定檔會在下列情況下匯出至您的目的地：

• 設定檔更新是由對應至目的地的至少一個區段的區段成員資格變更所決定。 例如，設定檔已符合對應至目的地的其中一個區段資格，或已退出對應至目的地的其中一個區段。
• 設定檔更新是由 身分圖. 例如，已符合其中一個對應至目的地區段資格的設定檔，已在「身分對應」屬性中新增身分識別。
• 配置檔案更新由至少一個映射到目標的屬性的屬性的屬性變化確定。 例如，對應步驟中對應至目的地的其中一個屬性會新增至設定檔。

在上述所有情況中，只有發生相關更新的設定檔會匯出至您的目的地。 例如，如果對應至目的地流程的區段有100個成員，且有5個新設定檔符合該區段的資格，則匯出至目的地的作業會是增量的，且僅包含5個新設定檔。

請注意，無論變更在何處，所有對應屬性都會針對設定檔匯出。 因此，在上述範例中，即使屬性本身未變更，這五個新設定檔的所有對應屬性也會匯出。

決定資料匯出的項目，以及匯出中包含的項目

對於針對指定設定檔匯出的資料，請務必了解 決定要匯出至HTTP API目的地的資料的因素 和 匯出中包含的資料.

例如，將此資料流視為HTTP目標，其中資料流中選擇了三個段，四個屬性映射到目標。

匯出至目的地的設定檔可由符合以下條件之一或退出該條件的設定檔來決定 三個已對應區段. 不過，在資料匯出中， segmentMembership 物件(請參閱 匯出的資料 )，則如果該特定設定檔是其成員，則可能會顯示其他未映射的區段。 如果設定檔符合「使用德羅林汽車」區段的客戶資格，但同時也是「已觀看的回到未來」電影和科幻影迷區段的成員，則另外兩個區段也會出現在 segmentMembership 對象，即使這些對象未映射到資料流中。

從設定檔屬性的觀點來看，對上述四個屬性所做的任何變更將決定目的地匯出，而設定檔上呈現的四個對應屬性中的任何一個將出現在資料匯出中。

歷史資料回填

將新區段新增至現有目的地，或建立新目的地並將區段對應至該目的地時，Experience Platform會將歷史區段資格資料匯出至目的地。 符合區段資格的設定檔 befor 區段已新增至目的地後，大約一小時內就會匯出至目的地。

匯出的資料

已導出 Experience Platform 資料登陸 HTTP 目的地。 例如，以下匯出包含符合特定區段資格的設定檔、是其他兩個區段的成員，並退出另一個區段。 匯出內容也包含設定檔屬性名、姓氏、出生日期和個人電子郵件地址。 此設定檔的身分為ECID和電子郵件。

{
  "person": {
    "birthDate": "YYYY-MM-DD",
    "name": {
      "firstName": "John",
      "lastName": "Doe"
    }
  },
  "personalEmail": {
    "address": "john.doe@acme.com"
  },
  "segmentMembership": {
   "ups":{
      "7841ba61-23c1-4bb3-a495-00d3g5fe1e93":{
         "lastQualificationTime":"2022-01-11T21:24:39Z",
         "status":"exited"
      },
      "59bd2fkd-3c48-4b18-bf56-4f5c5e6967ae":{
         "lastQualificationTime":"2022-01-02T23:37:33Z",
         "status":"existing"
      },
      "947c1c46-008d-40b0-92ec-3af86eaf41c1":{
         "lastQualificationTime":"2021-08-25T23:37:33Z",
         "status":"existing"
      },
      "5114d758-ce71-43ba-b53e-e2a91d67b67f":{
         "lastQualificationTime":"2022-01-11T23:37:33Z",
         "status":"realized"
      }
   }
},
  "identityMap": {
    "ecid": [
      {
        "id": "14575006536349286404619648085736425115"
      },
      {
        "id": "66478888669296734530114754794777368480"
      }
    ],
    "email_lc_sha256": [
      {
        "id": "655332b5fa2aea4498bf7a290cff017cb4"
      },
      {
        "id": "66baf76ef9de8b42df8903f00e0e3dc0b7"
      }
    ]
  }
}

以下是匯出資料的進一步範例，具體取決於您在連線目的地流程中為 包含區段名稱 和 包含區段時間戳記 選項：

"segmentMembership": {
        "ups": {
          "5b998cb9-9488-4ec3-8d95-fa8338ced490": {
            "lastQualificationTime": "2019-04-15T02:41:50+0000",
            "status": "existing",
            "createdAt": 1648553325000,
            "updatedAt": 1648553330000,
            "mappingCreatedAt": 1649856570000,
            "mappingUpdatedAt": 1649856570000,
            "name": "First name equals John"
          }
        }
      }

"segmentMembership": {
        "ups": {
          "5b998cb9-9488-4ec3-8d95-fa8338ced490": {
            "lastQualificationTime": "2019-04-15T02:41:50+0000",
            "status": "existing",
            "createdAt": 1648553325000,
            "updatedAt": 1648553330000,
            "mappingCreatedAt": 1649856570000,
            "mappingUpdatedAt": 1649856570000,
          }
        }
      }

限制和重試策略

在95%的時間內，Experience Platform會嘗試為成功發送的消息提供少於10分鐘的吞吐量延遲，每個資料流每秒的請求速率小於10,000個，以到達HTTP目的地。

如果對您的HTTP API目的地提出失敗請求，Experience Platform會儲存失敗的請求並重試兩次，以將請求傳送至端點。

Business.Adobe.com 資源