リソースのバインド

Python 関数でのリソースのバインド: 宣言されたプラットフォーム リソースを実行時にターゲット テナントに再マッピングする方法と、バインドを手動で保守する理由。

リソース バインディングは、ランタイムで再マップできるプラットフォーム リソースへの宣言された参照です。関数は、Orchestrator アセットを読み取るか、Integration Service のコネクションを呼び出すときに、設計時に固定された識別子を使用してそのリソースに名前を付けます。バインドにより、その識別子がハードコードされた文字列ではなくパッケージの宣言された依存関係に変換されるため、別のテナントで、そのテナントの独自のリソースに対して同じパッケージを実行できます。

バインドはプロジェクトのルートで bindings.json で宣言され、ローカルでの実行中と Orchestrator でのジョブの実行中の両方で読み取られます。

リソース識別子が関数の入力ではない理由

コネクション ID、アセット名、またはバケット名は、データではなくインフラストラクチャを識別します。Inputに通すことは機械的に機能しますが、次の 3 つの結果があります。

• すべての呼び出し元は、対象のテナントの設定を知っている必要があります。
• 識別子は宣言された依存関係としてではなくデータとして到着するため、オーバーライド メカニズムは実行されません。
• パッケージがリソースを必要とすることを宣言しなくなったため、デプロイ ツールでリソースのインベントリを作成したり再マッピングしたりすることはできません。

バインディングにより、識別子が呼び出しコントラクトから除外され、デプロイ ツールが識別子を参照できるパッケージ マニフェスト内に保持されます。

実行時にバインドがどのように解決されるか

オーバーライドをサポートする各 SDK 呼び出しは、そのリソースを次の 4 つのステージで解決します。

1. プラットフォームにより、現在のテナントに設定されたマッピングが、宣言されたバインドごとに 1 つのエントリとして提供されます。
2. SDK メソッドは、呼び出し引数から独自のリソース識別子を読み取ります。
3. その識別子が宣言されたバインディングとマッピングと一致すると、SDK は要求を発行する前にマッピングされた値を置き換えます。
4. 一致するマッピングがない場合、呼び出しは設計時の識別子で続行されます。

第 4 段階はサイレント フォールバックで、実行ログに記録されます。

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

ローカル実行ではマッピングが設定されていないため、この行はすべてのバインドに対して表示され、そこで予期されます。対象のテナントで実行されているジョブに同じ行があるということは、バインドがそのテナントにマッピングされておらず、関数が代わりに設計時リソースに到達していることを意味します。

警告:

マッピングされていないバインドは、ジョブに失敗しません。呼び出しは設計時の識別子にフォールバックするため、別のテナントにデプロイされた関数は、元のテナントのリソースへのアクセスを試みることができます。

bindings.json ファイル

resources配列の各エントリは、1 つのリソースを宣言します。コネクションのバインドは次のようになります。

{
  "$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、適用されるフォルダー パスがない場合は区切り文字が削除されます。

設計時の識別子は、一致する必要がある 3 か所に出現します。関数コード内のリテラル、バインディングのkey、valueおよび 内の識別フィールドのdefaultValueです。これらの不一致は、上書きルックアップで何も見つからず、フォールバックが適用されることを意味します。

リソースのオーバーライドに関与する SDK 呼び出し

以下の呼び出しのみが再マッピングされます。他のメソッドに渡された識別子は、記述したとおりに使用されます。

SDK 呼び出し	リソースの種類	識別子
assets.retrieve, assets.retrieve_credential	asset	最初の位置引数を で結合 folder_path
buckets.* (すべてのメソッド)	bucket	nameで結合された folder_path
queues.create_itemcreate_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 をご覧ください。

テナント間で関数を移動する

バインドとは、1 つのパッケージを複数のテナントにデプロイできるようにするものです。関数プロジェクトがソリューションに属している場合、ソリューションは各プロジェクトによって宣言されたバインディングをリソース リストに集約し、デプロイはそのリスト内のすべてのエントリをターゲット テナントのリソースにマップします。

次の 2 つのコマンドによって、そのリンクが確立されます。

• uip solution project add 関数プロジェクトをソリューションに登録します。
• uip solution resource refreshプロジェクトを再スキャンし、宣言されたバインドをソリューションのリソース リストに同期します。

その結果、1 つの .nupkg が保持される識別子が固定されるのではなく再マッピングされるため、開発、テスト、およびすべての顧客テナントで変更されずに実行されます。

次のステップ

• リソース バインドを宣言する — バインドを追加し、解決されることを確認します。
• プラットフォーム サービスへのアクセス — バインドが適用される SDK 呼び出しです。