API リクエストを構築する

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

重要:

フォルダー内のリソースにアクセスするには、各要求の HTTP ヘッダーに FolderId FolderPathまたは FolderKey が含まれている必要があります。このヘッダーは、エンコード (Base64 UTF-16LE エンコードを使用) またはプレーン テキストにすることができます。例えば：

• 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 型は一意の ID/文字列です。Orchestrator アカウントのライセンス プランを変更 (Enterprise 無料トライアルから Enterprise プランに変更した場合など)は、 FolderId の値も変更されますが、 FolderKey の値は変わりません。X-UIPATH-FolderPath-Encoded ヘッダーでは、次のように相対フォルダー パスがサポートされています。
• / で始まるパス - 周囲のフォルダーが属するツリーの root フォルダーから開始します。
• . で始まるパス - 周囲のフォルダーから開始します。
• .. で始まるパス - パス内のそれぞれの .. について、周囲のフォルダーの階層で 1 つ上のレベルから開始します (例: ../: 1 レベル上の階層、../../: 2 レベル上の階層)。 末尾にスラッシュを付けることはできませんのでご注意ください。

重要:

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

注:

既定では、 @odata.count パラメーターは、ワークフロー アクティビティから生成される API の結果に出力されません。このパラメーターを含めるには、目的のエンドポイントに手動で $count=true を追加する必要があります。

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 に置換できます。
  注:

  Machine ne null は存在しないため、MachineName ne nullMachineName に置き換えることはできません。

• 複合オブジェクトの入れ子になったプロパティを比較に使用できます。たとえば、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 要求

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

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

注:

POST 要求の本文で特殊文字をエスケープすることはできません。特殊文字を使用するには、まず特殊文字を使用するパラメーターを、次の形式を使用して文字列として宣言する必要があります "[e-mail]": "#String"。よりよく理解するには、以下の例で Specific Content パラメーターがどのように設定されたかをご覧ください。

PUT 要求

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

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

PATCH 要求

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

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

DELETE 要求

この HTTP 動詞を使用すると、指定した項目をデータベースで削除済みとしてマークできます。リソースを指定する場合、通常は、呼び出しの送信先の URL でその ID を使用します。応答が 204 であれば、要求が成功したことがわかります。

アセット、ロボット グループ、キュー アイテムのコメント、プロセス、ロール、テナント、ユーザーなどを削除できます。