[Ultimate]{class="badge positive"}

HTTP API連線

概觀 overview

HTTP API目的地是 Adobe Experience Platform 可協助您將設定檔資料傳送至第三方HTTP端點的串流目的地。

若要傳送設定檔資料至HTTP端點，您必須先 連線到目的地 在 Adobe Experience Platform.

使用案例 use-cases

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

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

支援的對象 supported-audiences

本節說明您可以將哪些型別的對象匯出至此目的地。

匯出型別和頻率 export-type-frequency

請參閱下表以取得目的地匯出型別和頻率的資訊。

先決條件 prerequisites

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

mTLS通訊協定支援和憑證 mtls-protocol-support

您可以使用 Mutual Transport Layer Security (mTLS)，以確保與您的HTTP API目的地連線的輸出連線具有增強的安全性。

mTLS 是一種用於相互驗證的端對端安全性方法，可確保共用資訊的雙方在共用資料之前都是聲稱的身分。 mTLS 包含額外的步驟，以便 TLS，其中伺服器也會要求使用者端的憑證，並在其末端進行驗證。

如果您想使用 mTLS 替換為 HTTP API 目的地，也就是您放入 目的地詳細資料 頁面必須具有 TLS 通訊協定已停用，且僅限 mTLS 已啟用。 如果 TLS 端點上的1.2通訊協定仍處於啟用狀態，不會為使用者端驗證傳送任何憑證。 這表示要使用 mTLS 與您的 HTTP API 目的地，您的「接收」伺服器端點必須是 mTLS-only啟用的連線端點。

下載憑證 certificate

如果您想檢查 Common Name (CN)和 Subject Alternative Names (SAN)若要進行其他協力廠商驗證，您可以下載以下憑證：

IP位址允許清單 ip-address-allowlist

為了滿足客戶的安全性和合規性要求，Experience Platform提供您可以允許列出HTTP API目的地的靜態IP清單。 請參閱 串流目的地的IP位址允許清單 以取得加入允許清單的IP完整清單。

支援的驗證型別 supported-authentication-types

HTTP API目的地支援多種對HTTP端點的驗證型別：

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>'

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'

連線到目的地 connect-destination

若要連線至此目的地，請遵循以下說明的步驟： 目的地設定教學課程. 連線到這個目的地時，您必須提供下列資訊：

驗證資訊 authentication-information

持有人權杖驗證 bearer-token-authentication

如果您選取 持有人權杖 驗證型別以連線至您的HTTP端點，輸入以下欄位並選取 連線到目的地：

無驗證 no-authentication

如果您選取 無 要連線至您的HTTP端點的驗證型別：

當您選取此驗證開啟時，您只需要選取 連線到目的地 而且已建立與端點的連線。

OAuth 2密碼驗證 oauth-2-password-authentication

如果您選取 OAuth 2密碼 驗證型別以連線至您的HTTP端點，輸入以下欄位並選取 連線到目的地：

OAuth 2使用者端憑證驗證 oauth-2-client-credentials-authentication

如果您選取 OAuth 2使用者端認證 驗證型別以連線至您的HTTP端點，輸入以下欄位並選取 連線到目的地：

填寫目的地詳細資料 destination-details

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

啟用警示 enable-alerts

您可以啟用警報以接收有關傳送到您目的地的資料流狀態的通知。 從清單中選取警報以訂閱接收有關資料流狀態的通知。 如需警示的詳細資訊，請參閱以下指南： 使用UI訂閱目的地警報.

當您完成提供目的地連線的詳細資訊時，請選取「 」 下一個.

啟用此目的地的對象 activate

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

目的地屬性 attributes

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

設定檔匯出行為 profile-export-behavior

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

在上述所有情況下，只有已發生相關更新的設定檔才會匯出至您的目的地。 例如，如果對應至目的地流程的受眾有一百個成員，且有五個新設定檔符合區段的資格，則匯出至您的目的地的作業將以漸進方式進行，且僅包含五個新設定檔。

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

決定資料匯出的因素及匯出中包含的因素 what-determines-export-what-is-included

針對針對指定設定檔匯出的資料，瞭解以下兩個不同的概念是很重要的 決定匯出至HTTP API目的地的資料內容 和 哪些資料包含在匯出中.

例如，將此資料流視為HTTP目的地，其中在資料流中選取了三個對象，且四個屬性對應至目的地。

要判斷匯出至目的地的設定檔是否符合「 」或「 」其中之一， 三個對應的區段. 不過，在資料匯出中，在 segmentMembership 物件(請參閱 匯出的資料 區段底下)，其他未對應的對象可能會出現，如果該特定設定檔為其成員，且這些對象與觸發匯出的對象共用相同的合併原則。 如果設定檔符合 擁有DeLorean Cars的客戶 區段，但同時也是 觀看「回到未來」 影片和 科幻迷 區段，則其他這兩個對象也會出現在 segmentMembership 匯出的物件，即使這些物件未在資料流中對映，只要它們與共用相同的合併原則 擁有DeLorean Cars的客戶 區段。

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

歷史資料回填 historical-data-backfill

當您新增對象至現有目的地，或當您建立新目的地並將對象對應至該目的地時，Experience Platform會將歷史對象資格資料匯出至該目的地。 符合對象資格的設定檔 早於 新增至目的地的對象會在約一小時內匯出至目的地。

匯出的資料 exported-data

您的匯出 Experience Platform 資料進入您的 HTTP JSON格式的目的地。 例如，下列匯出包含符合特定區段資格的設定檔、是另一個兩個區段的成員，且已退出另一個區段。 匯出也包含設定檔屬性的名字、姓氏、出生日期和個人電子郵件地址。 此設定檔的身分識別為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":"realized"
      },
      "947c1c46-008d-40b0-92ec-3af86eaf41c1":{
         "lastQualificationTime":"2021-08-25T23:37:33Z",
         "status":"realized"
      },
      "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"
      }
    ]
  }
}

以下為更多匯出資料範例，視您在連線目的地流程中選取的UI設定而定 包含區段名稱 和 包含區段時間戳記 選項：

"segmentMembership": {
        "ups": {
          "5b998cb9-9488-4ec3-8d95-fa8338ced490": {
            "lastQualificationTime": "2019-04-15T02:41:50+0000",
            "status": "realized",
            "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": "realized",
            "createdAt": 1648553325000,
            "updatedAt": 1648553330000,
            "mappingCreatedAt": 1649856570000,
            "mappingUpdatedAt": 1649856570000,
          }
        }
      }

限制和重試原則 limits-retry-policy

在95%的時間中，Experience Platform會嘗試針對每個資料流向HTTP目的地的成功傳送訊息，以每秒少於10,000個要求的速率，提供少於10分鐘的輸送量延遲。

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