API リクエストを構築する

Orchestrator API 呼び出しの構造と構文 (URL 形式や HTTPS の推奨事項を含む)

すべての Orchestrator API 呼び出しは、Orchestrator URL への HTTP メソッドを使用して実行されます。Orchestrator URL の構文は次のとおりです。{AutomationCloudURL}/{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"
• X-UIPATH-FolderKey "FolderKey"

フォルダー ID の取得

この FolderId は、 /odata/Folders エンドポイントに対して GET 要求を実行して「Id」の値をコピーするか、Orchestrator URL ( https://your-domain-server.com/?fid=2032&tid=8) から取得できます。 FolderId 型は Int 64 です。Orchestrator アカウントのライセンス プランを変更すると (Enterprise 無料トライアルから Enterprise に変更すると)、 FolderId の値も変わります。

FolderKey の取得

この FolderKey を取得するには、 /odata/Folders エンドポイントに対して GET 要求を実行し、「Key」の値をコピーします。FolderKey は Unique Id/String 型です。ライセンス プランを変更しても FolderKey 値は変わりません。

フォルダーの相対パス

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

• / で始まるパス - 周囲のフォルダーが属するツリーのrootフォルダーから開始します。
• . で始まるパス - 周囲のフォルダーから開始します
• ..で始まるパス - パス内の各..の階層で 1 つ上のレベルから開始します (例:../ 1レベルアップ、 ../../ 2レベルアップ)

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

重要:

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

注:

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

GET 要求

通常、GET 要求は最も簡単に作成できるものです。これらは、データの取得や、下表に示す一般的な OData 句の使用に役立ちます。

OData 句のリファレンス

条項	目的
$top	返される結果の数を制限する
$filter	プロパティの条件に基づいて結果をフィルター処理する
$expand	要求されたリソースのナビゲーション プロパティを読み込みます。
$select	返すリソース プロパティのサブセットを指定します
$orderby	指定したプロパティで結果を並べ替える
$skip	結果の項目を指定した数だけスキップする

$top

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

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

$filter

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

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

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

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

• {AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_/odata/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 であれば、要求が成功したことがわかります。

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