资源绑定

Python 函数中的资源绑定：如何在运行时将已声明的平台资源重新映射到目标租户，以及手动维护绑定的原因。

资源绑定是对运行时可以重新映射的平台资源的声明引用。当函数读取 Orchestrator 资产或调用 Integration Service 连接时，它会使用在设计时固定的标识符命名该资源。绑定会将标识符转换为已声明的包依赖项，而非硬编码字符串，因此同一包可以在另一个租户自己的资源中运行。

绑定在项目根目录的 bindings.json 中声明，并在本地运行和 Orchestrator 中的作业运行期间读取。

为什么资源标识符不能作为函数输入

基础架构（而非数据）由连接 ID、资产名称或存储桶名称标识。通过 Input 传递 1 会产生三个后果：

• 每个调用者都必须了解目标租户的配置。
• 覆盖机制永远不会运行，因为标识符作为数据到达，而不是作为声明的依赖项。
• 该包不再声明它需要资源，因此部署工具无法清点或重新映射该资源。

绑定会将标识符保留在调用合同之外和包清单中，部署工具可以在其中查看该标识符。

如何在运行时解析绑定

每个支持覆盖的 SDK 调用都分四个阶段解析其资源：

1. 平台提供为当前租户配置的映射，每个声明的绑定有一个条目。
2. SDK 方法从调用参数中读取自己的资源标识符。
3. 当该标识符将声明的绑定与映射匹配时，SDK 在发出请求之前会替换映射的值。
4. 如果没有匹配的映射，则将使用设计时标识符继续调用。

第四阶段是静默回退，记录在运行日志中：

No resource overwrite matched for connection key='connection.<design-time-id>' on retrieve

本地运行未配置映射，因此此行将为每个绑定显示，也是预期的结果。在目标租户中运行的作业中的同一行意味着从未在该租户中映射绑定，并且该函数正在访问设计时资源。

警告：

取消映射的绑定不会使作业失败。由于调用回退到设计时标识符，因此部署到其他租户的函数可以尝试访问原始租户的资源。

绑定.json 文件

resources 数组中的每个条目都声明一个资源。连接绑定如下所示：

{
  "$schema": "https://cloud.uipath.com/draft/2024-12/bindings",
  "version": "2.0",
  "resources": [
    {
      "resource": "connection",
      "key": "00000000-0000-0000-0000-000000000000",
      "value": {
        "ConnectionId": {
          "defaultValue": "00000000-0000-0000-0000-000000000000",
          "isExpression": false,
          "displayName": "Microsoft Outlook 365 Connection"
        },
        "Connector": {
          "defaultValue": "uipath-microsoft-outlook365",
          "isExpression": false,
          "displayName": "Connector"
        }
      },
      "metadata": {
        "Connector": "uipath-microsoft-outlook365",
        "UseConnectionService": "True",
        "BindingsVersion": "2.2"
      }
    }
  ]
}

字段	用途
resource	资源类型：asset、bucket、queue、process、app、index、connection 或 mcpServer。
key	绑定的标识符，与 SDK 调用中的标识符进行匹配。
value	运行时重新映射的设计时值。连接带有 ConnectionId 和 Connector；其他类型带有 name 和 folderPath。
metadata	平台在解析并显示绑定时读取的描述性字段。

key 格式取决于资源类型。连接单独使用连接 ID。每种其他类型都会用点号将资源名称和文件夹路径连接起来，如 my_asset.Finance 所示，并在没有适用的文件夹路径时删除分隔符。

设计时标识符出现在三个必须一致的位置：函数代码中的文字、绑定的 key 和 defaultValue 中识别字段的 value。如果它们之间不匹配，则意味着覆盖查找找不到任何内容，并且会应用回退。

参与资源覆盖的 SDK 调用

只有以下调用会被重新映射。传递给任何其他方法的标识符将与写入的标识符完全相同。

SDK 调用	资源类型	标识符
assets.retrieve, assets.retrieve_credential	asset	第一个位置参数，加入： folder_path
buckets.* （所有方法）	bucket	name，加入与 folder_path
queues.create_item, create_items, create_transaction_item	queue	队列名称，联接为 folder_path
processes.invoke, jobs.resume	process	name 或 process_name，使用 folder_path 联接
tasks.create, tasks.retrieve	app	app_name，加入与 app_folder_path
context_grounding.* （所有方法）	index	name，加入与 folder_path
connections.retrieve	connection	第一个位置参数，单独使用
mcp.retrieve	mcpServer	slug，加入与 folder_path

每种方法的同步变体和异步变体行为相同。对 llm、documents、entities、guardrails、attachments 和 folders 的调用不会生成绑定，assets.update 也不会生成。

为何绑定不是从您的代码派生

当文件不存在时，uipath init 将创建具有所需结构的 bindings.json，并保持现有文件不变。它不会从您的代码中读取资源调用，因此在更改 Input、Output 或资源调用后重新运行代码不会更新绑定。由手动维护该文件。

在函数运行之前，资源名称并不总是已知的。静态分析可以检测到 sdk.assets.retrieve("SMTP_HOST") 等文字，但 sdk.assets.retrieve(input.asset_name) 或从环境变量中读取的名称在分析时没有要绑定的值。

由于该工具无法区分无法解析的名称与有意未声明任何内容的项目，因此部分推理会静默丢弃手写条目，并且丢失情况仅会在目标租户中作为部署失败显现出来。保持文件不变是更安全的行为。

提示：

编码智能体的 UiPath 技能包含一个绑定参考，编码智能体可以遵循该参考，以使 bindings.json 与您的代码保持同步。请参阅github.com/UiPath/skills 。

在租户之间移动功能

绑定使单个包可部署至多个租户。当函数项目属于解决方案时，解决方案会将每个项目声明的绑定聚合到资源列表中，并且部署会将该列表中的每个条目映射到目标租户中的资源。

有两个命令可建立该链接：

• uip solution project add在解决方案中注册函数项目。
• uip solution resource refresh重新扫描项目，并将其声明的绑定同步到解决方案的资源列表中。

结果是一个 .nupkg 在开发、测试和每个客户租户中运行不变，因为它携带的标识符被重新映射而不是固定。

后续步骤

• 声明资源绑定— 添加绑定并验证其是否解析。
• 访问平台服务— 绑定适用的 SDK 调用。