外部資料來源 external-data-sources
外部資料來源可讓您定義與協力廠商系統的連線，例如使用飯店訂房系統來檢查某人是否已登記客房。與內建的 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) 組成。
以下是建立和設定新外部資料來源的主要步驟：
-
從資料來源清單中，按一下 建立資料Source 以建立新的外部資料來源。
這會開啟畫面右側的資料來源設定窗格。
-
輸入您的資料來源名稱。
note note NOTE 只允許使用英數字元和底線。 長度上限為30個字元。 -
新增說明至您的資料來源。此步驟為選填。
-
新增外部服務的 URL。在我們的範例中：https://api.adobeweather.org/weather。
note caution CAUTION 基於安全考量，我們強烈建議您使用 HTTPS。另請注意，我們不允許使用非公開的 Adobe 網址和 IP 位址。 
-
根據外部服務組態設定驗證： 無驗證、基本、自訂 或 API金鑰。
對於基本驗證模式，您需要填寫使用者名稱和密碼。
note note NOTE 執行驗證呼叫時，會在Authentication標頭中新增以base64編碼的 <username>:<password>字串。如需自訂驗證模式的詳細資訊，請參閱本節。 在我們的範例中，我們選擇API金鑰驗證模式：
- 型別： "API金鑰"
- 名稱： "appid" （這是API金鑰引數名稱）
- 值： "1234" （這是我們API金鑰的值）
- 位置： "Query parameter" （API金鑰位於URL）
-
按一下 新增欄位群組，為每個API引數集新增欄位群組。 欄位群組名稱中只允許使用英數字元和底線。 長度上限為30個字元。 在我們的範例中，我們需要建立兩個欄位群組，每個群各有一個參數集（city 及 long/lat）。
在 "long/lat" 參數集中，我們會建立包含下列資訊的欄位群組：
-
用於：顯示使用欄位群組的歷程次數。 您可以按一下 檢視歷程 圖示，以顯示使用此欄位群組的歷程清單。
-
方法：選取POST或GET方法。 在本例中，我們選取 GET 方法。
-
動態值：在本例中，輸入以逗號分隔的不同引數，即「long，lat」。 由於參數值視執行內容而定，因此它們會在歷程中定義。了解更多
-
回應承載：在 承載 欄位內按一下，並貼上呼叫傳回之承載的範例。 例如，我們使用了氣象 API 網站上找到的有效負載。確認欄位類型是否正確。每次呼叫 API 時，系統都會擷取有效負載範例中包含的所有欄位。請注意，如果要變更目前傳遞的裝載，可以按一下 貼上新的裝載。
-
已傳送裝載：此欄位未出現在我們的範例中。 只有選取 POST 方法時才能使用。貼上會傳送至協力廠商系統的有效負載。
若是GET呼叫所需的引數，您會在 動態值 欄位中輸入引數，呼叫結束時會自動新增這些引數。 若是 POST 呼叫，您需要：
-
在 動態值 欄位中列出呼叫時要傳遞的引數（在以下範例中：「識別碼」）。
-
在已傳送有效負載的正文中，也使用完全相同的語法指定它們。若要這麼做，您必須新增："param"： 「name of your parameter」 （在以下範例中：「identifier」）。 請遵循下列語法：
code language-json {"id":{"param":"identifier"}}
按一下 儲存。
資料來源現在已設定完畢，且可供您在歷程中使用，例如在您的條件或個人化電子郵件中。如果溫度超過 30°C，您可以決定傳送特定通訊。
自訂驗證模式 custom-authentication-mode
此驗證模式會用於複雜驗證，常用來呼叫 OAuth2 這類 API 封裝通訊協定，以擷取要插入到動作之實際 HTTP 要求中的存取權杖。
當您設定自訂驗證時，可以按一下下方的按鈕，以檢查自訂驗證有效負載是否已正確設定。
如果測試成功，按鈕就會變成綠色。
使用此驗證的話，動作執行會是兩個步驟的流程：
- 呼叫端點以產生存取權仗。
- 以正確的方式插入存取權仗來呼叫 REST API。
要呼叫的端點定義，用於產生存取權杖 custom-authentication-endpoint
-
endpoint：用來產生端點的URL -
端點（
GET或POST）上的HTTP要求方法 -
headers：必要時，在此呼叫中插入做為標題的機碼值組 -
body：說明呼叫的主體(如果方法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要求必須採用的方式定義 custom-authentication-access-token
-
authorizationType：定義如何將產生的存取權杖插入動作的HTTP呼叫。 可能的值包括：
bearer：表示存取權杖必須插入到Authorization標頭中，例如： 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",
"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": {
(optional, mutually exclusive with 'duration') "expiryInResponse": "<json selector in format 'json://<field path to expiry>'",
(optional, mutually exclusive with 'expiryInResponse') "duration": <integer value>,
"timeUnit": "<unit in 'milliseconds', 'seconds', 'minutes', 'hours', 'days', 'months', 'years'>"
},
"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'>",
}
您可以針對自訂驗證資料來源變更權杖之快取期間的資訊。以下是自訂驗證有效負載的範例。快取期間在cacheDuration引數中定義。 其會指定快取中產生權杖的保留期間。單位可能是毫秒、秒、分鐘、小時、天、月、年。
以下是持有人驗證型別的範例：
{
"type": "customAuthorization",
"endpoint": "https://<your_auth_endpoint>/epsilon/oauth2/access_token",
"method": "POST",
"headers": {
"Authorization": "Basic EncodeBase64(<epsilon Client Id>:<epsilon Client Secret>)"
},
"body": {
"bodyType": "form",
"bodyParams": {
"scope": "cn mail givenname uid employeeNumber",
"grant_type": "password",
"username": "<epsilon User Name>",
"password": "<epsilon User Password>"
}
},
"tokenInResponse": "json://access_token",
"cacheDuration": {
"duration": 5,
"timeUnit": "minutes"
},
},
以下是標頭驗證型別的範例：
{
"type": "customAuthorization",
"endpoint": "https://myapidomain.com/v2/user/login",
"method": "POST",
"headers": {
"x-retailer": "any value"
},
"body": {
"bodyType": "form",
"bodyParams": {
"secret": "any value",
"username": "any value"
}
},
"tokenInResponse": "json://token",
"cacheDuration": {
"expiryInResponse": "json://expiryDuration",
"timeUnit": "minutes"
},
"authorizationType": "header",
"tokenTarget": "x-auth-token"
}
以下是登入API呼叫的回應範例：
{
"token": "xDIUssuYE9beucIE_TFOmpdheTqwzzISNKeysjeODSHUibdzN87S",
"expiryDuration" : 5
}