外部 API external-api
說明 description
External API 活動會透過 HTTP API 呼叫，從 外部系統 將資料帶入工作流程中。
外部系統端點可以是公用 API 端點、客戶管理系統或無伺服器應用程式執行個體（例如 Adobe I/O Runtime），以及一些類別。
本活動的主要特點是：
- 能夠將 JSON 格式的資料傳遞至第三方 REST API 端點
- 能夠重新接收 JSON 回應、將它對應至輸出表格，並傳遞至下游的其他工作流程活動。
- 具有出站特定轉變的故障管理
回溯相容性注意事項 from-beta-to-ga
在Campaign Standard 20.4版本中，http回應資料大小限制和回應逾時護欄已降低，以符合最佳實務 — 請參閱限制和護欄。 這些護欄修改不會對現有的外部 API 活動產生影響；因此，建議您在所有工作流程中，以新版本取代現有的外部 API 活動。
取代外部 API 活動時，將新的外部 API 活動新增至工作流程、手動複製設定詳細資訊，然後刪除舊活動。
限制和護欄 guardrails
以下護欄適用於此活動：
- 5MB http 回應資料大小限制（注意：這與之前版本中 50MB 的限制有所不同）
- 請求逾時為 1 分鐘（注意：這與之前版本中 10 分鐘逾時有所不同）
- 不允許 HTTP 重新導向
- 拒絕非 HTTPS Url
- 允許使用 "Accept: application/json" 要求標頭及 "Content-Type: application/json" 回應標頭
具體的護欄已經到位：
- JSON 深度上限：將可處理的自訂巢狀 JSON 的深度上限限制為 10 個層級。
- JSON 金鑰長度上限：將內部密鑰的最大長度限制為 255。此鍵與欄 ID 相關聯。
- 允許的 JSON 重複金鑰上限：將作為欄 ID 的重複 JSON 屬性名稱的總數上限為 150。
設定 configuration
將 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 中有任何陣列物件，則這些陣列物件的所有元素也會平面化。
如果已 驗證解析，則會出現一條訊息，邀請您在「列定義」索引標籤中自訂資料對應。在其他情況下，會顯示錯誤訊息。
執行
此索引標籤可讓您定義連接端點。URL 欄位可讓您定義將與Campaign Standard通訊的 HTTPS端點。
如果端點需要，則可以使用兩種型別的驗證方法：
-
基本驗證：在 Request Header(s) 區段中輸入您的使用者名稱/密碼資訊。
-
OAuth驗證：按一下外部帳戶中的 Use connection parameters defined in an external account，您可以選取定義OAuth驗證的外部帳戶。 如需詳細資訊，請參閱外部帳戶。
屬性
此索引標籤可讓您控制外部 API 活動的 一般屬性，例如， UI 中顯示的標籤。無法自訂內部 ID。
欄定義
Column definition 索引標籤可讓您精確指定每欄的資料結構，以匯入不含任何錯誤的資料，並使其符 Adobe Campaign 資料庫中已存在的類型，以供日後作業使用。
例如，您可以變更欄的標籤，並選取其類型（字串、整數、日期等）或甚至指定錯誤處理。
如需詳細資訊，請參閱載入檔案區段。
轉變
此索引標籤可讓您啟用 出站轉變 及其標籤。在 逾時 或負載超過 資料大小限制 時，此特定轉變很實用。
執行選項
此索引標籤可用於大部分的工作流程活動。如需詳細資訊，請參閱活動屬性區段。
測試
若要使用簡單的測試端點來測試外部API功能，您可以使用Postman Echo： https://docs.postman-echo.com。
疑難排解
此新工作流程活動中新增了兩種類型的日誌訊息：資訊與錯誤。它們可協助您疑難排解潛在問題。
資訊
這些日誌訊息用於在工作流程活動執行期間記錄有關有用檢查點的資訊。
錯誤次數
這些日誌訊息用於記錄有關可能最終導致工作流程活動失敗的意外錯誤條件的資訊。
無法剖析 API URL（錯誤：'-2010'）。
注意：當 API URL 失敗驗證規則時，會記錄此錯誤。
API URL主機不得是 'localhost' 或 IP 位址常值（URL 主機： 'localhost'）。
API URL主機不得是 'localhost' 或 IP 位址常值（URL 主機：192.168.0.5'）。
API URL主機不得是 'localhost' 或 IP 位址常值（URL 主機：'[2001]'）。
無法建立請求正文 JSON。新增 'params' 時出錯。
無法建立請求正文 JSON。新增 'data' 時發生錯誤。
HTTP header key is bad (header key: '%s').
注意：當自訂標頭密鑰根據 RFC 驗證失敗時，將記錄此錯誤
HTTP header value is bad (header value: '%s').
注意：當自訂標頭值根據 RFC 驗證失敗時，將記錄此錯誤
格式錯誤的 JSON 或不可接受的格式。
注意：此訊息僅適用於從外部 API 剖析回應內文，並在嘗試驗證回應內文是否符合本練習規定的 JSON 格式時記錄。
當活動因 HTTP 401 錯誤回應而失敗時 – 活動失敗（原因：'HTTP - 401'）
當活動因內部呼叫失敗而失敗時 – 活動失敗（原因：'iRc - -Nn'）。
當活動因無效的內容類型標題而失敗時。- 活動失敗（原因：'Content-Type - application/html'）。