Ressourcenbindungen

Ressourcenbindungen in Python-Funktionen: Wie eine deklarierte Plattformressource zur Laufzeit dem Zielmandanten neu zugeordnet wird und warum Bindungen manuell verwaltet werden.

Eine Ressourcenbindung ist eine deklarierte Referenz für eine Plattformressource, die die Runtime neu zuordnen kann. Wenn eine Funktion ein Orchestrator-Asset liest oder eine Integration Service-Verbindung aufruft, benennt sie diese Ressource mit einem Bezeichner, der zur Entwurfszeit festgelegt wurde. Die Bindung macht diesen Bezeichner zu einer deklarierten Abhängigkeit des Pakets und nicht zu einem hartcodierten String, sodass dasselbe Paket in einem anderen Mandanten auf der eigenen Ressource dieses Mandanten ausgeführt werden kann.

Bindungen werden in bindings.json am Projektstamm deklariert und sowohl während einer lokalen Ausführung als auch während einer Auftragsausführung im Orchestrator gelesen.

Warum ein Ressourcenbezeichner keine Funktionseingabe ist

Eine Verbindungs-ID, ein Asset-Name oder ein Bucket-Name identifiziert die Infrastruktur, keine Daten. Das Übergeben einer durch Input funktioniert automatisch, hat aber drei Folgen:

• Jeder Aufrufer muss die Konfiguration des Zielmandanten kennen.
• Der Überschreibungsmechanismus wird nie ausgeführt, da der Bezeichner als Daten und nicht als deklarierte Abhängigkeit eintrifft.
• Das Paket deklariert nicht mehr, dass es die Ressource benötigt, sodass das Bereitstellungstool sie nicht inventarisieren oder neu zuordnen kann.

Eine Bindung hält den Bezeichner aus dem Aufrufvertrag heraus und innerhalb des Paketmanifests, wo das Bereitstellungstool ihn sehen kann.

Wie eine Bindung zur Runtime aufgelöst wird

Jeder SDK-Aufruf, der Überschreibungen unterstützt, löst seine Ressource in vier Phasen auf:

1. Die Plattform stellt die für den aktuellen Mandanten konfigurierte Zuordnung bereit, einen Eintrag pro deklarierter Bindung.
2. Die SDK-Methode liest ihren eigenen Ressourcenbezeichner aus den Aufrufargumenten.
3. Wenn dieser Bezeichner mit einer deklarierten Bindung mit einer Zuordnung übereinstimmt, ersetzt das SDK den zugeordneten Wert, bevor die Anforderung ausgegeben wird.
4. Wenn keine Zuordnung übereinstimmt, wird der Aufruf mit dem Entwurfszeitbezeichner fortgesetzt.

Die vierte Phase ist ein stilles Fallback, das im Ausführungsprotokoll aufgezeichnet wird:

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

Für eine lokale Ausführung sind keine Zuordnungen konfiguriert, sodass diese Zeile für jede Bindung angezeigt wird und dort erwartet wird. Dieselbe Zeile in einem Auftrag, der in einem Zielmandanten ausgeführt wird, bedeutet, dass die Bindung in diesem Mandanten nie zugeordnet wurde und die Funktion stattdessen nach der Entwurfszeitressource greift.

Warnung:

Eine nicht zugeordnete Bindung schlägt den Auftrag nicht fehl. Da der Aufruf auf den Bezeichner zur Entwurfszeit zurückgreift, kann eine Funktion, die für einen anderen Mandanten bereitgestellt wurde, versuchen, die Ressource des ursprünglichen Mandanten zu erreichen.

Die Dateibindungen.json

Jeder Eintrag im resources -Array deklariert eine Ressource. Eine Verbindungsbindung sieht folgendermaßen aus:

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

Feld	Zweck
resource	Der Ressourcentyp: asset, bucket, queue, process, app, index, connection oder mcpServer.
key	Der Bezeichner der Bindung, der mit dem Bezeichner im SDK-Aufruf abgeglichen wird.
value	Die Werte zur Entwurfszeit, die die Laufzeit neu zuordnet. Verbindungen übertragen ConnectionId und Connector; andere Typen enthalten name und folderPath.
metadata	Beschreibende Felder, die die Plattform liest, wenn sie die Bindung auflöst und anzeigt.

Das Format key hängt vom Ressourcentyp ab. Verbindungen verwenden die Verbindungs-ID selbst. Jeder andere Typ verbindet den Ressourcennamen und den Ordnerpfad mit einem Punkt, wie in my_asset.Finance, und lässt das Trennzeichen weg, wenn kein Ordnerpfad zutrifft.

