API を使用する

注:

UiPath は、API を予測可能にすると同時に、使いやすく、連携しやすいものにすることを目指しています。改善に役立つフィードバックがある場合や、問題や予期しない動作が発生した場合は、 サポートにお問い合わせください。できるだけ早くご連絡いたします。

API エンドポイント

すべての API 要求は、HTTPS 経由で JSON オブジェクトとしてテナント エンドポイント に Communications Mining™ に送信されます。

注:

利用可能なすべてのエンドポイントは、データ マネージャーで確認できます。また、 API チュートリアルもご覧ください。

UiPath® 経由でオンボーディングされたテナント:

https://cloud.uipath.com/<my_uipath_organisation>/<my_uipath_tenant>/reinfer_/api/...

Communications Mining を介してオンボードされたテナント:

https://<mydomain>.reinfer.io/api/...

重要:

Communications Mining™ では、開発データと運用データ、およびワークフローを分離するには、別々のテナントを使用するか、同じテナント内の別々のプロジェクトに配置します。いずれの場合も、データアクセスは個別に許可されるため、開発者は開発データへの管理者アクセスを持ち、本番環境ではより厳格な制御を課すことができます。別々のテナントを使用する場合、API エンドポイントは開発データと運用データごとに異なります。同じテナント内で別個のプロジェクトを使用する場合、その 1 つのテナントのエンドポイントが両方に使用されます。

認証

All API requests require authentication to identify the user making the request. Two authentication methods are supported: developer API tokens and External Applications (OAuth Client Credentials).

開発者アクセス トークンを取得するには次の手順に従います。

1. Automation Cloud から IXP にアクセスします。

2. [管理] ページに移動します。

3. [マイ アカウント] を選択します。

4. [ API トークン] で [ 再生成 ] ボタンを選択すると、アクセス トークンが生成されます。

   

注:

一度にアクティブにできる API トークンは 1 つだけです。 新しいトークンを生成すると、前のトークンは無効になります。

すべての API 呼び出しに、以下の HTTP ヘッダーを含める必要があります。 $REINFER_TOKEN は Communications Mining™ の API トークンです。

Authorization: Bearer $REINFER_TOKEN

の bash の例では、トークンが環境変数に保存されていることを前提としています。Python と Node の例では、選択した構成ソリューションを介して REINFER_TOKEN トークンがローカル変数に格納されていることを前提としています。

bash

curl -X GET 'https://<my_api_endpoint>/api/...' \
    -H "Authorization: Bearer $REINFER_TOKEN"

ノード

const request = require("request");

request.get(
  {
    url: "https://<my_api_endpoint>/api/...",
    headers: {
      Authorization: "Bearer " + process.env.REINFER_TOKEN,
    },
  },
  function (error, response, json) {
    // digest response
    console.log(JSON.stringify(json, null, 2));
  }
);

Python

import json
import os

import requests

response = requests.get(
    "https://<my_api_endpoint>/api/...",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

レスポンス

{
  "status": "ok"
}

Authentication with external applications

For automated or server-to-server integrations where a developer API token is not appropriate, you can authenticate using an External Application with the Client Credentials flow.

Step 1: Create an external application

An administrator must create a Confidential application and configure the required scopes based on which APIs you need to access.

Required scopes:

• PM.User
• PM.User.Read
• Ixp.ApiAccess

重要:

Save the App ID and App Secret immediately after creation, as you cannot retrieve the secret later.

For the complete instructions, check Managing External Applications.

Step 2: Assign application permissions

After creating the external application, you must assign it the appropriate permissions before it can access resources.

1. Navigate to the Manage Access page in IXP in your UiPath environment.
2. Search for your application by the name you gave it when you created it.
3. Assign the necessary roles to the application. The application will appear in the list just like regular users.
4. Save the role assignments.

For the complete permission assignment details, check Managing User and Group Roles.

Step 3: Authenticate using the client credentials flow

Use the Client Credentials grant type to obtain an access token.

Required parameters:

• grant_type=client_credentials
• client_id={app_id} - from Step 1
• client_secret={app_secret} - from Step 1
• scope - the scopes you configured in Step 1 (space-separated)

For the complete authentication details, check External Applications (OAuth).

Step 4: Use the access token

Once you have an access token, include it in the Authorization header for all API requests.

Authorization: Bearer {access_token}

Example request:

curl -X GET "https://cloud.uipath.com/{organizationName}/{tenantName}/reinfer_/api/v1/datasets" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/json"

注:

Replace {organizationName}, {tenantName}, and {access_token} with your actual values.

権限

各 API エンドポイントには、必要な権限が一覧表示されます。自分が持っている権限を表示するには、[管理] ページの [アクセス権を管理] タブに移動します。このタブには、自身がアクセス権を持つプロジェクトと、各プロジェクトで持つ権限が表示されます。

Error

従来の HTTP 応答コードを使用して、API 要求の成功または失敗を示します。一般に、 2xx 範囲のコードは成功を示し、 4xx 範囲のコードは指定された要求の結果としてのエラーを示し、 5xx 範囲のコードは Communications Mining の問題を示します。

そのエラーは、okではなく status 値 errorの本文と、エラーを説明するエラー メッセージも返すことを要求します。

bash

curl -X GET 'https://<my_api_endpoint>/api/v1/nonexistent_page' \
    -H "Authorization: Bearer $REINFER_TOKEN"

ノード

const request = require("request");

request.get(
  {
    url: "https://<my_api_endpoint>/api/v1/nonexistent_page",
    headers: {
      Authorization: "Bearer " + process.env.REINFER_TOKEN,
    },
  },
  function (error, response, json) {
    // digest response
    console.log(JSON.stringify(json, null, 2));
  }
);

Python

import json
import os

import requests

response = requests.get(
    "https://<my_api_endpoint>/api/v1/nonexistent_page",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

レスポンス

{
  "message": "404 Not Found",
  "status": "error"
}

注:

Communications Mining に到達する前に、ネットワークの問題が原因で要求が失敗する可能性があります。このような場合、表示される応答は、前述の Communications Mining のエラー応答とは異なります。

Performance timing

Server-Timing HTTP ヘッダーを使用して、API への要求が処理されるのにかかる時間を通知します。単一のメトリックとして totalが含まれています。これを使用して、プラットフォームがネットワーク リクエストの遅延なしでリクエストを処理するのにかかった時間を測定できます。

応答に表示されるヘッダーの例:

Server-Timing: total;dur=37.7

Server-Timing 値は常にミリ秒単位であるため、この場合、このヘッダー値を含む API リクエストが UiPath のプラットフォームで処理されるまでに 37.7 ミリ秒かかりました。