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

Apps Script 工作

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

事前準備

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

啟用 Apps Script API
建立 OAuth 2.0 用戶端 ID
設定驗證設定檔
請確認專案中 Google Cloud 的 Application Integration未設定 VPC Service Controls。
警告：如果為 Google Cloud 專案中的 Application Integration 設定 VPC Service Controls，Cloud Function 將無法運作或停止運作。

啟用 Apps Script API

如要使用這項工作，請在 Google Cloud 專案和 Apps Script 使用者帳戶中啟用 Apps Script API。如要瞭解如何在 Google Cloud 專案中啟用 Apps Script 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 工作

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

建立驗證設定檔

在設計工具中，按一下「Apps Script」元素，即可查看「Apps Script」任務設定窗格。
在 Apps Script 工作的任務設定窗格中，按一下「+ 新增驗證設定檔」。
在「Authentication profile」(驗證設定檔) 對話方塊中，輸入設定檔名稱和說明，並設定下列屬性：
- 驗證類型：選取「OAuth 2.0 授權碼」
- 驗證端點：輸入 https://accounts.google.com/o/oauth2/auth
- 權杖端點：輸入 https://oauth2.googleapis.com/token
- 「Client ID」(用戶端 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
  
  注意：多個範圍之間可以插入單一空格字元 (" ")。
按一下「Generate Access Token and Save」(產生並儲存存取權杖)。
系統會將您重新導向至授權畫面。登入並同意畫面列出的權限，即可產生存取權杖。如果存取權杖產生成功，系統會儲存驗證設定檔，您也可以繼續編輯整合項目。

設定 Apps Script 工作

如要在「Apps Script」工作設定 Apps Script 專案，請按照下列步驟操作：

在工作設定窗格中，按一下「設定 Apps Script 專案」。
系統隨即會顯示「Apps Script Configuration」(應用程式指令碼設定) 對話方塊。
您可以選擇連結至現有的 Apps Script 專案，或建立新的 Apps Script 專案。
設定 Apps Script 專案會將該專案與 Application Integration 中的整合項目建立關聯。
按一下「儲存」。
按一下「開啟 Apps Script 專案」。
在 Apps Script 編輯器中，您會看到下列檔案：
- Run.gs：包含可執行程式碼。在 run 函式中編寫指令碼。這個函式會在執行 Apps Script 工作時呼叫。您可以在指令碼中使用整合層級定義的變數。如要瞭解如何使用整合變數，請參閱「使用整合變數」。
- Main.gs：包含從整合服務執行 Apps Script 的初始化程式碼。請勿編輯或修改這個檔案。
- Test.gs：包含測試執行的可執行程式碼。您可以在 testRun 函式中編寫腳本，測試腳本。
請務必以網頁應用程式格式部署專案。如要進一步瞭解各種部署模式，請參閱「建立及管理部署作業」。

存取整合作業變數

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

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

舉例來說，如果您有名為「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');

`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/分鐘
網頁應用程式部署的每秒查詢次數 (QPS)：5000/分鐘
API 執行檔的延遲時間：1.5 秒
Webapp 的延遲時間：2.5 秒
Apps Script 中所有整合變數的累積大小上限：15 MB

錯誤處理策略

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

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

Apps Script 工作依附於 Google Apps Script 產品。由於這項依附元件位於 Application Integration 外部，因此凡是因 Apps Script 工作失敗而導致 active 整合執行失敗，均不適用於Application Integration 服務水準協議 (SLA) 條款及細則。

配額與限制

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

後續步驟

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

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