Liaisons de ressources

Liaisons de ressources dans les fonctions Python: comment une ressource de plateforme déclarée est remappée au locataire cible au moment du runtime et pourquoi les liaisons sont gérées par la main.

Une liaison de ressource est une référence déclarée à une ressource de la plate-forme que le runtime peut remapper. Lorsqu'une fonction lit une ressource Orchestrator ou appelle une connexion Integration Service, elle nomme cette ressource avec un identifiant fixe au moment de la conception. La liaison transforme cet identifiant en une dépendance déclarée du package plutôt qu’une chaîne codée en dur, de sorte que le même package peut s’exécuter dans un autre locataire avec la propre ressource de ce locataire.

Les liaisons sont déclarées dans bindings.json à la racine du projet et sont lues à la fois lors d'une exécution locale et d'une exécution de tâche dans Orchestrator.

Pourquoi un identificateur de ressource n'est pas une entrée de fonction

Un ID de connexion, un nom de ressource ou un nom de compartiment identifie l'infrastructure, et non les données. La transmission d'un fichier via Input fonctionne automatiquement, mais a trois conséquences:

• Chaque appelant doit connaître la configuration du locataire cible.
• Le mécanisme de remplacement ne s'exécute jamais, car l'identifiant arrive sous forme de données plutôt que sous forme de dépendance déclarée.
• Le package ne déclare plus avoir besoin de la ressource, de sorte que les outils de déploiement ne peuvent pas l’inventaire ou la remapper.

Une liaison maintient l'identifiant en dehors du contrat d'invocation et à l'intérieur du manifeste du package, où les outils de déploiement peuvent le voir.

Comment une liaison se résout au moment du runtime

Chaque appel SDK qui prend en charge les remplacements résout sa ressource en quatre étapes:

1. La plate-forme fournit le mappage configuré pour le locataire actuel, une entrée par liaison déclarée.
2. La méthode SDK lit son propre identifiant de ressource à partir des arguments d'appel.
3. Lorsque cet identifiant correspond à une liaison déclarée avec un mappage, le SDK remplace la valeur mappée avant d’émettre la requête.
4. Lorsqu’aucun mappage ne correspond, l’appel se poursuit avec l’identificateur au moment de la conception.

La quatrième étape est une solution de secours silencieuse, enregistrée dans le journal d’exécution:

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

Dans une exécution locale, aucun mappage n’est configuré. Cette ligne apparaît donc pour chaque liaison et y est attendue. La même ligne dans une tâche s'exécutant dans un locataire cible signifie que la liaison n'a jamais été mappée dans ce locataire et que la fonction atteint la ressource de phase de conception à la place.

Avertissement :

Une liaison non mappée n'échoue pas la tâche. Étant donné que l'appel revient à l'identifiant de la conception, une fonction déployée dans un autre locataire peut tenter d'atteindre la ressource du locataire d'origine.

Le fichier Bins.json

Chaque entrée du tableau resources déclare une ressource. Une liaison de connexion ressemble à ce qui suit:

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

Champ	Objectif
resource	Type de ressource: asset, bucket, queue, process, app, index, connection ou mcpServer.
key	L'identifiant de la liaison, correspondant à l'identifiant dans l'appel SDK.
value	La valeur de la phase de conception pour les nouveaux mappages de runtime. Les connexions comportent ConnectionId et Connector; les autres types portent name et folderPath.
metadata	Champs descriptifs que la plate-forme lit lorsqu'elle résout et affiche la liaison.

Le format key dépend du type de ressource. Les connexions utilisent l'ID de connexion seul. Tout autre type joint le nom de la ressource et le chemin de dossier par un point, comme dans my_asset.Finance, et supprime le séparateur lorsqu'aucun chemin de dossier ne s'applique.

L'identifiant lors de la conception apparaît à trois endroits qui doivent correspondre: le littéral dans votre code de fonction, le key de la liaison et le defaultValue du champ d'identification dans value. Une incompatibilité entre eux signifie que la recherche de remplacement ne trouve rien et que le remplacement s'applique.

Appels SDK qui participent au remplacement des ressources

Seuls les appels ci-dessous sont remappés. Un identificateur transmis à n'importe quelle autre méthode est utilisé exactement tel qu'il est écrit.

Appel du SDK	Type de ressource	Identificateur
assets.retrieve, assets.retrieve_credential	asset	Premier argument de position, joint à folder_path
buckets.* (toutes les méthodes)	bucket	name, associé à folder_path
queues.create_item, create_items, create_transaction_item	queue	Nom de la file d'attente, joint avec folder_path
processes.invoke, jobs.resume	process	name ou process_name, joint avec folder_path
tasks.create, tasks.retrieve	app	app_name, associé à app_folder_path
context_grounding.* (toutes les méthodes)	index	name, associé à folder_path
connections.retrieve	connection	Premier argument de position, utilisé seul
mcp.retrieve	mcpServer	slug, associé à folder_path

Les variantes synchrones et asynchrones de chaque méthode se comportent de la même manière. Les appels vers llm, documents, entities, guardrails, attachments et folders ne produisent aucune liaison, contrairement à assets.update.

Pourquoi les liaisons ne sont pas dérivées de votre code

uipath init crée bindings.json avec la structure requise lorsque le fichier est absent et laisse un fichier existant inchangé. Elle ne lit pas les appels de ressources dans votre code. Par conséquent, sa réexécution après une modification vers Input, Output ou un appel de ressource ne met pas à jour les liaisons. Le fichier est maintenu à la main.

Les noms de ressources ne sont pas toujours connaissables avant l’exécution de la fonction. Un littéral tel que sdk.assets.retrieve("SMTP_HOST") est détectable par une analyse statique, mais sdk.assets.retrieve(input.asset_name) ou un nom lu à partir d'une variable d'environnement n'a aucune valeur à lier au moment de l'analyse.

Étant donné que l'outil ne peut pas distinguer un nom ne pouvant être résolu d'un projet qui ne déclare intentionnellement rien, l'inférence partielle ignorerait silencieusement les entrées manuscrites, et la perte n'apparaîtrait qu'comme un échec de déploiement dans le locataire cible. Le comportement plus sûr est de laisser le fichier inchangé.

Astuce :

Les compétences UiPath pour les agents de codage incluent une référence de liaisons qu'un agent de codage peut suivre pour que bindings.json soit synchronisé avec votre code. Voir github.com/UiPath/skills.

Déplacer une fonction entre des locataires

Les liaisons rendent un paquet unique déployable sur plus d'un locataire. Lorsqu'un projet de fonction appartient à une solution, la solution agrège les liaisons déclarées par chacun de ses projets dans une liste de ressources, et le déploiement mappe chaque entrée de cette liste à une ressource dans le locataire cible.

Deux commandes établissent ce lien:

• uip solution project add enregistre le projet de fonction dans une solution.
• uip solution resource refresh analyse à nouveau les projets et synchronise leurs liaisons déclarées dans la liste des ressources de la solution.

Il en résulte un .nupkg qui s’exécute inchangé dans le développement, les tests et chaque locataire client, car les identifiants qu’il transporte sont remappés plutôt que corrigés.

Prochaines étapes

• Déclarez une liaison de ressource : ajoutez une liaison et vérifiez qu’elle se résout.
• Accéder aux services de la plate-forme — aux appels SDK auxquels les liaisons s'appliquent.