Der Entwurfszeitbezeichner wird an drei Stellen angezeigt, die übereinstimmen müssen: das Literal in Ihrem Funktionscode, das key der Bindung und der defaultValue des identifizierenden Felds in value. Eine Abweichung zwischen ihnen bedeutet, dass die Überschreibungssuche nichts findet und das Fallback angewendet wird.

SDK-Aufrufe, die an Ressourcenüberschreibungen beteiligt sind

Nur die folgenden Aufrufe werden neu zugeordnet. Ein Bezeichner, der an eine andere Methode übergeben wird, wird genau wie geschrieben verwendet.

SDK-Aufruf	Ressourcentyp	Bezeichner
assets.retrieve, assets.retrieve_credential	asset	Erstes Positionsargument, verbunden mit folder_path
buckets.* (alle Methoden)	bucket	name, verbunden mit folder_path
queues.create_item, create_items, create_transaction_item	queue	Warteschlangenname, verbunden mit folder_path
processes.invoke, jobs.resume	process	name oder process_name, verbunden mit folder_path
tasks.create, tasks.retrieve	app	app_name, verbunden mit app_folder_path
context_grounding.* (alle Methoden)	index	name, verbunden mit folder_path
connections.retrieve	connection	Erstes Positionsargument, das eigenständig verwendet wird
mcp.retrieve	mcpServer	slug, verbunden mit folder_path

Die synchronen und asynchronen Varianten jeder Methode verhalten sich identisch. Aufrufe von llm, documents, entities, guardrails, attachments und folders erzeugen keine Bindungen und assets.update auch nicht.

Warum Bindungen nicht von Ihrem Code abgeleitet werden

uipath init erstellt bindings.json mit der erforderlichen Struktur, wenn die Datei fehlt, und lässt eine vorhandene Datei unverändert. Ressourcenaufrufe werden nicht aus Ihrem Code gelesen, sodass ein erneutes Ausführen nach einer Änderung an Input, Output oder einem Ressourcenaufruf die Bindungen nicht aktualisiert. Die Datei wird von Hand verwaltet.

Ressourcennamen sind nicht immer bekannt, bevor die Funktion ausgeführt wird. Ein Literal wie sdk.assets.retrieve("SMTP_HOST") ist durch eine statische Analyse erkennbar, aber sdk.assets.retrieve(input.asset_name) oder ein aus einer Umgebungsvariable gelesener Name hat zum Analysezeitpunkt keinen Wert, der gebunden werden muss.

Da das Tool einen unauflösbaren Namen nicht von einem Projekt unterscheiden kann, das absichtlich nichts deklariert, würde eine partielle Inferenz im Hintergrund handschriftliche Einträge verwerfen und der Verlust würde nur als Bereitstellungsfehler im Zielmandanten auftreten. Es ist sicherer, die Datei unverändert zu lassen.

Tipp:

Die UiPath-Fähigkeiten für Codierungs-Agents enthalten eine Bindungsreferenz, der ein Codierungs-Agent folgen kann, um bindings.json mit Ihrem Code Schritt zu halten. Siehe github.com/UiPath/skills.

Verschieben einer Funktion zwischen Mandanten

Bindungen ermöglichen es, dass ein einzelnes Paket für mehrere Mandanten bereitgestellt werden kann. Wenn ein Funktionsprojekt zu einer Lösung gehört, aggregiert die Lösung die von jedem ihrer Projekte deklarierten Bindungen in einer Ressourcenliste und die Bereitstellung ordnet jeden Eintrag in dieser Liste einer Ressource im Zielmandanten zu.

Zwei Befehle stellen diese Verbindung her:

• uip solution project add registriert das Funktionsprojekt in einer Lösung.
• uip solution resource refresh scannt die Projekte erneut und synchronisiert ihre deklarierten Bindungen mit der Ressourcenliste der Lösung.

Das Ergebnis ist ein .nupkg, der unverändert in der Entwicklung, im Test und in jedem Kundenmandanten ausgeführt wird, da die darin enthaltenen Bezeichner neu zugeordnet und nicht repariert werden.

Nächste Schritte

• Deklarieren einer Ressourcenbindung – Fügen Sie eine Bindung hinzu und stellen Sie sicher, dass sie aufgelöst wird.
• Zugriff auf Plattformdienste – Die SDK-Aufrufe, für die Bindungen gelten.