外部資料來源

外部資料來源可讓您定義與協力廠商系統的連線，例如使用飯店訂房系統來檢查某人是否已登記客房。與內建的 Adobe Experience Platform 資料來源不同，您可以視需要儘量建立外部資料來源。

支援使用 POST 或 GET 以及傳回 JSON 的 REST API。支援 API 金鑰、基本和自訂驗證模式。

我們以一個氣象 API 服務為例，我想利用它根據即時氣象資料來自訂歷程的行為。

以下是 API 呼叫的兩個範例：

  • https://api.adobeweather.org/weather?city=London,uk&appid=1234
  • https://api.adobeweather.org/weather?lat=35&lon=139&appid=1234

此呼叫由主要 URL (https://api.adobeweather.org/weather)、兩個參數集 （"city" 代表城市、"lat/long" 代表經緯度）和 API 金鑰 (appid) 組成。

以下是建立和設定新外部資料來源的主要步驟：

  1. 從資料來源清單中，按一下 Add 以建立新的外部資料來源。

    這會開啟畫面右側的資料來源設定窗格。

  2. 輸入您的資料來源名稱。

    注意

    請勿使用空格或特殊字元。請勿使用超過 30 個字元。

  3. 新增說明至您的資料來源。此步驟為選填。

  4. 新增外部服務的 URL。在我們的範例中：https://api.adobeweather.org/weather。

    注意

    基於安全考量，我們強烈建議您使用 HTTPS。另請注意，我們不允許使用非公開的 Adobe 網址和 IP 位址。

  5. 根據外部服務配置設定身份驗證：No authentication、Basic、Custom 或 API key。有關自定義身份驗證模式的詳細資訊，請參閱本節。 在我們的範例中，我們選擇：

    • Type："API key"
    • Value："1234"（這是我們 API 金鑰的值）
    • Name："appid"（這是 API 金鑰參數名稱）
    • Location："Query parameter"（API 金鑰位於 URL）

  6. 按一下 Add a New Field Group，為每個 API 參數集新增欄位群組。請勿在欄位群組名稱中使用空格或特殊字元。在我們的範例中，我們需要建立兩個欄位群組，每個群各有一個參數集（city 及 long/lat）。

在 "long/lat" 參數集中，我們會建立包含下列資訊的欄位群組：

  • Used in：顯示使用欄位群組的歷程數量。您可以按一下 View journeys 圖示，以顯示使用此欄位群組的歷程清單。
  • Method：選取 POST 或 GET 方法。在本例中，我們選取 GET 方法。
  • Cache duration：在本例中，我們希望每 10 分鐘快取氣象一次。
  • Response Payload：在 Payload 欄位內按一下，並貼上呼叫傳回之有效負載的範例。例如，我們使用了氣象 API 網站上找到的有效負載。確認欄位類型是否正確。每次呼叫 API 時，系統都會擷取有效負載範例中包含的所有欄位。請注意，您可以按一下 Paste a new payload，以變更目前已傳遞的有效負載。
  • Dynamic Values：在本例中，輸入以逗號分隔的不同參數，即 "long,lat"。由於參數值視執行內容而定，因此它們會在歷程中定義。請參閱本頁。
  • Sent Payload：我們的範例不會出現此欄位，只有選取 POST 方法時才能使用。貼上會傳送至協力廠商系統的有效負載。

若是 GET 呼叫所需的參數，您會在 Parameters 欄位中輸入參數，系統就會在呼叫結束時自動新增這些參數。若是 POST 呼叫，您需要：

  • 在 Parameter 欄位中列出呼叫時要傳遞的參數（在以下範例中：“identifier”）。

  • 在已傳送有效負載的正文中，也使用完全相同的語法指定它們。若要這麼做，您必須新增："param": “name of your parameter”（在以下範例中：“identifier”）。請遵循下列語法：

    {"id":{"param":"identifier"}}

按一下 Save。

資料來源現在已設定完畢，且可供您在歷程中使用，例如在您的條件或個人化電子郵件中。如果溫度超過 30°C，您可以決定傳送特定通訊。

自訂驗證模式

此驗證模式會用於複雜驗證，常用來呼叫 OAuth2 這類 API 封裝通訊協定，以擷取要插入到動作之實際 HTTP 要求中的存取權杖。

當您設定自訂驗證時，可以按一下下方的按鈕，以檢查自訂驗證有效負載是否已正確設定。

如果測試成功，按鈕就會變成綠色。

使用此驗證的話，動作執行會是兩個步驟的流程：

  1. 呼叫端點以產生存取權仗。
  2. 以正確的方式插入存取權仗來呼叫 REST API。

此驗證分為兩個部分。

要呼叫的端點定義，用於產生存取權仗：

  • 端點：用於產生端點的 URL
  • 端點上的 HTTP 要求方法（GET 或 POST）
  • 標題：在此呼叫中插入做為標題的金鑰/值配對 (若有需要)
  • 正文：說明方法為 POST 時呼叫的正文。我們支援有限的正文結構，如 bodyParams (金鑰/值配對) 中所定義。bodyType 說明了呼叫內正文的格式和編碼：
    • 'form'：表示內容類型將會是 application/x-www-form-urlencoded（字元集 UTF-8），而金鑰/值配對將會序列化為：key1=value1&key2=value2&…
    • 'json'：表示內容類型將會是 application/json（字元集 UTF-8），而金鑰/值配對將會序列化為 JSON 物件，如下所示：{ "key1": "value1", "key2": "value2", …}

存取權杖插入動作之 HTTP 要求必須採用的方法定義：

  • authorizationType：定義如何將產生的存取權杖插入到動作的 HTTP 要求。可能的值包括：

    • bearer：表示存取權杖必須插入到「授權」標題，例如：Authorization: Bearer <access token>
    • header：表示存取權杖必須插入為標題，而標題的名稱會用屬性 tokenTarget 定義。舉例來說，若 tokenTarget 是 myHeader，則存取權杖會插入為標題，如下所示：myHeader: <access token>
    • queryParam：表示存取權杖必須插入為 queryParam，而查詢參數的名稱會由屬性 tokenTarget 定義。舉例來說，若 tokenTarget 是 myQueryParam，則動作呼叫的 URL 將會是：<url>?myQueryParam=<access token>

  • tokenInResponse：表示如何從驗證呼叫中擷取存取權杖。此屬性可以是：

    • 'response'：表示 HTTP 回應就是存取權杖
    • JSON 的選擇器（假設回應為 JSON，我們不支援 XML 等其他格式）。此選擇器的格式為 json://<path to the access token property>。舉例來說，若呼叫的回應是：{ "access_token": "theToken", "timestamp": 12323445656 }，tokenInResponse 將會是：json: //access_token

此驗證的格式為：

{
    "type": "customAuthorization",
    "authorizationType": "<value in 'bearer', 'header' or 'queryParam'>",
    (optional, mandatory if authorizationType is 'header' or 'queryParam') "tokenTarget": "<name of the header or queryParam if the authorizationType is 'header' or 'queryParam'>",
    "endpoint": "<URL of the authentication endpoint>",
    "method": "<HTTP method to call the authentication endpoint, in 'GET' or 'POST'>",
    (optional) "headers": {
        "<header name>": "<header value>",
        ...
    },
    (optional, mandatory if method is 'POST') "body": {
        "bodyType": "<'form'or 'json'>,
        "bodyParams": {
            "param1": value1,
            ...

        }
    },
    "tokenInResponse": "<'response' or json selector in format 'json://<field path to access token>'"
}

您可以針對自訂驗證資料來源變更權杖之快取期間的資訊。以下是自訂驗證有效負載的範例。會在　"cacheDuration"　參數中定義快取期間。其會指定快取中產生權杖的保留期間。單位可能是毫秒、秒、分鐘、小時、天、月、年。

"authentication": {
    "type":"customAuthorization",
    "authorizationType":"Bearer",
    "endpoint":"http://localhost:${port}/epsilon/oauth2/access_token",
    "method":"POST",
    "headers": {
        "Authorization":"Basic EncodeBase64(${epsilonClientId}:${epsilonClientSecret})"
        },
    "body": {
        "bodyType":"form",
        "bodyParams": {
             "scope":"cn mail givenname uid employeeNumber",
             "grant_type":"password",
             "username":"${epsilonUserName}",
             "password":"${epsilonUserPassword}"
             }
        },
    "tokenInResponse":"json://access_token",
    "cacheDuration":
             { "duration":5, "timeUnit":"seconds" }
    }

本頁內容