API リクエストを構築する

All Orchestrator API calls are made using HTTP methods to the Orchestrator URL. The Orchestrator URL has the following syntax: https://{yourDomain} . It is recommended to encrypt the data you send via API calls, by using the HTTPS protocol.

重要:

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 の値は変わりません。

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 インスタンスに存在する該当リソースの数によって決まります。

For example, this request https://{yourDomain}/odata/Environments?$top=10 returns the first 10 environments available in the Community Edition of Orchestrator. However, if only 5 environments exist, only those are retrieved.

$filter

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

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

• 数値プロパティ:

  • https://{yourDomain}/odata/Environments?$filter=Id%20eq%2015 - requests a specific environment based on its Id

• テキスト プロパティ:

  • https://{yourDomain}/odata/Environments?$filter=contains(Name,'N')&$top=10 - returns the first 10 environments whose name contains the letter "N"

• Boolean プロパティ:

  • https://{yourDomain}/odata/Processes?$filter=Title%20eq%20'test'%20%26%20IsLatestVersion%20eq%20true - returns all processes that contain the word "test" and represent the latest version

• enumerable properties:

  • https://{yourDomain}/odata/QueueItems?$filter=Priority%20eq%20'High' - returns all queue items that have a High priority

• プロパティのプロパティ:

  • https://{yourDomain}/odata/Jobs?$top=10$filter=Robot/MachineName%20eq%20'Documentation' - returns the first 10 jobs that were executed by any Robot that exists on the "Documentation" machine

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

• https://{yourDomain}/odata/Jobs?$top=10&$filter=Robot/MachineName eq 'LAVINIA-PC' and (not(Source eq 'Manual') or StartTime gt 2017-10-28T12:13:00.07Z) - displays the top 10 jobs that are being executred manually or after "2017-10-28T12:13:00.07Z", by a Robot deployed on the "LAVINIA-PC" machine.

$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 であれば、要求が成功したことがわかります。

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