Associações de recursos

Associações de recursos no Python funcionam: como um recurso de plataforma declarado é remapeado para o tenant de destino no runtime e por que as associações são mantidas manualmente.

Uma associação de recursos é uma referência declarada a um recurso de plataforma que o runtime pode remapear. Quando uma função lê um ativo do Orchestrator ou chama uma conexão do Integration Service, ela nomeia esse recurso com um identificador fixo no momento do design. A associação transforma esse identificador em uma dependência declarada do pacote, em vez de uma string codificada, para que o mesmo pacote possa ser executado em outro tenant no próprio recurso desse tenant.

As associações são declaradas em bindings.json na raiz do projeto e são lidas durante uma execução local e durante uma execução de trabalho no Orchestrator.

Por que um identificador de recurso não é uma entrada de função

Um ID de conexão, nome de ativo ou nome do bucket identifica a infraestrutura, não os dados. Passar um por Input funciona mecanicamente, mas tem três consequências:

• Cada chamador tem que saber a configuração do tenant de destino.
• O mecanismo de substituição nunca é executado, porque o identificador chega como dados em vez de como uma dependência declarada.
• O pacote não declara mais que precisa do recurso, portanto, as ferramentas de implantação não podem inventário ou remapeá-lo.

Uma associação mantém o identificador fora do contrato de invocação e dentro do manifesto do pacote, onde as ferramentas de implantação podem vê-lo.

Como uma associação é resolvida no runtime

Cada chamada do SDK que é compatível com substituições resolve seu recurso em quatro estágios:

1. A plataforma fornece o mapeamento configurado para o tenant atual, uma entrada por associação declarada.
2. O método SDK lê seu próprio identificador de recurso a partir dos argumentos da chamada.
3. Quando esse identificador corresponde uma associação declarada a um mapeamento, o SDK substitui o valor mapeado antes de emitir a solicitação.
4. Quando não há correspondências de mapeamento, a chamada prossegue com o identificador de tempo de design.

O quarto estágio é um fallback silencioso, registrado no log de execução:

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

Uma execução local não tem mapeamentos configurados, então essa linha aparece para cada vinculação e é esperada lá. A mesma linha em um trabalho em execução em um tenant de destino significa que a associação nunca foi mapeada nesse tenant e, em vez disso, a função está alcançando o recurso de tempo de design.

AVISO:

Uma associação não mapeada não gera falha no trabalho. Como a chamada retorna ao identificador de tempo de design, uma função implantada em outro tenant pode tentar alcançar o recurso do tenant original.

O arquivo Bindings.json

Cada entrada na matriz resources declara um recurso. Uma vinculação de conexão se parece com isso:

{
  "$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	Finalidade
resource	O tipo de recurso: asset, bucket, queue, process, app, index, connection ou mcpServer.
key	O identificador da associação, correspondente ao identificador na chamada do SDK.
value	Os valores de tempo de design que o runtime remapeia. As conexões carregam ConnectionId e Connector; outros tipos carregam name e folderPath.
metadata	Campos descritivos que a plataforma lê quando resolve e exibe a associação.

O key formato depende do tipo de recurso. Conexões usam o ID de conexão por conta própria. Todos os outros tipos unem o nome do recurso e o caminho da pasta com um ponto, como em my_asset.Finance, e eliminam o separador quando nenhum caminho de pasta se aplica.

O identificador de tempo de design aparece em três lugares que devem concordar: o literal no código de função, o key da associação e o defaultValue do campo de identificação dentro de value. Uma incompatibilidade entre eles significa que a pesquisa de substituição não encontra nada e o fallback se aplica.

Chamadas do SDK que participam de substituições de recursos

Apenas as chamadas abaixo são remapeadas. Um identificador passado para qualquer outro método é usado exatamente como escrito.

Chamada do SDK	Tipo de Recurso	Identificador
assets.retrieve, assets.retrieve_credential	asset	Primeiro argumento posicional, unido a folder_path
buckets.* (todos os métodos)	bucket	name, associado a folder_path
queues.create_item, create_items, create_transaction_item	queue	Nome da fila, emparelhado com folder_path
processes.invoke, jobs.resume	process	name ou process_name, junto com folder_path
tasks.create, tasks.retrieve	app	app_name, associado a app_folder_path
context_grounding.* (todos os métodos)	index	name, associado a folder_path
connections.retrieve	connection	Primeiro argumento posicional, usado sozinho
mcp.retrieve	mcpServer	slug, associado a folder_path

As variantes síncronas e assíncronas de cada método comportam-se de forma idêntica. As chamadas para llm, documents, entities, guardrails, attachments e folders não produzem associações, nem assets.update.

Por que as associações não são derivadas do seu código

uipath init cria bindings.json com a estrutura necessária quando o arquivo está ausente e deixa um arquivo existente intocado. Ele não lê chamadas de recursos do seu código; portanto, reexecutá-lo após uma alteração em Input, Output ou uma chamada de recurso não atualiza as associações. O arquivo é mantido manualmente.

Os nomes dos recursos nem sempre podem ser conhecidos antes da execução da função. Um literal como sdk.assets.retrieve("SMTP_HOST") é detectável por análise estática, mas sdk.assets.retrieve(input.asset_name) ou um nome lido de uma variável de ambiente não tem valor para associar no tempo da análise.

Como as ferramentas não podem distinguir um nome não resolvido de um projeto que não declara nada intencionalmente, a inferência parcial descartaria silenciosamente entradas escritas à mão, e a perda apareceria apenas como uma falha de implantação no tenant de destino. Deixar o arquivo intacto é o comportamento mais seguro.

Dica:

As habilidades da UiPath para agentes de codificação incluem uma referência de associações que um agente de codificação pode seguir para manter bindings.json em dia com seu código. Consulte github.com/UiPath/skills.

Movimentação de uma função entre tenants

As associações são o que tornam um único pacote implantável em mais de um tenant. Quando um projeto de função pertence a uma solução, a solução agrega as associações declaradas por cada um de seus projetos em uma lista de recursos e a implantação mapeia cada entrada nessa lista para um recurso no tenant de destino.

Dois comandos estabelecem esse link:

• uip solution project add registra o projeto da função em uma solução.
• uip solution resource refresh verifica novamente os projetos e sincroniza suas associações declaradas com a lista de recursos da solução.

O resultado é um .nupkg que é executado inalterado no desenvolvimento, teste e cada tenant do cliente, porque os identificadores que ele carrega são remapeados em vez de corrigidos.

Próximas Etapas

• Declare uma associação de recurso — adicione uma associação e verifique se ela é resolvida.
• Acessando serviços de plataforma — as chamadas do SDK às quais as associações se aplicam.