Apps 脚本任务

通过 Apps 脚本任务,您可以从集成运行 Google Apps 脚本。Google Apps 脚本是一个快速开发的应用开发平台,可以帮助您快速轻松地创建业务应用。如需了解详情,请参阅 Google Apps 脚本。如果您希望运行自定义脚本,或者要在集成中重复使用现有脚本,此任务会很有用。

准备工作

在使用 Apps 脚本任务之前,请确保完成以下步骤:

启用 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

设置身份验证配置文件

Apigee Integration 使用身份验证配置文件连接到 Google Cloud,以部署和运行 Apps 脚本项目。如需设置身份验证配置文件,请执行以下步骤:

添加 Apps 脚本任务

  1. Apigee 界面中,选择您的 Apigee 组织
  2. 点击开发 > 集成
  3. 选择现有集成,或通过点击创建集成来创建新集成。

    要创建新的集成,请执行以下操作:

    1. 创建 Integrations对话框中输入名称和说明。
    2. 从支持的区域列表中选择集成的区域
    3. 点击创建

    这将在集成设计器中打开集成。

  4. 集成设计器导航栏中,点击 + 添加任务/触发器 > 任务以查看可用任务列表。
  5. 点击 Apps 脚本元素并将其放入集成编辑器中。

创建身份验证配置文件

  1. 点击设计器上的 Apps 脚本元素查看 Apps 脚本任务配置窗格。
  2. 在 Apps 脚本任务的任务配置窗格中,点击 +新建身份验证配置文件
  3. 身份验证配置文件对话框中,为配置文件输入名称和描述,并设置以下属性:
    • 身份验证类型:选择 OAuth 2.0 授权代码
    • 身份验证端点:输入 https://accounts.google.com/o/oauth2/auth
    • 令牌端点:输入 https://oauth2.googleapis.com/token
    • 客户端 ID:输入客户端 ID。

      客户端 ID 位于 Google Cloud 项目信息中心的凭据 > OAuth 2.0 客户端 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. 点击生成访问令牌并保存

    您会被重定向到授权屏幕。登录并同意屏幕上所列权限以生成访问令牌。如果访问令牌生成成功,系统会保存您的身份验证配置文件,您可以继续修改集成。

配置 Apps 脚本任务

如需在 Apps 脚本任务中配置 Apps 脚本项目,请执行以下步骤:

  1. 在任务配置窗格中,点击配置 Apps 脚本项目

    系统会显示 Apps Script Configuration 对话框。

  2. 您可以选择关联到现有的 Apps 脚本项目,也可以新建 Apps 脚本项目。

    配置 Apps 脚本项目会将 Apps 脚本项目与 Apigee Integration 中的集成相关联。

  3. 点击保存。
  4. 点击打开 Apps 脚本项目

    在 Apps 脚本编辑器中,您可以看到以下文件:

    • Run.gs:包含可执行代码。在 run 函数中编写脚本。此函数在 Apps 脚本任务执行时调用。您可以在脚本中使用集成级别定义的变量。如需了解如何使用集成变量,请参阅使用集成变量
    • Main.gs:包含从集成中运行 Apps 脚本的初始化代码。请勿编辑或修改此文件。
    • Test.gs:包含测试运行的可执行代码。您可以在 testRun 函数中编写脚本,以测试脚本

    请务必以 Web 应用格式部署项目。如需详细了解各种部署模式,请参阅创建和管理部署

访问集成变量

Apps 脚本任务使用 AppsScriptTask 库,让您可以在脚本中使用集成变量。AppsScriptTask 库是自动导入的,可在 run 函数中使用。

如需访问 Apps 脚本中的集成变量,您必须以任务参数的形式将变量传递给 Apps 脚本任务。任务参数是键值对,其中 Key 是 AppsScript 任务中变量的名称,Value 是相应的集成变量名称。您可以在任务配置窗格的任务参数部分添加一个或多个任务参数。

例如,如果您要在 Apps 脚本中使用名称为 Product 的集成变量,则可以将定义为 ProductKey,将值定义为 Product。在 Apps 脚本中,您可以使用 AppsScriptTask.getTaskParameter('ProductKey') 读取 Product 变量。

AppsScriptTask 库提供访问 Integration 变量的以下方法:

函数名称 说明 用量

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 脚本编辑器中的 AppsScriptTask 菜单项上,然后点击“更多” > 在新标签页中打开

测试您的 Apps 脚本

在发布集成之前,您可以使用 Test.gs 文件中提供的 testRun 函数测试脚本。使用 AppsScriptTaskTest 库在 testRun 函数中编写您的测试代码。借助这个库,您可以运行基于断言的测试用例,并自动导入用于 testRun 函数。

如需查看 AppsScriptTaskTest 库中提供的所有函数,请将鼠标悬停在 Apps 脚本编辑器中的 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 脚本任务。

此外,建议将所有逻辑编码到单个 Apps 脚本任务中,而不是将多个 Apps 脚本任务链接,以尽可能减少性能瓶颈。

如需了解适用于 Apps 脚本任务的用量限额,请参阅用量限额

注意事项

在集成设计中添加“Apps 脚本”任务时,请考虑以下系统限制:

  • AppsScript 的活跃部署数上限:50
  • API 可执行文件的每秒查询数 (QPS):5000/分钟
  • Web 应用部署的每秒查询次数 (QPS):5000/分钟
  • API 可执行文件的延迟:1.5 秒
  • Webapp 的延迟时间:2.5 秒
  • AppsScript 中所有集成变量的累计大小上限:15 MB

错误处理策略

任务的错误处理策略指定当任务因暂时性错误而失败时要执行的操作。如需了解如何使用错误处理策略,以及了解不同类型的错误处理策略,请参阅错误处理策略