查看 Application Integration 支援的連接器。

Apps Script 工作

Apps Script 工作可讓您從整合作業執行 Google Apps Script。Google Apps Script 可讓您快速開發應用程式，輕鬆建立業務應用程式。詳情請參閱「Google Apps Script」。如要在整合中執行自訂指令碼或重複使用現有指令碼，這項工作就很實用。

事前準備

使用 Apps Script 工作前，請務必完成下列步驟：

啟用 AppsScript API

您必須在 Google Cloud 專案和 AppsScript 使用者帳戶中啟用 AppsScript API，才能使用此工作。如要瞭解如何在 Google Cloud 專案中啟用 AppsScript API，請參閱「在標準 Google Cloud 專案中啟用 API」。如要在使用者帳戶中啟用 API，請按一下「設定」，然後將 Google Apps Script API 設為 On。

建立 OAuth 2.0 用戶端 ID

如果您有 OAuth 2.0 用戶端 ID，可以略過這個步驟，並繼續進行「 設定驗證設定檔」。

如要瞭解如何建立新的 OAuth 用戶端 ID，請參閱「建立 OAuth 用戶端 ID」。

設定驗證設定檔

Application Integration 會使用驗證設定檔連線至 Google Cloud，以便部署及執行 Apps Script 專案。如要設定驗證設定檔，請執行下列步驟：

新增 Apps Script 工作

  1. 前往 Google Cloud 控制台的「Application Integration」頁面。

    前往「應用程式整合」

  2. 在導覽選單中，按一下「整合」。

    系統隨即會顯示「Integrations」頁面，列出 Google Cloud 專案中可用的所有整合項目。

  3. 選取現有的整合，或按一下「建立整合」來建立新的整合。

    如果您要建立新的整合功能：

    1. 在「Create Integration」窗格中輸入名稱和說明。
    2. 選取整合作業的區域。
    3. 選取要用於整合的服務帳戶。您隨時可以透過整合工具列的 「整合摘要」窗格，變更或更新整合作業的服務帳戶詳細資料。
    4. 按一下「建立」，新建立的整合服務會在整合服務編輯器中開啟。

  4. 在整合編輯器的導覽列中，按一下「Tasks」，即可查看可用任務和連接器的清單。
  5. 在整合服務編輯器中點按並放置 Apps Script 元素。

建立驗證設定檔

  1. 按一下設計工具中的 Apps Script 元素，即可查看 Apps Script 任務設定窗格。
  2. 在 Apps Script 工作的工作設定窗格中，按一下「+ 新增驗證設定檔」。
  3. 在「Authentication profile」對話方塊中，輸入設定檔的名稱和說明，並設定下列屬性：
    • 驗證類型：選取「OAuth 2.0 授權碼」
    • 驗證端點：輸入 https://accounts.google.com/o/oauth2/auth
    • 權杖端點：輸入 https://oauth2.googleapis.com/token
    • 用戶端 ID：輸入用戶端 ID。

      您可以在 Google Cloud 專案資訊主頁的「憑證」>「OAuth 2.0 用戶端 ID」下方，找到用戶端 ID。

    • 密鑰：輸入用戶端密鑰

      您可以在 Google Cloud 專案資訊主頁的「憑證」>「OAuth 2.0 用戶端 ID」下方，找到用戶端密碼。

    • 範圍：輸入下列內容：

      https://www.googleapis.com/auth/script.projects https://www.googleapis.com/auth/script.deployments https://www.googleapis.com/auth/script.deployments.readonly https://www.googleapis.com/auth/drive.scripts https://www.googleapis.com/auth/drive https://www.googleapis.com/auth/script.external_request https://www.googleapis.com/auth/userinfo.email

      注意：多個範圍之間可以使用半形空格字元 (" ") 分隔。

  4. 按一下「Generate Access Token and Save」。

    系統會將您重新導向至授權畫面。登入並同意畫面上列出的權限，以產生存取權杖。如果存取權杖產生作業成功，系統會儲存驗證設定檔，您就可以繼續編輯整合作業。

設定 Apps Script 工作

如要在 Apps Script 工作中設定 Apps Script 專案，請執行下列步驟：

  1. 在任務設定窗格中，按一下「Configure Apps Script Project」。

    系統隨即會顯示「Apps Script Configuration」對話方塊。

  2. 您可以選擇連結至現有的 Apps Script 專案，或建立新的 Apps Script 專案。

    設定 Apps Script 專案後，系統會將 Apps Script 專案與應用程式整合作業建立關聯。

  3. 按一下「儲存」。
  4. 按一下「Open Apps Script Project」。

    您可以在 Apps Script 編輯器中查看下列檔案：

    • Run.gs：包含可執行的程式碼。在 run 函式中編寫指令碼。這個函式會在 Apps Script 工作執行時呼叫。您可以在指令碼中使用在整合層級定義的變數。如要瞭解如何使用整合變數，請參閱「使用整合變數」。
    • Main.gs：包含用於從整合項目執行 Apps Script 的初始化程式碼。請勿編輯或修改這個檔案。
    • Test.gs：包含可執行的測試執行程式碼。您可以在 testRun 函式中編寫腳本，以便測試腳本。

    請務必以 網頁應用程式格式部署專案。如要進一步瞭解各種部署模式，請參閱「 建立及管理部署作業」。

