根据 API 定义构建连接器

新建连接器

1. 如果选择 从 API 定义开始，则必须提供 API 定义：

   • 从本地文件 – 上传 Postman 或 Swagger 集合。
   • 来自 URL – 输入文件 URL，例如https://petstore.swagger.io/v2/swagger.json 。
     
     

     

     
     
2. 单击“继续”。

配置连接器

1. 在“确认导入”窗口中，您可以执行以下操作：

   • 更改“提供程序名称”、“应用程序名称” 和“连接器名称”。

   • 修改要在自定义连接器中使用的资源。 系统将自动启用所有可用资源；禁用您想要排除的那些项目。

     • 使用“搜索”栏查找特定资源。

   • 单击“创建”。
     
     

     

     
     
2. 现在会显示“设置”窗口。

3. 在“信息”选项卡中，您可以配置以下字段：

   • 名称- 这会反映在您的连接器密钥中。
   • “API 类型”– 默认情况下此字段为禁用状态，因为当前仅支持 REST。
   • 类别- 您可以从可用类别中选择，例如人工智能或市场营销，也可以创建自己的类别。
   • “说明”– 输入连接器的说明。
   • 图标– 单击“浏览”以从您的计算机上传图像。 支持所有图像类型，但我们建议使用方形 SVG。
4. 目录预览显示自定义连接器在集成服务连接器目录中的显示方式。
5. 选择“保存”。

   
   

   

   
   

配置基本 API

在“基本 API ” 选项卡中，配置应用程序 API 的基本 URL 和分页：

• 基本 URL – 自动填充在创建连接器时声明的值。
• 分页类型– 下拉列表中的可用选项包括：以 1 开头的页、以 0 开头的页、偏移量、自定义、无。 如果供应商文档未提供有关分页的任何详细信息，请保留默认值。 有关详细信息，请参阅分页部分。
• 最大分页值 – 默认值为 100 。 如果供应商文档未提供有关分页的任何详细信息，请保留默认值。
• “Content-Type”标头– 默认情况下禁用此字段。 当前仅支持“ application/json ”。
• “接受”标头– 默认情况下禁用此字段。 当前仅支持“ application/json ”。
  
  

  

  
  

分页

分页允许供应商应用程序逐步返回响应的各部分，而不是一次返回全部，从而优化响应时间。

分页可以通过多种方式实施。 UiPath 连接器使用标准化的分页配置，确保所有连接器都以相同的方式工作。

您可以通过定义“ 分页类型 ”和“ 分页最大数量 ”字段，在 “设置”>“基本 API” 中在连接器级别配置分页设置。对于基于列表的活动，您可以在资源级别进一步配置分页。

分页类型

“分页类型” 字段提供多个选项，以符合各种提供程序规范：

• 以 1 开头的页

• 从 0 开始的页

• 偏移

• 光标

• 无

无论选定的分页类型如何，自定义连接器的活动都将在您的 Studio 环境中正常运行。 但是，为确保您收到完整的回复，请务必指定和配置正确的分页类型。

以 1 开头的页和以 0 开头的页

基于页面的分页类型依赖于传递给提供程序的查询参数，以指示应返回结果的哪一页以及每页的结果数量。

例如，GitHub 使用基于页面的分页，如使用 REST API 中的分页中所述。 他们在响应标头中包含了下一页 URL，以便于实施，但基本机制基于Page和Per_page查询参数。

在“连接器生成器”中，您可以选择以下选项之一:

• 以 1 开头的页面表示分页，其中结果第一页的索引为 1（例如，page=1），
• 以 0 开头的页是指分页，其中结果的第一页位于索引零处（例如，page=0）。

资源配置

默认情况下，基于页面的分页分配“页面”和“页面大小”作为分页参数。 您可以将这些覆盖为提供程序规范，如下所示：

1. 选择您的资源。
2. 选择“分页” 选项卡。
3. 启用分页并更新参数名称以匹配提供程序的参数。

光标分页

基于光标的分页依赖于从提供程序返回的页面令牌，而不是可以传递到后续调用以返回下一页结果的页数或偏移量。

在“连接器生成器”中向使用基于光标的分页的连接器发出请求时，系统不会自动对返回的结果进行分页。 因此，并非返回所有结果而未在后续调用中手动包括下一个光标。

与其他分页类型类似，基于光标的分页通常包含一个用于指定每页结果数的值。

资源配置

基于光标的分页为光标和页面大小（ nextPage和pageSize ）提供默认名称，您可以覆盖这些默认名称以匹配提供程序规范。

识别页面令牌路径

下一页光标通常嵌套在 API 响应字段中。 因此，请务必在响应架构中指定光标的位置，以便 Integration Service 可以提取页面令牌值并在后续响应中使用该值。

您可以在响应字段中指定位置，如下所示：

1. 确定其在响应中的位置（正文或标头）。

2. 标识字段路径，并使用句点分隔级别。

如果光标嵌套在 URL 中，则可以使用问号符号 ( ? ) 来表示要拉取的查询参数。

示例

Meta Graph API 提供了在“连接器生成器”中使用基于光标的分页的很好示例。 元分页文档会指定在每个请求中找到下一页令牌的位置，包括对令牌或完整 URL 的直接引用。 我们可以使用这些示例为元数据图形 API 构建资源分页。

