Show Menu
主題×

外部 API

說明

External API 活動會透過 HTTP API 呼叫,從​ 外部系統 ​將資料匯入工作流程中。
外部系統端點可以是公用 API 端點、客戶管理系統或無伺服器應用程式執行個體(例如 Adobe I/O Runtime ),以及一些類別。
基於安全性原因,Campaign Standard 不支援使用 JSSP。如果您需要執行程式碼,可以透過外部 API 活動呼叫 Adobe I/O Runtime 執行個體。
本活動的主要特點是:
  • 能夠將 JSON 格式的資料傳遞至第三方 REST API 端點
  • 能夠重新接收 JSON 回應、將它對應至輸出表格,並傳遞至下游的其他工作流程活動。
  • 具有出站特定轉變的故障管理

從測試版過渡到正式上市

在 Campaign Standard 20.3 版本中,外部 API 功能將測試版移至一般可用性 (GA)。
因此,如果您使用測試版外部 API 活動,則需要在所有工作流程中以 GA 外部 API 活動來取代這些活動。  使用 External API 測試版的工作流程將從 20.3 版開始停止運作。
取代外部 API 活動時,將新的外部 API 活動新增至工作流程、手動複製設定詳細資訊,然後刪除舊活動。
您將無法複製標題值,因為這些值在活動中被遮罩。
接著,重新設定工作流程中指向及/或使用測試版外部 API 活動資料的其他活動,以指向及/或使用新外部 API 活動的資料。活動範例:電子郵件傳送(個人化欄位)、擴充活動等。

限制和護欄

以下護欄適用於此活動:
  • 50MBhttp回應資料大小限制(建議使用5MB)
  • 請求逾時為 10 分鐘
  • 不允許 HTTP 重新導向
  • 拒絕非 HTTPS Url
  • 允許使用 "Accept: application/json" 要求標頭及 "Content-Type: application/json" 回應標頭
從Campaign 20.4版開始,http回應資料大小限制和回應逾時護欄將分別降低為5MB和1分鐘。 雖然這項變更只會影響新的外部API活動,但強烈建議目前外部API活動的實施與這些新的防護欄一致,以遵循最佳實務。
已設定好 JSON 的特定防護欄:
  • JSON 深度上限 :將可處理的自訂巢狀 JSON 的深度上限限制為 10 個層級。
  • JSON 金鑰長度上限 :將內部密鑰的最大長度限制為 255。此鍵與欄 ID 相關聯。
  • 允許的 JSON 重複金鑰上限 :將作為欄 ID 的重複 JSON 屬性名稱的總數上限為 150。
活動不支援 JSON 結構,如下:
  • 將陣列對象與其他非陣列元素組合
  • JSON 陣列物件是巢狀內嵌在一或多個中間陣列物件中。
「外部API」活動是指擷取促銷活動範圍的資料(最新選件集、最新分數等),而非擷取每個描述檔的特定資訊,因為這會導致大量資料傳輸。 如果使用案例需要此項目,建議使用 傳輸檔案 活動。

設定

External API 活動拖放到工作流程中,並開啟活動以啟動設定。

入站對應

入站對應是由先前入站活動產生的臨時表格,將在 UI 中顯示為 JSON 並發送。 根據此臨時表格,使用者可以對入站資料進行修改。
入站資源 ​下拉式功能表可讓您選取將建立臨時表格的查詢活動。
新增計數參數 ​核取方塊將為來自臨時表格的每行新增計數值。請注意,此核取方塊僅在入站活動產生臨時表格時才可用。
入站欄 ​區段可讓使用者從入站轉變表格中新增任何欄位。選取的欄將是資料物件中的金鑰。JSON 中的資料物件將是陣列清單,包含入站轉變表格各列所選欄的資料。
自訂參數 ​文字方塊可讓您新增有效的 JSON 及外部 API 所需的其他資料。此額外資料將新增至產生的 JSON 中的 params 物件。

出站對應

此標籤可讓您定義 API 呼叫傳回的範例 JSON 結構
JSON 剖析器的設計可容納標準 JSON 結構模式類型,但有些例外。標準模式的範例是: {“data”:[{“key”:“value”}, {“key”:“value”},...]}
範例 JSON 定義必須具有​ 下列特性
  • 陣列元素 ​必須包含第一級屬性(不支援較深的層級)。 屬性名稱 ,最終將成為輸出臨時表格之輸出模式的欄名稱。
  • 要擷取的 JSON 元素 ​必須在 JSON 回應內的 10 級或更低巢狀層級。
  • 欄名稱 ,定義是以 "data" 陣列的第一個元素為基礎。 列定義(新增/刪除)和屬性的類型值可以在 Column definition 索引標籤中編輯。
平面化核取方塊 ​行為:
「平面化」核取方塊(預設值:未勾選),以指出是否將 JSON 平面化為索引鍵/值對應。
  • 停用核取方塊 (未勾選)時,會剖析範例 JSON 以尋找陣列物件。使用者將需要提供 API 回應範例 JSON 格式的裁剪版本,如此 Adobe Campaign 就能確切判斷使用者想要使用哪個陣列。在工作流程製作時,將會判斷並記錄巢狀陣列物件的路徑,以便在執行時使用它來存取從 API 呼叫接收的 JSON 回應內文中存取該陣列物件。
  • 啟用核取方塊 (已核取)後,範例 JSON 將會平面化,而提供之範例 JSON 中指定的所有屬性將用於建立輸出臨時表格的欄,並顯示在 Column Definitions 標籤上。請注意,如果範例 JSON 中有任何陣列物件,則這些陣列物件的所有元素也會平面化。
