API リクエストを構築する

すべての Orchestrator API 呼び出しは、Orchestrator URL への HTTP メソッドを使用して実行されます。Orchestrator URL の構文は次のとおりです。 https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_ HTTPS プロトコルを使用し、API 呼び出しを介して送信するデータを暗号化することをお勧めします。

重要:

For accessing resources in a folder, each request must contain either the FolderId, FolderPath, or FolderKey in an HTTP header. This header may be encoded (using Base64 UTF-16LE encoding) or plain text.

例:

X-UIPATH-OrganizationUnitId "FolderId"
X-UIPATH-FolderPath-Encoded "{Encoded FolderPath value}"
X-UIPATH-FolderPath "PlainText FolderPath value", or
X-UIPATH-FolderKey "FolderKey" です。

FolderId を取得するには、/odata/Folders エンドポイントに GET 要求を送信して「Id」の値をコピーするか、Orchestrator URL (https://your-domain-server.com/?fid=2032&tid=8) から取得できます。FolderId は Int64 型です。

FolderKey を取得するには、/odata/Folders エンドポイントに GET 要求を送信して「Key」の値をコピーします。FolderKey は Unique Id/String 型です。

Orchestrator アカウントのライセンスプランを変更した場合 (例: Enterprise 無料トライアルから Enterprise プランに変更)、FolderId の値も変更されますが、FolderKey の値は変わりません。

アップグレードして、以前の Orchestrator インスタンスで組織単位を有効にした場合、各組織単位は新しいクラシックフォルダーとして移行されます。

X-UIPATH-FolderPath-Encoded ヘッダーでは、以下のように相対フォルダーパスがサポートされています。

/ で始まるパス - 周囲のフォルダーが属するツリーの root フォルダーから開始します。
. で始まるパス - 周囲のフォルダーから開始します。
.. で始まるパス - パス内のそれぞれの .. について、周囲のフォルダーの階層で 1 つ上のレベルから開始します (例: ../: 1 レベル上の階層、../../: 2 レベル上の階層)。

末尾にスラッシュを付けることはできませんのでご注意ください。

重要: Orchestrator API を MSXML と組み合わせて使用すると、「204 コンテンツなし」の応答が返されてステータスコード 1223 が生成され、エラーが発生する場合があります。

GET 要求

GET 要求は通常、最も簡単に実行できる要求です。データを取得したり、一般的な OData 句を使用したりするのに便利です。

$top
$filter
$expand
$select
$orderby
$skip

$top

この句を使用すると、取得するデータの量を制限できます。この句には上限があり、呼び出すエンドポイントと、Orchestrator インスタンスに存在する該当リソースの数によって決まります。

たとえば、要求 https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Environments?$top=10 は、Orchestrator の Community Edition で利用可能な最初の 10 個のロボットグループを返します。ただし、存在するロボットグループが 5 個しかない場合は、5 個のみを取得します。

$filter

この OData 句は、特定のリソースをそのプロパティに従ってフィルター処理する場合に使用します。

たとえば、次の条件でフィルター処理できます。

数値プロパティ:
- https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Environments?$filter=Id%20eq%2015 - 特定のロボットグループをその ID に基づいて要求します。
テキストプロパティ:
- https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Environments?$filter=contains(Name,'N')&$top=10 - 名前に文字「N」が含まれる最初の 10 個のロボットグループを返します。
Boolean プロパティ:
- https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Processes?$filter=Title%20eq%20'test'%20%26%20IsLatestVersion%20eq%20true - 「test」という単語を含み、最新バージョンに相当するプロセスをすべて返します。
enumerable properties:
- https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/QueueItems?$filter=Priority%20eq%20'High' - 優先度が「高」のキューアイテムをすべて返します。
プロパティのプロパティ:
- https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Jobs?$top=10$filter=Robot/MachineName%20eq%20'Documentation' - 「Documentation」マシン上に存在する任意のロボットによって実行された最初の 10 個のジョブを返します。

論理演算子「and」、「or」、および/または「not」を使用して複数のフィルターパラメーターを組み合わせたり、括弧「( )」でグループ化したりできます。以下に要求の例を示します。

https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Jobs?$top=10&$filter=Robot/MachineName eq 'LAVINIA-PC' and (not(Source eq 'Manual') or StartTime gt 2017-10-28T12:13:00.07Z) - 手動で実行されるジョブ、または「2017-10-28T12:13:00.07Z」より後に、マシン「LAVINIA-PC」にデプロイされたロボットによって実行されるジョブの上位 10 個を表示します。

既知の問題

入れ子になった複合オブジェクトを null と比較する式を含む OData の $filter クエリは機能しません。たとえば、Release ne null 式を使用するとエラーが返されます。これは、Release はそれ自体の入れ子になったプロパティを含む複合オブジェクトであるためです。

このような場合は、複合オブジェクトを単一オブジェクトに置換することをお勧めします。

例:

ReleaseName は既存の単一オブジェクトであるため、Release ne null を ReleaseName ne null に置換できます。
注: MachineName は存在しないため、Machine ne null を MachineName ne null に置換できません。
複合オブジェクトの入れ子になったプロパティを比較に使用できます。たとえば、Release/Name ne null は Release ne null を置換し、Machine/Name ne null は Machine ne null を置換できます。

$expand

この句は、要求されたリソースのナビゲーションプロパティを完全に読み込む場合に使用します。

$select

この OData 句では、返す必要がある、リソースプロパティのサブセットを指定できます。複数のリソースを抽出する場合は、各リソースをコンマで区切ります。

$orderby

$orderby 句では、取得したリソースを並べ替えることができます。$select 句と同様に、並べ替え条件として使用するリソースが複数ある場合は、各リソースをコンマで区切ります。昇順 (asc) または降順 (desc) で並べ替えることができます。どちらの演算子も指定されていない場合、リソースは自動的に昇順で並べ替えられます。

$skip

この句では、指定したフィルターで最初の n 個の項目をスキップできます。

POST Requests

POST HTTP 動詞では、新しい項目を他のリソースの下位に作成できます。新しいリソースを作成する場合、親リソースに POST を送信します。新しいリソースは Orchestrator によって親に関連付けられ、ID などの必要な情報が割り当てられます。データは要求の本文を使用して追加し、応答は作成されたオブジェクト全体になります。

キューに新しいアイテムを追加する、新しいアセット、ロボットグループ、プロセスを作成する、レビュー担当者を 1 つまたは複数の失敗したトランザクションに割り当てるなど、さまざまな操作を実行できます。

注: POST 要求の本文で特殊文字をエスケープすることはできません。特殊文字を使用するには、まず特殊文字を使用するパラメーターを文字列として宣言する必要があります。宣言に使用する形式は、"Parameter@odata.type": "#String" です。理解を深めるには、以下の例で Specific Content パラメーターの設定方法をご覧ください。

PUT Requests

PUT は通常、リソースの内容を更新する場合に必要になります。一般に、特定のエンティティに対して要求を実行するには、その Id を URL に追加します。PUT 呼び出しは、既存のエンティティを要求の内容に置き換えます。指定した場所にエンティティが存在しない場合は、エンティティの作成を試みます。

キュー、ロボットグループ、組織単位や、トランザクション、プロセスなどのリソースの詳細に関するコメントを更新できます。

PATCH Requests

PATCH は、既存のエンティティの内容を目的のエンティティで更新する場合に使用します。目的のエンティティを指定するには、その Id を URL に追加します。要求の本文には、変更する内容のみを含めます。ここが PUT 呼び出しとは異なります。PUT 呼び出しは現在のエンティティを後続の要求の内容に置き換えます。

PATCH 要求を使用して更新できるエンティティは、マシン、プロセス、ロボット、テナント、ユーザー (組織単位とロールを除く)、および Webhook です。