根据 API 定义构建连接器

新建连接器

1. If you select Start from an API definition, you must provide the API definition:

   • 从本地文件 – 上传 Postman 或 Swagger 集合。

   • 来自 URL – 输入文件 URL，例如https://petstore.swagger.io/v2/swagger.json 。

     

2. 选择“继续” 。

配置连接器

1. In the Confirm import window, you can:

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

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

     • Use the Search bar to look for a specific resource.

   • 选择“创建”。

     

2. The Settings window is now displayed.

3. In the Info tab you can configure the following fields:

   • 名称- 这会反映在您的连接器密钥中。
   • API type – This field is disabled by default, as only REST is currently supported.
   • “类别” - 您可以从可用的类别中进行选择，例如“人工智能” 或“市场营销”，也可以创建自己的类别。
   • Description – Enter a description for your connector.
   • “图标” – 选择“浏览”以从您的计算机上传图像。支持所有图像类型，但我们建议使用方形 SVG。

4. Catalog preview displays how your custom connector will appear in the Integration Service connector catalog.

5. 选择“保存”。

   

配置基本 API

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

• Base URL – Automatically filled with the value declared at connector creation.

• 分页类型– 下拉列表中的可用选项包括：以 1 开头的分页、以 0 开头的分页、偏移量、自定义、无。如果供应商文档未提供有关分页的任何详细信息，请保留默认值。有关详细信息，请参阅分页部分。

• Pagination max – Default value is 100. If the vendor documentation doesn’t provide any details on pagination, keep the default value.

• “内容类型” 标头– 默认情况下禁用此字段。当前仅支持application/json 。

• “接受”标头– 默认情况下禁用此字段。当前仅支持application/json 。

  

分页

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

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

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

分页类型

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

• 以 1 开头的页
• 从 0 开始的页
• 偏移
• 光标
• 无

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

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

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

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

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

• 以 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令牌名称和页面大小名称以匹配提供程序 API。根据 Meta Graph API 文档，下一页令牌名称为之后，页面大小为限制。

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="  }}{  "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 不使用分页，请将分页类型设置为无。

资源配置

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

最大分页数

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

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

设置身份验证方法

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

测试连接

Once you have completed the authentication configuration, select Add connection from the drop-down menu:

If your connection is successful, the status is updated to Connected.

资源

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

1. 选择“更多选项”按钮菜单以进一步配置每种方法。您可以：

   • Add method – Opens the Create new resource window.

   • Allow method deletion – Activates a Delete icon for each resource in the group.

   • Edit path – Edit the resource’s path. For example: [BASE URL]/pet = https://petstore.swagger.io/v2/pet

   • Delete – Deletes a resource group. A message warns you that the operation cannot be undone.

   • 复制– 打开复制资源窗口，您可以在其中编辑路径，选取显示名称和选择方法。

     

2. 您还可以通过两种方式创建新的资源组：
   • 空白：配置以下字段：

     • Path - [Base URL]/[path]

     • 显示名称

     • Select methods: Get, Get By Id, Post, Put, Patch, Delete

       

   • 使用cURL（可选） ：输入 cURL 命令。

配置资源

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

Depending on the resource method you select, the following configuration tabs are available: Parameters, Response/Request Fields, Pagination, Search.

参数

例如，GET 方法可使用所有四个选项卡。 对于 POST 方法，仅显示“参数”、“请求字段”和“响应字段”选项卡。

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

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

The Pet object corresponds to the Pet resource group, and the available fields are the ones set for the GETBYID resource:

响应和请求字段

备注：

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

The Response and Request fields for each resource are automatically generated upon sending a request.

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

In the Response/Request fields tab, the following options are also available:

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

• Additional options button:

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

• Add row button - Adds new fields to the resource.

选择“可见列” 图标以在字段表格中添加或删除列。

Each color under the Methods column corresponds to a certain method: Get, Get by ID, Post, Put, Patch, Delete.

分页

Enable Pagination for a resource if you expect a list response. If you enable pagination, you also need to define the Response root key in the configuration tab, for nested lists.

搜索

Activate the Enable Search checkbox to allow search setup for a resource.

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