存取整合變數

Apps Script 工作會使用 AppsScriptTask 程式庫，讓您在指令碼中使用整合變數。系統會自動匯入 AppsScriptTask 程式庫，並可在 run 函式中使用。

如要在 Apps Script 中存取整合變數，您必須以工作參數的形式將變數傳遞至 Apps Script 工作。工作參數是鍵/值組合，其中「Key」是 AppsScript 工作中的變數名稱，而「Value」是對應的整合變數名稱。您可以在工作設定窗格的「工作參數」部分新增一或多個工作參數。

舉例來說，假設您有一個名為「Product」的整合變數，且想在 Apps Script 中使用，可以將「Key」定義為「ProductKey」，並將值定義為「Product」。接著，您可以在 Apps Script 中使用 AppsScriptTask.getTaskParameter('ProductKey') 讀取「Product」變數。

AppsScriptTask 程式庫提供下列方法，可存取整合變數：

函式名稱 說明 用法

setIntegrationVariable

 將提供的值設為變數。

語法： setIntegrationVariable(value,value)

示例： 

// Write to an Integer variable
AppsScriptTask.setIntegrationVariable('EmployeeIDKey','456');

getTaskParameter

 取得變數的值。

語法： getTaskParameter(value)

示例： 

// Read an integration variable
AppsScriptTask.getTaskParameter('EmployeeIDKey');

如要查看 AppsScriptTask 程式庫中提供的所有函式，請將滑鼠游標懸停在 Apps Script 編輯器中的 AppsScriptTask 選單項目上，然後按一下「更多」 >「在新的分頁中開啟」。

測試 Apps Script

在發布整合功能前，您可以使用 Test.gs 檔案中的 testRun 函式測試指令碼。使用 AppsScriptTaskTest 程式庫，在 testRun 函式中編寫測試程式碼。這個程式庫可讓您執行以斷言為基礎的測試案例，並自動匯入 testRun 函式中使用。

如要查看 AppsScriptTaskTest 程式庫中提供的所有函式，請將滑鼠游標懸停在 Apps Script 編輯器中的 AppsScriptTaskTest 選單項目上，然後按一下「更多」 >「在新分頁中開啟」。

以下範例說明如何使用 AppsScriptTaskTest 程式庫函式。

function testRun(){

  // Create a new request
  let req = AppsScriptTaskTest.createNewTestRequest('myCustomTest');

  // Add a task parameter that references an integration variable with the value 5
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, 'input', '$input$', 5);

  // Add a task parameter that references an integration variable
  AppsScriptTaskTest.createReference(req, 'output', '$output$');

  // Run the task(assuming the task increments the input by 1) and get the response
  let res = AppsScriptTaskTest.runTest(req, executeScript);

  // Check the response for the expected integration variable and its corresponding values
  AppsScriptTaskTest.containsIntegrationVariable(res, 'output', true);
  AppsScriptTaskTest.containsIntegrationVariable(res, 'someOtherIntegrtionVariable', false);
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, 'output', 6);
}

以下範例說明如何在 testRun 方法中存取 JSON 和陣列變數：

function testRun(){

  // Create a new request
  let req = AppsScriptTaskTest.createNewTestRequest('json-test');

  // Add a task parameter that references a JSON integration variable
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, "emp", "employee", {name:"snape", age:35});

  // Add a task parameter that references an array integration variable
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, "arr", "array", ["A", "B", "C"]);


  // Run the task and get the response
  // Assume that the run method increases the age of the employee by 5 and appends a new element in the array
  let res = AppsScriptTaskTest.runTest(req, executeScript);

  // Check the response for the expected integration variable and its corresponding values
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, "employee", {name:"snape", age:40});
  AppsScriptTaskTest.containsIntegrationVariable(res, "array", true);
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, "array", ["A", "B", "C", "D"]);
}

執行測試案例後，您可以在執行記錄中查看斷言。如要查看記錄檔，請在選單中按一下「執行記錄」。

最佳做法

如果您希望整合作業的延遲時間低於 1 到 2 秒，我們不建議使用 Apps Script 工作。

此外，我們建議您在單一 Apps Script 工作中編寫所有邏輯，而非連結多個 Apps Script 工作，以盡量減少效能瓶頸。

如要瞭解適用於 Apps Script 工作階段的用量限制，請參閱「 用量限制」。

注意事項

在整合設計中加入 Apps Script 工作時，請考量下列系統限制：

  • Apps Script 的有效部署作業上限：50 個
  • API 可執行檔的每秒查詢次數 (QPS)：5000/分鐘
  • webapp 部署作業的每秒查詢次數 (QPS)：5000/分鐘
  • API 執行檔的延遲時間：1.5 秒
  • Webapp 的延遲時間：2.5 秒
  • AppsScript 中所有整合變數的累積大小上限：15 MB

錯誤處理策略

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

「服務水準協議」排除條款

Apps Script 工作會依附 Google Apps Script 產品。由於此依附元件是應用程式整合功能的外部元件，因此如果 Apps Script 工作失敗，導致 active 整合功能的所有執行作業失敗，則會從應用程式整合功能服務水準協議 (SLA) 的條款及細則中排除。

配額與限制

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

後續步驟