1. 在所选资源上，更新nextPage令牌名称和pageSize名称以匹配提供程序 API。 根据 Meta Graph API 文档， 下一页 令牌名称为 After ，页面大小 为limit 。

2. 接下来，确定每个请求上的nextPage令牌可用的位置。 该文档为我们提供了此映射位置的 JSON：

   {
     "data": [
        ... Endpoint data is here
     ],
     "paging": {
       "cursors": {
         "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
         "before": "NDMyNzQyODI3OTQw"
       },
       "previous": "https://graph.facebook.com/{your-user-id}/albums?limit=25&before=NDMyNzQyODI3OTQw"
       "next": "https://graph.facebook.com/{your-user-id}/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
     }
   }

这是响应正文的一部分，因此您可以 通过 两种方式配置 nextPage 令牌：

1. 直接映射到页面令牌（首选）： body.paging.cursors.after 。
2. 使用下一个 URL： body.paging.next?after 。

这两条路径都为连接器提供了用于检索nextPage令牌值的正确位置。

偏移量分页

偏移量分页使用记录号来允许对所有响应对象进行分页。 “偏移量”参数指定在开始返回结果之前要跳过的项目数。

偏移量分页通常使用以下两个参数（确切名称可能有所不同）

• 偏移量- 指示要返回结果的记录的起始位置。

• 限制- 指示每页的结果数量。

资源配置

默认情况下，基于页面的分页分配“页面”和“页面大小”作为分页参数。 您可以将这些覆盖为提供程序规范，如下所示：

1. 选择您的资源。
2. 选择“分页” 选项卡。
3. 启用分页并更新参数名称以匹配提供程序的参数。

分页类型无

如果提供程序 API 不使用分页，请将分页类型设置为无。

资源配置

如果将 “分页类型”设置为 “ 无 ”，则系统会从 “ 列表” 活动资源中删除 分页 选项卡。

最大分页数

“分页最大值”字段是指提供程序可以返回的最大结果数。

Integration Service 的阈值上限为 2,000 个结果。 为了提高效率，我们建议使用较小的数字。

设置身份验证方法

在“身份验证” 选项卡中，配置连接器的身份验证类型。 有关支持的选项的更多信息，请参阅身份验证类型。

测试连接

完成身份验证配置后，从下拉菜单中选择“添加连接”：

如果连接成功，状态将更新为“已连接”。

资源

连接器生成器会根据提供的 API 定义生成资源列表。 左侧菜单显示按组组织的可用资源列表。

1. 单击“更多选项”按钮菜单以进一步配置每种方法。 您可以：
   • 添加方法 – 打开“创建新资源”窗口。
   • “允许方法删除” – 为组中的每个资源激活“删除”图标。
   • 编辑路径 – 编辑资源的路径。 例如： [BASE URL]/pet = https://petstore.swagger.io/v2/pet
   • “删除” – 删除资源组。 系统将显示一条消息，警告您无法撤销该操作。
   • 复制– 打开“复制资源”窗口，您可以在其中编辑路径，选择显示名称和选择方法。
     
     

     

     
     

2. 您还可以通过两种方式 创建新的资源组 ：

   • 空白：配置以下字段：
     • 路径 - [Base URL]/[path]
     • 显示名称
     • 选择方法：“获取”、“按 ID 获取”、“发布”、“放置”、“补丁”、“删除”
       
       

       

       
       
   • 从cURL ：输入 cURL 命令。

配置资源

选择资源时，将显示以下窗口：

根据您选择的资源方法，以下配置选项卡可用：参数、响应/请求字段、分页、搜索。

参数

例如，所有四个选项卡都可用于 GET 方法。 对于 POST 方法，您只能看到“参数” 、“请求字段” 和“响应字段” 选项卡。

在参数中，您可以查看所选资源的可用参数列表，添加新参数或从现有资源导入参数。

此表中列出的参数是使用自定义连接器构建自动化时将在 Studio 中使用的参数。

Pet 对象对应于 Pet 资源组，可用字段是为 GETBYID 资源设置的字段：

响应和请求字段

备注：

当前不支持嵌套数组对象。

发送请求时，系统会自动生成每个资源的“响应” 和“请求” 字段。

在每个相应的选项卡中，您可以编辑或删除任何字段。 如果单击“编辑”图标，则会显示以下配置窗口：

在“响应/请求 字段” 选项卡中，还提供以下选项：

• “覆盖发送请求”复选框 - 如果选中，则在执行发送请求时，系统将重新生成字段列表。 如果您已向资源添加了新字段，请不要选择此选项。

• 其他选项 按钮：

  选项	操作
  更新响应根键	在处理响应中的嵌套数组时定义响应键。
  删除方法的所有字段	删除所选方法的所有字段。
  从有效负载生成	使用服务文档中的有效负载示例或 API 调用来生成资源字段。

• “添加行”按钮 - 向资源添加新字段。

单击“可见列” 图标以在字段表中添加或删除列。

“方法” 列下的每种颜色对应于特定方法：“获取” 、“按 ID 获取” 、“发布” 、“放置” 、“补丁” 和“删除”。

分页

如果您期望列表响应，请为资源启用 分页 。 如果启用分页，则还需要在配置选项卡中为嵌套列表定义 响应根键 。

搜索

激活“启用搜索” 复选框以允许为资源设置搜索。

配置所需的一切后，您可以继续。