连接器任务

连接器任务可让您使用 Integration Connectors 中提供的开箱即用连接器快速安全地连接到集成中的 Google Cloud 服务和其他业务应用。

如需查看 Apigee Integration 的所有受支持的连接器列表，请参阅连接器参考文档。

须知事项

添加连接器任务

如需在集成中添加连接器任务，请执行以下操作：

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

    要创建新的集成，请执行以下操作：

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

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

  4. 在集成设计器导航栏中，点击 + 添加任务/触发器 > 任务以查看可用任务列表。
  5. 点击连接器元素，并将其放置到集成编辑器中。

配置连接器任务

如需配置连接器任务，请执行以下操作：

  1. 点击设计器上的连接器任务元素，以查看连接器任务配置窗格。

    （可选）点击 以重命名任务。

  2. 点击配置连接器。
  3. 您可以选择该区域中的现有连接，也可以创建新的连接。如需配置现有连接，请在连接器任务编辑器页面中完成以下步骤：
    1. 在选择连接器字段中，选择连接所在的区域。
    2. 从所选区域的可用连接列表中选择一个现有连接。
    3. 点击下一步。
    4. 从类型列表中，选择实体或操作。
      • 如果您选择实体，则设置实体/操作部分会显示连接的受支持实体列表。选择一个实体，后跟要对该实体执行的操作。
      • 如果您选择操作，则设置实体/操作列中将显示连接支持的操作列表。为连接选择操作。
        • 支持的实体和操作取决于连接器类型。如需查看 Apigee Integration 的所有受支持的连接器列表，请参阅连接器参考文档。 如需查看某个连接器支持的操作和实体，请参阅具体的连接器文档。

        如果连接器支持自定义 SQL 查询，您可以从操作列表中选择执行自定义查询选项。例如，如需了解如何为 BigQuery 连接器添加自定义 SQL 查询，请参阅执行自定义 SQL 查询。

        如需详细了解实体和操作，请参阅实体、操作和动作。

    5. 点击完成以完成连接配置并关闭窗格。

      6. 下图展示了连接器任务编辑器页面的示例布局。 显示“配置连接器任务”对话框的图片 显示“配置连接器任务”对话框的图片

配置任务输入和输出变量

连接器任务配置窗格会显示根据配置连接器任务对话框中选择的“实体和操作”或“操作”自动生成的任务输入和任务输出变量。这些变量可配置，并且可作为当前任务的输入或作为当前集成中的后续任务或条件的输出进行访问。

如需配置任务输入或任务输出变量，请点击相应变量以打开配置变量窗格并执行以下步骤：

  1. 在默认值字段中输入变量值。
  2. （可选）选择用作集成的输入或用作集成的输出。
  3. 点击保存。

如需详细了解连接器任务的输入和输出参数，请参阅实体操作。

实体操作

您可以对连接器的实体执行 CRUD（创建、读取、更新、删除）操作。其中每个实体操作都有一组不同的输入和输出参数。下表列出了各种实体操作的输入和输出参数。

操作名称 输入参数 输出参数
List
  • listEntitiesPageSize
  • listEntitiesPageToken
  • listEntitiesSortByColumns
  • filterClause
  • connectorOutputPayload
  • listEntitiesNextPageToken
Get entityId connectorOutputPayload
创建 connectorInputPayload connectorOutputPayload
Update
  • connectorInputPayload
  • entityId
  • filterClause
 connectorOutputPayload
删除
  • entityId
  • filterClause
 不适用

输入参数

下表介绍了各种实体操作的输入参数。

参数名称 数据类型 说明
entityId 字符串

您要访问的行的唯一标识符。

通常，entityId 是表或数据集的主键值。如果您为 entityId 指定了值，并且表或数据集没有主键列，则集成会报告运行时错误，并且连接器任务会失败。

例如，如需从 MySQL 表中获取特定行，entityId 需要是表中的主键值。
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 整数

指定页面中应返回的结果数。

页面是结果集中记录的逻辑分组。如果您希望结果集中包含大量记录，则页面的概念非常有用。如果结果集很大，则连接器任务可能会失败，因为连接器任务可以处理的数据大小存在限制。您可以通过将结果集细分为较小的数据块来避免此问题。

例如，如果您希望结果集中有 1000 条记录，则可以将 listEntitiesPageSize 设置为 100。因此，连接器任务首次运行时，会返回前 100 条记录，第二次运行时返回下 100 条记录，依此类推。
listEntitiesPageToken 字符串

用于访问特定页面的页面标识符（令牌）。

