[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是相互驗證的端對端安全性方法，可確保共用資訊的雙方在共用資料之前，都是聲稱的身分。 與TLS相比，mTLS包含額外的步驟，其中伺服器也會要求使用者端的憑證，並在其結尾加以驗證。

如果您想要搭配HTTP API個目的地使用mTLS，您放入目的地詳細資料頁面的伺服器位址必須停用TLS通訊協定，而且只能啟用mTLS。 如果端點上仍啟用TLS 1.2通訊協定，則不會傳送使用者端驗證的憑證。 這表示若要搭配您的HTTP API目的地使用mTLS，您的「接收」伺服器端點必須是僅限mTLS啟用的連線端點。

下載憑證 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資料以JSON格式登陸您的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":"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會儲存失敗的請求並重試兩次，以將請求傳送至您的端點。