Vinculaciones de recursos

Vinculaciones de recursos en funciones de Python: cómo un recurso de plataforma declarado se reasigna al tenant de destino en runtime y por qué las vinculaciones se mantienen a mano.

Una vinculación de recursos es una referencia declarada a un recurso de plataforma que el runtime puede reasignar. Cuando una función lee un activo de Orchestrator o llama a una conexión de Integration Service, nombra ese recurso con un identificador fijado en tiempo de diseño. La vinculación convierte ese identificador en una dependencia declarada del paquete en lugar de una cadena codificada, por lo que el mismo paquete puede ejecutarse en otro tenant con el propio recurso de ese tenant.

Las vinculaciones se declaran en bindings.json en la raíz del proyecto y se leen tanto durante una ejecución local como durante una ejecución de trabajo en Orchestrator.

Por qué un identificador de recursos no es una entrada de función

Un ID de conexión, un nombre de activo o un nombre de depósito identifica la infraestructura, no los datos. Pasar uno a través de Input funciona mecánicamente, pero tiene tres consecuencias:

• Cada persona que llama debe conocer la configuración del tenant de destino.
• El mecanismo de anulación nunca se ejecuta, porque el identificador llega como datos en lugar de como una dependencia declarada.
• El paquete ya no declara que necesita el recurso, por lo que las herramientas de implementación no pueden inventariarlo ni reasignarlo.

Una vinculación mantiene el identificador fuera del contrato de invocación y dentro del manifiesto del paquete, donde las herramientas de implementación pueden verlo.

Cómo se resuelve una vinculación en runtime

Cada llamada de SDK que admite anulaciones resuelve su recurso en cuatro etapas:

1. La plataforma proporciona la asignación configurada para el tenant actual, una entrada por enlace declarado.
2. El método SDK lee su propio identificador de recursos de los argumentos de la llamada.
3. Cuando ese identificador coincide con una vinculación declarada con una asignación, el SDK sustituye el valor asignado antes de emitir la solicitud.
4. Cuando no coincide ninguna asignación, la llamada continúa con el identificador de tiempo de diseño.

La cuarta etapa es una alternativa silenciosa, registrada en el registro de ejecución:

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

Una ejecución local no tiene asignaciones configuradas, por lo que esta línea aparece para cada vinculación y se espera allí. La misma línea en un trabajo que se ejecuta en un tenant de destino significa que la vinculación nunca se asignó en ese tenant, y la función está alcanzando el recurso de tiempo de diseño en su lugar.

ADVERTENCIA:

Una vinculación no asignada no hace que el trabajo falle. Como la llamada recurre al identificador de tiempo de diseño, una función implementada en otro tenant puede intentar llegar al recurso del tenant original.

El archivo vinculantes.json

Cada entrada en la matriz resources declara un recurso. Un enlace de conexión se ve así:

{
  "$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"
      }
    }
  ]
}

Campo	Propósito
resource	El tipo de recurso: asset, bucket, queue, process, app, index, connection o mcpServer.
key	El identificador de la vinculación, comparado con el identificador en la llamada del SDK.
value	Los valores de tiempo de diseño que el runtime reasigna. Las conexiones llevan ConnectionId y Connector; otros tipos llevan name y folderPath.
metadata	Campos descriptivos que la plataforma lee cuando resuelve y muestra la vinculación.

El formato key depende del tipo de recurso. Las conexiones utilizan el ID de conexión por sí solo. Cualquier otro tipo une el nombre del recurso y la ruta de la carpeta con un punto, como en my_asset.Finance, y suelta el separador cuando no se aplica ninguna ruta de carpeta.

El identificador de tiempo de diseño aparece en tres lugares que deben coincidir: el literal en tu código de función, el key de la vinculación y el defaultValue del campo de identificación dentro de value. Si no coinciden, la búsqueda de anulación no encuentra nada y se aplica la alternativa.

Llamadas de SDK que participan en anulaciones de recursos

Solo se reasignan las siguientes llamadas. Un identificador pasado a cualquier otro método se utiliza exactamente como está escrito.

Llamada SDK	TipoDeRecurso	Identificador
assets.retrieve, assets.retrieve_credential	asset	Primer argumento posicional, unido con folder_path
buckets.* (todos los métodos)	bucket	name, unido a folder_path
queues.create_item, create_items, create_transaction_item	queue	Nombre de cola, unido con folder_path
processes.invoke, jobs.resume	process	name o process_name, unido con folder_path
tasks.create, tasks.retrieve	app	app_name, unido a app_folder_path
context_grounding.* (todos los métodos)	index	name, unido a folder_path
connections.retrieve	connection	Primer argumento posicional, utilizado por sí solo
mcp.retrieve	mcpServer	slug, unido a folder_path

Las variantes síncrona y asíncrona de cada método se comportan de forma idéntica. Las llamadas a llm, documents, entities, guardrails, attachments y folders no producen vinculaciones, y assets.update tampoco.

Por qué las vinculaciones no se derivan de tu código

uipath init crea bindings.json con la estructura necesaria cuando el archivo está ausente y deja intacto un archivo existente. No lee las llamadas de recursos de tu código, por lo que volver a ejecutarlo después de un cambio en Input, Output o una llamada de recurso no actualiza las vinculaciones. El archivo se mantiene a mano.

Los nombres de los recursos no siempre se pueden conocer antes de que se ejecute la función. Un literal como sdk.assets.retrieve("SMTP_HOST") es detectable por análisis estático, pero sdk.assets.retrieve(input.asset_name) o un nombre leído de una variable de entorno no tiene valor para vincular en el momento del análisis.

Debido a que las herramientas no pueden distinguir un nombre irresoluble de un proyecto que intencionalmente no declara nada, la inferencia parcial descartaría silenciosamente las entradas escritas a mano, y la pérdida emergería solo como un error de implementación en el tenant de destino. Dejar el archivo intacto es el comportamiento más seguro.

Consejo:

Las habilidades de UiPath para agentes de codificación incluyen una referencia de vinculaciones que un agente de codificación puede seguir para mantenerse bindings.json en sintonía con tu código. Consulta github.com/UiPath/skills.

Mover una función entre tenants

Las vinculaciones son las que hacen que un único paquete se pueda implementar en más de un tenant. Cuando un proyecto de función pertenece a una solución, la solución agrega los enlaces declarados por cada uno de sus proyectos en una lista de recursos, y la implementación asigna cada entrada de esa lista a un recurso en el tenant de destino.

Dos comandos establecen ese enlace:

• uip solution project add registra el proyecto de función en una solución.
• uip solution resource refresh vuelve a escanear los proyectos y sincroniza sus enlaces declarados en la lista de recursos de la solución.

El resultado es uno .nupkg que se ejecuta sin cambios en desarrollo, prueba y en cada tenant del cliente, porque los identificadores que lleva se reasignan en lugar de corregirse.

Próximos pasos

• Declarar una vinculación de recursos : añade una vinculación y verifica que se resuelva.
• Acceder a los servicios de la plataforma : las llamadas de SDK a las que se aplican los enlaces.