您可以从 listEntitiesNextPageToken 输出参数中获取页面令牌的值。由于每个页面都有唯一的令牌，因此您可以灵活地访问结果集中您需要的任何页面。如需了解此参数的用法，另请参阅 listEntitiesNextPageToken 输出参数的说明。
listEntitiesSortByColumns 字符串数组 作为结果集排序依据的列名称。

输出参数

下表介绍了各种实体操作的输出参数。

参数名称 数据类型 说明
connectorOutputPayload JSON 操作的输出（采用 JSON 格式）。
listEntitiesNextPageToken 字符串

系统为页面生成的标识符。您可以将令牌视为可通过其访问结果集特定页面的指针。

如果您已通过设置 listEntitiesPageSize 参数将结果集拆分为多个页面，则您需要一种机制来浏览各个页面。借助 listEntitiesNextPageToken 输出参数，您便可以实现这一目的。连接器任务每次运行时，系统都会为下一页生成令牌，并将 listEntitiesNextPageToken 的值设置为新生成的令牌。之后，您便可以使用该令牌访问结果集中的下一页。若要访问下一页，您必须将 listEntitiesPageToken 输入参数设置为下一页的令牌值。

例如，假设您将 listEntitiesPageSize 参数设置为 2，之后连接器任务首次运行时，listEntitiesNextPageToken 便会设置为 ChoKC2VtcGxveWVlX2lkEgkRAAAAAAAA8D8YDw== 令牌值。然后，您可以将 listEntitiesPageToken 输入参数设置为此令牌值，以在后续运行连接器任务时获取下一页。

如果结果集包含大量页面，您可以考虑使用针对每一个循环任务重复调用连接器任务，并使用数据映射任务在每次运行后自动为 listEntitiesPageToken 输入参数分配令牌值。

实体操作的过滤条件子句

您可以使用可用作任务输入的过滤条件子句变量来限制连接器任务处理的记录。例如，对于删除操作，您可以添加过滤条件子句以删除具有特定 orderId 的记录。

过滤条件子句只能应用于以下实体操作：

  • 列表
  • 删除
  • 更新

选择上述任何操作时，连接器任务的任务输入部分都会自动显示 Filter clause（过滤条件子句）字段。

添加过滤条件子句

如需添加过滤条件子句，请执行以下步骤：

  1. 点击设计器上的连接器任务元素，以查看连接器任务配置窗格。
  2. 展开任务输入部分，然后点击 filterClause(Connectors) 字符串变量。

    随即会出现配置变量对话框。

  3. 在默认值字段中输入过滤条件子句（在子句语法后面）。
  4. 点击保存。

过滤条件子句语法和示例

过滤条件子句采用以下格式：

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 = ' 输入为输入行中的 Value。

内嵌连接创建

您可以使用连接器任务直接在 Integration Connectors 中创建新连接。

须知事项

新建连接

如需从 Apigee Integration 创建新连接，请执行以下步骤：

  1. 点击设计器上的连接器任务元素，以查看连接器任务配置窗格。
  2. 点击配置连接器。

    随即将显示连接器任务编辑器页面。

  3. 跳过区域字段。
  4. 点击连接，然后从下拉菜单中选择创建连接选项。
  5. 在创建连接窗格中完成以下步骤：
    1. 在位置步骤中，选择连接的位置。
      1. 点击区域，然后从下拉列表中选择一个位置。
      2. 点击下一步。
    2. 在连接详细信息步骤中，提供连接的详细信息：
      1. 连接器：从下拉列表中选择要创建的连接器类型。如需了解受支持的连接器列表，请参阅所有 Integration Connectors。
      2. 连接器版本：从下拉列表中选择所选连接器类型的可用版本。
      3. 连接名称：输入连接实例的名称。
      4. （可选）输入连接实例的说明。
      5. （可选）勾选启用 Cloud Logging 以存储连接实例的日志数据。
      6. 服务账号：选择具有所需角色的服务账号。
      7. （可选）点击高级设置以配置连接节点设置。

        如需了解详情，请参阅 Integration Connectors 中的相应连接文档。

      8. （可选）点击 + 添加标签，以键值对的形式向连接添加标签。
      9. 点击下一步。
    3. 在身份验证步骤中，提供连接的身份验证详细信息。
      1. 此步骤中填充的身份验证方法基于要创建的连接类型。

        不同的连接类型使用不同的身份验证方法。如需了解详情，请参阅 Integration Connectors 中相应连接文档的配置身份验证部分。

      2. 点击下一步。
    4. 查看：查看您的连接和身份验证详细信息。
    5. 点击创建。

最佳做法

错误处理策略

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