如果已​ 驗證解析 ,則會出現一條訊息,邀請您在「列定義」索引標籤中自訂資料對應。在其他情況下,會顯示錯誤訊息。

執行

此索引標籤可讓您定義將傳送資料至 ACS 的 HTTPS 端點 。如有需要,您可在下列欄位中輸入驗證資訊。

屬性

此標籤可讓您控制外部 API 活動的​ 一般屬性 ,例如 UI 中顯示的標籤。無法自訂內部 ID。

欄定義

在 Outbound Mapping 索引標籤中完成並驗證​ 回應資料格式 ​時,將顯示此索引標籤。
Column definition 索引標籤可讓您精確指定每欄的資料結構,以匯入不含任何錯誤的資料,並使其符 Adobe Campaign 資料庫中已存在的類型,以供日後作業使用。
例如,您可以變更欄的標籤,並選取其類型(字串、整數、日期等)或甚至指定錯誤處理。
如需詳細資訊,請參閱 載入檔案 區段。

轉變

此索引標籤可讓您啟用​ 出站轉變 ​及其標籤。在​ 逾時 ​或負載超過​ 資料大小限制 ​時,此特定轉變很實用。

執行選項

此標籤可用於大部分的工作流程活動。如需詳細資訊,請參閱 活動屬性 區段。

疑難排解

此新工作流程活動中新增了兩種類型的日誌訊息:資訊與錯誤。它們可協助您疑難排解潛在問題。

資訊

這些日誌訊息用於在工作流程活動執行期間記錄有關有用檢查點的資訊。具體來說,下列記錄訊息可用來記錄第一次嘗試存取 API 的重試嘗試(以及首次嘗試失敗的原因)。
訊息格式 範例
叫用 API URL '%s'。
叫用 API URL 'https://example.com/api/v1/web-coupon?count=2'。
重試 API URL '%s',先前嘗試失敗('%s')。
重試 API URL 'https://example.com/api/v1/web-coupon?count=2',先前嘗試失敗 ('HTTP - 401')。
正在傳輸 '%s'(%s / %s) 的內容。
從 'https://example.com/api/v1/web-coupon?count=2'(1234 / 1234) 傳輸內容。

錯誤

這些日誌訊息用於記錄有關可能最終導致工作流程活動失敗的意外錯誤條件的資訊。
代碼 – 訊息格式 範例
WKF-560250 – 超出 API 要求內文限制 (限制:'%d')。
已超出 API 要求內文限制 (限制:'5242880')。
WKF-560239 – 超出 API 回應限制 (限制:'%d')。
已超出 API 回應限制 (限制:5242880')。
WKF-560245 – 無法剖析 API URL (錯誤:'%d')。
無法剖析 API URL (錯誤:'-2010')。
注意:當 API URL 失敗驗證規則時,會記錄此錯誤。
WKF-560244 - API URL主機不能是 'localhost' 或 IP 位址常值 (URL 主機:'%s')。
API URL主機不得是 'localhost' 或IP位址常值 (URL 主機: 'localhost' )。
API URL主機不得是 'localhost' 或IP位址常值 (URL 主機:192.168.0.5')。
API URL主機不得是 'localhost' 或 IP 位址常值 (URL 主機:'[2001]')。
WKF-560238 - API URL必須是安全URL (https) (請求的 URL:'%s')。
API URL 必須是安全 URL(https) (請求的 URL:'https://example.com/api/v1/web-coupon?count=2’)。
WKF-560249 – 無法建立請求內文 JSON。新增 '%s' 時出錯。
無法建立請求正文 JSON。新增 'params' 時出錯。
無法建立請求正文 JSON。新增 'data' 時發生錯誤。
WKF-560246 - HTTP 標頭鍵錯誤(標頭鍵:'%s')。
HTTP 標頭鍵錯誤 (標頭鍵:'%s')。
注意:當自訂標頭密鑰根據 RFC 驗證失敗時,將記錄此錯誤
WKF-560248 – 不允許 HTTP 標頭鍵 (標頭鍵:'%s')。
不允許 HTTP 標題鍵 (標題鍵:'接受')。
WKF-560247 - AHTTP 標頭值錯誤 (標頭值:'%s')。
HTTP 標頭值錯誤 (標頭值:'%s')。
注意:當自訂標頭值根據 RFC 驗證失敗時,將記錄此錯誤
WKF-560240 - JSON 裝載有不良屬性 '%s'。
JSON 裝載包含不正確的屬性 'plash'。
WKF-560241 – 格式錯誤的 JSON 或不可接受的格式。
格式錯誤的 JSON 或不可接受的格式。
注意:此訊息僅適用於從外部 API 剖析回應內文,並在嘗試驗證回應內文是否符合本練習規定的 JSON 格式時記錄。
WKF-560246 – 活動失敗 (原因:'%s')。
當活動因 HTTP 401 錯誤回應而失敗時 – 活動失敗 (原因:'HTTP - 401')
當活動因內部呼叫失敗而失敗時 – 活動失敗 (原因:'iRc - -Nn')。
當活動因無效的內容類型標題而失敗時。-活動失敗(原因:'Content-Type - application/html')。