HTTP API連接

總覽

HTTP API目標是 Adobe Experience Platform 流目標，幫助您將配置檔案資料發送到第三方HTTP終結點。

要向HTTP終結點發送配置檔案資料，必須首先 連接到目標 在 Adobe Experience Platform。

使用案例

HTTP API目標允許您將XDM配置檔案資料和訪問群體段導出到通用HTTP終結點。 在此，您可以運行自己的分析，或對導出出Experience Platform的配置檔案資料執行可能需要的任何其他操作。

HTTP端點可以是客戶自己的系統或第三方解決方案。

導出類型和頻率

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

先決條件

要使用HTTP API目標導出Experience Platform外的資料，必須滿足以下先決條件：

• 必須具有支援REST API的HTTP終結點。
• 您的HTTP終結點必須支援Experience Platform配置檔案架構。 HTTP API目標中不支援對第三方負載架構的轉換。 請參閱 導出的資料 的子節。
• HTTP終結點必須支援標頭。

IP地址允許清單

為滿足客戶的安全性和合規性要求，Experience Platform提供了一個靜態IP清單，您可以允許列出該HTTP API目標。 請參閱 流目標的IP地址允許清單 清單。

支援的身份驗證類型

HTTP API目標支援對HTTP終結點的多種身份驗證類型：

• 無驗證的HTTP終結點；
• 持有者令牌認證；
• OAuth 2.0客戶端憑據 驗證主體形式，使用 client ID。 client secret 和 grant type 在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>'

• 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 標題 將base64編碼併發送到目標。 有關示例，請參見 支援的身份驗證類型 的子菜單。

目標詳細資訊

建立到HTTP終結點的身份驗證連接後，請提供目標的以下資訊：

• 名稱:輸入將來用於識別此目標的名稱。
• 說明:輸入將幫助您在將來確定此目標的說明。
• 標題:按照以下格式輸入要包括在目標調用中的任何自定義標頭： header1:value1,header2:value2,...headerN:valueN。
• HTTP終結點:要將配置檔案資料發送到的HTTP終結點的URL。
• 查詢參數:也可以將查詢參數添加到HTTP終結點URL。 設定您使用的查詢參數的格式如下： parameter1=value&parameter2=value。
• 包括段名稱:如果希望資料導出包含要導出的段的名稱，則切換。 有關選擇此選項的資料導出示例，請參閱 導出的資料 的下一頁。
• 包括段時間戳:如果希望資料導出包括建立和更新段時的UNIX時間戳，以及將段映射到要激活的目標時的UNIX時間戳，則切換。 有關選擇此選項的資料導出示例，請參閱 導出的資料 的下一頁。

將段激活到此目標

請參閱 激活受眾資料以流式處理配置檔案導出目標 有關激活此目標受眾段的說明。

目標屬性

在 選擇屬性 步驟，Adobe建議您從 聯合架構。 選擇要導出到目標的唯一標識符和任何其他XDM欄位。

配置檔案導出行為

Experience Platform可優化配置檔案導出行為到HTTP API目標，以便在經過段限定或其他重要事件之後對配置檔案進行相關更新時，才將資料導出到API終結點。 配置式在以下情況下導出到目標：

• 配置檔案更新由映射到目的地的至少一個段的段成員資格的改變確定。 例如，配置檔案已限定映射到目標的段之一或已退出映射到目標的段之一。
• 配置檔案更新由 身份映射。 例如，已為映射到目標的段之一限定的配置檔案已在標識映射屬性中添加了新標識。
• 配置檔案更新由映射到目的地的至少一個屬性的屬性的改變確定。 例如，映射步驟中映射到目標的屬性之一被添加到配置檔案。

在上述所有情況下，只將發生相關更新的配置檔案導出到目標。 例如，如果映射到目標流的段有100個成員，並且有5個新配置檔案符合該段的條件，則向目標的導出是增量的，並且只包括5個新配置檔案。

請注意，無論更改位於何處，都會為配置檔案導出所有映射的屬性。 因此，在上面的示例中，即使屬性本身沒有更改，也會導出這五個新配置檔案的所有映射屬性。

什麼決定資料導出以及導出中包含的內容

對於為給定配置檔案導出的資料，瞭解以下兩個不同概念非常重要 決定資料導出到HTTP API目標的內容 和 資料包含在導出中。

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

導出到目標的配置檔案可由符合或退出其中一個配置檔案來確定 三個映射段。 但是，在資料導出中，在 segmentMembership 對象（請參見） 導出的資料 )中，如果特定配置檔案是其成員，則可能會顯示其他未映射的段。 如果配置檔案符合DeLorean Cars分部客戶的資格，但也是受觀看的「回到未來」電影和科幻片迷分部的成員，則另外兩個分部也將出現在 segmentMembership 資料導出的對象，即使這些對象未映射到資料流中。

從配置檔案屬性的視點來看，對上述四個屬性的任何更改都將確定目標導出，並且配置檔案上存在的四個映射屬性中的任何一個都將出現在資料導出中。

歷史資料回填

當您將新段添加到現有目標或建立新目標並將段映射到該目標時，Experience Platform會將歷史段限定資料導出到目標。 限定段的配置檔案 先 已添加到目標的段在大約一小時內導出到目標。

導出的資料

已導出 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":"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 API目標發出失敗請求，Experience Platform將儲存失敗的請求並重試兩次，以將請求發送到終結點。