本頁面由 Cloud Translation API 翻譯而成。

查看 Application Integration 支援的連接器。

連接器工作

連接器工作可讓您使用整合連接器中提供的即用型連接器，從整合作業快速且安全地連線至各種 Google Cloud 服務和其他商業應用程式。

如需應用程式整合功能支援的所有連接器清單，請參閱「連接器參考資料」。

事前準備

請確認您已在 Google Cloud 專案中獲得連接器管理員 (roles/connectors.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理存取權」。
瞭解 Integration Connectors 的一般概念。
如要使用連接器連線至 Google Cloud 服務和其他商務應用程式，請務必將使用者代管的服務帳戶附加至整合作業。如果整合作業未設定使用者自管服務帳戶，系統會預設使用預設服務帳戶 (service-PROJECT_NUMBER@gcp-sa-integrations.iam.gserviceaccount.com) 進行驗證。
請確認服務帳戶具備必要的 IAM 角色。如要瞭解如何將角色授予服務帳戶，請參閱「管理服務帳戶的存取權」。

新增連接器工作

如要在整合中新增 Connectors 工作，請按照下列步驟操作：

前往 Google Cloud 控制台的「Application Integration」頁面。
前往「應用程式整合」
在導覽選單中，按一下「整合」。
系統隨即會顯示「Integrations」頁面，列出 Google Cloud 專案中可用的所有整合功能。
選取現有的整合，或按一下「建立整合」來建立新的整合。
如果您要建立新的整合功能：
1. 在「Create Integration」窗格中輸入名稱和說明。
2. 選取整合作業的區域。
  注意：「Regions」下拉式選單只會列出 Google Cloud 專案中已佈建的地區。如要佈建新的區域，請按一下「啟用區域」。詳情請參閱「啟用新區域」一文。
3. 選取要用於整合的服務帳戶。您隨時可以透過整合工具列的「整合摘要」窗格，變更或更新整合作業的服務帳戶詳細資料。
  注意：只有在您為所選區域啟用整合管理功能時，系統才會顯示服務帳戶選項。
4. 按一下「建立」，新建立的整合服務會在整合服務編輯器中開啟。
在整合編輯器的導覽列中，按一下「Tasks」，即可查看可用任務和連接器清單。

顯示連接器工作的圖片

如要設定新連線，請在整合服務編輯器中點按並放置「Connectors」元素。接著按一下「設定連接器」，設定連線。
如果您已建立連線，請按一下「連接器」分頁標籤，查看最近建立的連線。您也可以在「搜尋」欄位中輸入名稱，搜尋連接器、連線或工作。
在整合服務編輯器中，按一下並放置已設定的「Connectors」元素。如要進一步瞭解如何設定連接器工作，請參閱「設定連接器工作」。

設定連接器工作

如要設定「連接器」工作，請按照下列步驟操作：

按一下設計工具中的「Connectors」任務元素，即可查看「Connectors」任務設定窗格。
您可以按一下重新命名工作名稱。
按一下「設定連接器」。
您可以選取該區域中的現有連線，或建立新的連線。如要設定現有連線，請在「Connector Tasks Editor」頁面中完成下列步驟。
下圖為「連接器任務編輯器」頁面的範例版面配置。

在「選取連線」部分中，選取連線的地區。
從所選區域的可用連線清單中，選擇現有的連線。
點選「下一步」。
在「Type」清單中，選取「實體」或「動作」。
- 如果您選取「實體」，連線的支援實體清單會顯示在「設定實體/動作」部分。選取實體，接著選取要對該實體執行的操作。
- 如果選取「動作」，系統會在「設定實體/動作」欄中顯示連線支援的動作清單。選取連線的動作。
注意：並非所有連結類型都支援實體或動作。如果某個連線類型不支援任何動作或實體，則對應的「實體」和「動作」清單會為空白。如要進一步瞭解實體和動作，請參閱「實體、作業和動作」。
按一下「完成」，完成連線設定並關閉窗格。

設定工作輸入和輸出變數

「連接器」工作設定窗格會顯示「工作輸入」和「工作輸出」變數，這些變數會根據在「設定連接器工作」對話方塊中選取的「實體和作業」或「動作」自動產生。這些變數可設定，並可做為目前工作輸入內容、後續工作輸出內容，或目前整合項目中的條件。

如要設定「Task Input」或「Task Output」變數，請按一下相應變數，開啟「Configure Variable」窗格，然後執行下列步驟：

在「Default Value」欄位中輸入變數值。
(選用) 選取「Use as an input to integration」(做為整合輸入內容使用) 或「Use as an output to integration」(做為整合輸出內容使用)。
按一下 [儲存]。

如要進一步瞭解 Connector 工作中的輸入和輸出參數，請參閱「實體作業」。

設定驗證覆寫值

如要讓連線在執行期間動態接受不同的後端驗證，請確認您已在「整合連接器」中為連線選取「啟用驗證覆寫」選項。

如要設定驗證覆寫值，請按照下列步驟操作：

按一下設計工具中的連接器任務元素，即可查看「Connectors」任務設定窗格。
展開「工作輸入」部分。「End user credentials」欄位已設為 dynamicAuthConfig 變數。

接著，請按照下列步驟操作：
1. 按一下 dynamicAuthConfig 變數。系統隨即會顯示「Edit variable」窗格。
  如要覆寫驗證機制，您必須在測試整合時提供驗證值。
  
  請按照以下步驟操作：
  1. 在「變數類型」清單中選取「整合輸入」。
  2. 在 JSON 結構定義選項中，您可以驗證為連線設定的驗證類型。測試整合時，請使用這個結構定義覆寫驗證值。
或者，您也可以在「連接器」工作設定窗格中，於「工作輸入」部分選取「使用 HTTPS 標頭進行驗證設定」核取方塊，將驗證資訊以 HTTP 標頭的形式傳遞。

實體作業和動作

您可以對連接器的實體執行 CRUD (建立、讀取、更新、刪除) 作業。每個實體作業都有一組不同的輸入和輸出參數。下表列出各種實體作業的輸入和輸出參數。

作業名稱	輸入參數	輸出參數
清單	listEntitiesPageSize listEntitiesPageToken listEntitiesSortByColumns filterClause	connectorOutputPayload listEntitiesNextPageToken
取得	entityId	connectorOutputPayload
取得	注意：您只能使用 Get 作業，從具有主鍵的資料表擷取單一記錄。或者，您也可以使用 List 作業搭配 filterClause。
建立	connectorInputPayload	connectorOutputPayload
更新	connectorInputPayload entityId filterClause	connectorOutputPayload
刪除	entityId filterClause	不適用

輸入參數

下表說明各種實體作業的輸入參數。

參數名稱	資料類型	說明
entityId	字串	要存取的資料列專屬 ID。通常，`entityId` 是資料表或資料集的主鍵值。如果您為 `entityId` 指定值，但資料表或資料集沒有主鍵欄，整合作業就會回報執行階段錯誤，且 Connectors 任務會失敗。舉例來說，如要從 MySQL 資料表中取得特定資料列，`entityId` 就是資料表中的主鍵值。注意：`entityId` 並非 BigQuery 的必要項目。如果 BigQuery 資料表沒有主鍵，這個欄位就會留空。
connectorInputPayload	JSON	實體中要新增或更新的實際資料。以下範例顯示要新增至資料表的資料列 JSON 程式碼片段： { "employee_first_name": "John", "employee_emailID": "test-05@test.com" } 在這個範例中，`employee_first_name` 和 `employee_emailID` 是資料欄名稱，對應的值分別為 `John` 和 `test-05@test.com`。
filterClause	字串	根據條件限制運算結果。如要進一步瞭解如何新增篩選器子句，請參閱「為作業新增篩選器」。
listEntitiesPageSize	整數	指定應在頁面中傳回的結果數量。頁面是結果集內記錄的邏輯分組。如果您預期結果集中會有大量記錄，頁面這個概念就很實用。如果結果集很大，Connectors 任務可能會失敗，因為 Connectors 任務可處理的資料大小有限制。您可以將結果集拆分為較小的部分，避免發生這個問題。舉例來說，如果您預期結果集會包含 1000 筆記錄，可以將 `listEntitiesPageSize` 設為 100。因此，當 Connectors 工作首次執行時，會傳回前 100 筆記錄，第二次執行時則會傳回接下來的 100 筆記錄，依此類推。重要事項：預設的頁面大小為 25，工作最多可支援 50000 個頁面。除非您的資料表或資料集有主鍵，否則必須設定 `listEntitiesSortByColumns` 參數才能使用 `listEntitiesPageToken`。請使用 `listEntitiesPageSize` 參數搭配 `listEntitiesPageToken` 參數，瀏覽各個頁面。
listEntitiesPageToken	字串	可讓您存取特定網頁的網頁 ID (權杖)。您可以從 `listEntitiesNextPageToken` 輸出參數取得網頁憑證的值。由於每個網頁都有專屬的符記，您可以靈活地存取結果集合中的任何網頁。如要瞭解這個參數的用法，請一併參閱 `listEntitiesNextPageToken` 輸出參數的說明。
listEntitiesSortByColumns	字串陣列	您要依據哪個資料欄排序結果集。注意：您只能依據單一資料欄排序結果集。

輸出參數

下表說明各種實體作業的輸出參數。

參數名稱資料類型說明

connectorOutputPayload JSON 以 JSON 格式輸出的作業結果。

listEntitiesNextPageToken

字串

參數名稱	資料類型	說明
connectorOutputPayload	JSON	以 JSON 格式輸出的作業結果。
listEntitiesNextPageToken	字串	系統為網頁產生的 ID。您可以將符記視為指標，藉此存取結果集的特定頁面。如果您已透過設定 `listEntitiesPageSize` 參數將結果集分割成多個網頁，就需要透過某種機制瀏覽各個網頁。`listEntitiesNextPageToken` 輸出參數正好可用於這類情況。每次執行 Connectors 工作時，系統都會為下一頁產生權杖，並將 `listEntitiesNextPageToken` 的值設為新產生的權杖。接著，您可以使用這個符記存取結果集的下一頁。如要存取下一頁，您必須將 `listEntitiesPageToken` 輸入參數設為下一頁的符記值。舉例來說，假設您將 `listEntitiesPageSize` 參數設為 2，當 Connectors 工作首次執行時，`listEntitiesNextPageToken` 會設為 `ChoKC2VtcGxveWVlX2lkEgkRAAAAAAAA8D8YDw==` 符記值。接著，您可以將 `listEntitiesPageToken` 輸入參數設為此符記值，在後續執行 Connectors 工作時擷取下一頁。如果結果集包含大量網頁，建議您使用 While 迴圈工作，取得下一頁，並使用資料對應工作，在每次執行後自動將網頁符記值指派給 `listEntitiesPageToken` 輸入參數。將上一個迴圈迭代的 `listEntitiesNextPageToken` 對應至目前迴圈迭代的 Connectors 工作 `LIST Operation` 中的 `listEntitiesPageToken`。當 `listEntitiesNextPageToken` 為 `NULL` 時，while 迴圈工作就會結束，表示沒有更多頁面。

系統為網頁產生的 ID。您可以將符記視為指標，藉此存取結果集的特定頁面。

如果您已透過設定 listEntitiesPageSize 參數將結果集分割成多個網頁，就需要透過某種機制瀏覽各個網頁。listEntitiesNextPageToken 輸出參數正好可用於這類情況。每次執行 Connectors 工作時，系統都會為下一頁產生權杖，並將 listEntitiesNextPageToken 的值設為新產生的權杖。接著，您可以使用這個符記存取結果集的下一頁。如要存取下一頁，您必須將 listEntitiesPageToken 輸入參數設為下一頁的符記值。

舉例來說，假設您將 listEntitiesPageSize 參數設為 2，當 Connectors 工作首次執行時，listEntitiesNextPageToken 會設為 ChoKC2VtcGxveWVlX2lkEgkRAAAAAAAA8D8YDw== 符記值。接著，您可以將 listEntitiesPageToken 輸入參數設為此符記值，在後續執行 Connectors 工作時擷取下一頁。

如果結果集包含大量網頁，建議您使用 While 迴圈工作，取得下一頁，並使用資料對應工作，在每次執行後自動將網頁符記值指派給 listEntitiesPageToken 輸入參數。將上一個迴圈迭代的 listEntitiesNextPageToken 對應至目前迴圈迭代的 Connectors 工作 LIST Operation 中的 listEntitiesPageToken。當 listEntitiesNextPageToken 為 NULL 時，while 迴圈工作就會結束，表示沒有更多頁面。

實體作業的篩選子句

您可以使用可做為工作輸入的篩選子句變數，限制連接器工作處理的記錄。舉例來說，如果是刪除作業，您可以新增篩選器子句，刪除具有特定 orderId 的記錄。

篩選器子句只能套用至下列實體作業：

清單
刪除
更新

選取任一操作後，「Connectors」工作中的「Task Input」部分會自動顯示「Filter clause」欄位。

新增篩選器子句

如要新增篩選器子句，請執行下列步驟：

按一下設計工具中的「Connectors」任務元素，即可查看「Connectors」任務設定窗格。
展開「Task Input」部分，然後按一下「filterClause(Connectors)」字串變數。
系統隨即會顯示「Configure Variable」對話方塊。
在「預設值」欄位中輸入篩選器子句 (遵循子句語法)。
按一下 [儲存]。

篩選子句語法和範例

篩選器子句的格式如下：

FIELD_NAME CONDITION FILTER_VALUE

範例

```
OwnerId = '0053t000007941XAAQ'
```
```
PoNumber < 2345
```

OrderNumber = 00110 AND StatusCode = 'Draft'

```
TotalAmount > 2500
```

ShippingPostalCode = 94043 OR ShippingPostalCode = 77002

在篩選條件子句中使用變數

您無法在篩選器子句中直接使用整合變數。如果您想使用整合變數，請先設定資料對應工作，在整合變數和篩選子句之間建立對應關係。

下表顯示整合變數與 filterClause(Connectors) 變數之間的對應範例：

輸入	輸出
`PRIMARY_KEY_ID = ' .CONCAT(INTEGRATION_VARIABLE) .CONCAT(')`	`filterClause(Connectors)`

其中，PRIMARY_KEY_ID = ' 是輸入列中的「值」。

動作：執行自訂 SQL 查詢

如要建立自訂查詢，請按照下列步驟操作：

按照詳細操作說明新增連接器工作。
設定連接器工作時，請在要執行的動作類型中選取「動作」。
在「Action」清單中，選取「Execute custom query」，然後按一下「Done」。
展開「Task input」部分，然後執行下列操作：
1. 在「Timeout after」欄位中，輸入要等待多久時間才執行查詢。
  預設值：180 秒。
2. 在「資料列數量上限」欄位中，輸入要從資料庫傳回的資料列數量上限。
  預設值：25。
3. 如要更新自訂查詢，請按一下「編輯自訂指令碼」。系統會開啟「Script editor」對話方塊。
4. 在「Script editor」對話方塊中輸入 SQL 查詢，然後按一下「Save」。
  您可以在 SQL 陳述式中使用問號 (?) 代表單一參數，該參數必須在查詢參數清單中指定。舉例來說，下列 SQL 查詢會選取 Employees 資料表中與 LastName 資料欄指定值相符的所有資料列：
```
SELECT * FROM Employees where LastName=?
```
  注意：系統支援資料操縱語言 (DML) 和資料定義語言 (DDL) 陳述式。
5. 如果您在 SQL 查詢中使用了問號，請按一下每個問號旁的「+ 新增參數名稱」，新增參數。執行整合作業時，這些參數會依序取代 SQL 查詢中的問號 (?)。舉例來說，如果您新增了三個問號 (?)，就必須依序新增三個參數。
  
  如要新增查詢參數，請按照下列步驟操作：
  1. 在「類型」清單中選取參數的資料類型。
  2. 在「Value」欄位中輸入參數的值。
  3. 如要新增多個參數，請按一下「+ 新增查詢參數」。

結構定義重新整理

所有實體和動作都會與相關聯的結構定義建立關聯。舉例來說，動作結構定義會包含參數詳細資料，例如參數名稱和對應的資料類型。在執行階段，連線會從後端擷取實體和動作的結構定義 (中繼資料)。如果結構定義有任何更新，這些更新不會自動反映在現有連線中，您必須手動重新整理結構定義。如要在現有的連接器工作中查看更新後的結構定義，請按照下列步驟操作：

在 Integration Connectors 中，開啟連線的「Connection details」頁面，然後按一下「Refresh connection schema」。
在應用程式整合中，您必須針對相同的連線重新設定現有的連接器工作。

內嵌連結建立

您可以使用連接器任務，直接在 Integration Connectors 中建立新連線。

事前準備

新增連接器任務

建立新的連線

如要透過應用程式整合建立新連線，請執行下列步驟：

按一下設計工具中的「Connectors」任務元素，即可查看「Connectors」任務設定窗格。
按一下「設定連接器」。
畫面隨即會顯示「Connectors Task Editor」(連接器工作編輯器) 頁面。
略過「區域」欄位。
按一下「連線」，然後在下拉式選單中選取「建立連線」選項。
在「建立連線」窗格中完成下列步驟：
注意：以下是建立連線的一般步驟。雖然所有連線類型的大部分步驟都相同，但與驗證相關的部分額外步驟或詳細資料可能會有所不同。
建議您也查看 Integration Connectors 中的相關連接類型說明文件。
1. 在「位置」步驟中，選擇連線的位置。
  1. 點選「區域」，然後從下拉式清單中選取地點。
  2. 點選「下一步」。
2. 在「連線詳細資料」步驟中，提供連線的詳細資料：
  1. 連接器：從下拉式清單中選取要建立的連接器類型。如要查看支援的連接器清單，請參閱「所有 Integration Connectors」。
  2. 連接器版本：從下拉式清單中選擇所選連接器類型的可用版本。
  3. 連線名稱：輸入連線執行個體的名稱。
    注意：連線名稱必須符合下列條件：
    - 連線名稱可以包含英文字母、數字或連字號。
    - 字母必須為小寫。
    - 連線名稱的開頭必須是英文字母，結尾則須為英文字母或數字。
    - 連線名稱長度不得超過 63 個半形字元。
  4. (選用) 輸入連線例項的說明。
  5. (選用) 勾選「Enable Cloud Logging」，即可儲存連線例項的記錄資料。
  6. 服務帳戶：選取具備必要角色的服務帳戶。
  7. (選用) 按一下「進階設定」，設定連線節點設定。
    詳情請參閱「Integration Connectors」中的相關連結說明文件。
  8. (選用) 按一下「+ 新增標籤」，以鍵/值組合的形式為連線新增標籤。
  9. 點選「下一步」。
3. 在「驗證」步驟中，提供連線的驗證詳細資料。
  1. 在此步驟中填入的驗證方法，取決於要建立的連線類型。
    不同的連線類型會使用不同的驗證方法。詳情請參閱整合連接器中各連結說明文件的「設定驗證」一節。
  2. 點選「下一步」。
4. 查看：查看連線和驗證詳細資料。
5. 按一下 [建立]。

最佳做法

如要瞭解適用於 Connectors 工作項的用量限制，請參閱「用量限制」一文。
如要進一步瞭解如何排解失敗的 Connectors 工作，請參閱「使用記錄檔排解及追蹤連接器失敗問題」。

錯誤處理策略

工作錯誤處理策略會指定在工作因暫時性錯誤而失敗時，應採取的動作。如要瞭解如何使用錯誤處理策略，以及不同類型的錯誤處理策略，請參閱「錯誤處理策略」。

定價

您不需要建立連接器，即可使用 Cloud Pub/Sub 觸發條件和 Salesforce 觸發條件。不過，如果您使用連接器任務連結 Pub/Sub 或 Salesforce，系統會依連接器使用量向您收費。如需定價資訊，請參閱「Application Integration 定價」。

配額與限制

如要進一步瞭解配額和限制，請參閱「配額與限制」。

後續步驟

瞭解所有工作和觸發條件。
瞭解如何測試及發布整合。

瞭解錯誤處理。
瞭解整合執行記錄。