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 つのテナントのエンドポイントが両方に使用されます。

認証

すべての API 要求では、要求を行うユーザーを識別するための認証が必要です。開発者 API トークンと外部アプリケーション (OAuth クライアント資格情報) の 2 つの認証方法がサポートされています。

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

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"
}

外部アプリケーションによる認証

開発者 API トークンが適切ではない自動連携またはサーバー間連携の場合は、外部アプリケーションを使用してクライアント資格情報フローで認証できます。

手順 1: 外部アプリケーションを作成する

管理者は 機密アプリケーション を作成し、アクセスする必要がある API に基づいて必要なスコープを設定する必要があります。

必要なスコープ:

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

重要:

アプリ ID とアプリ シークレットは後で取得できないため、作成後すぐに保存してください。

詳しい手順については、「 外部アプリケーションを管理する」をご覧ください。

手順 2: アプリケーションのアクセス許可を割り当てる

外部アプリケーションを作成したら、そのアプリケーションがリソースにアクセスする前に、適切な権限をそのアプリケーションに割り当てる必要があります。

1. UiPath 環境で IXP の [ アクセス権を管理 ] ページに移動します。
2. 作成時に付けた名前でアプリケーションを検索します。
3. アプリケーションに必要なロールを割り当てます。アプリケーションは、通常のユーザーと同じようにリストに表示されます。
4. ロールの割り当てを保存します。

権限の割り当てについて詳しくは、「 ユーザーとグループのロールを管理する」をご覧ください。

手順 3: クライアント資格情報フローを使用して認証する

[クライアント資格情報] の付与の種類を使用して、アクセス トークンを取得します。

必須パラメーター:

• grant_type=client_credentials
• client_id={app_id} - 手順 1 から
• client_secret={app_secret} - 手順 1 から
• scope - 手順 1 で設定したスコープ (スペース区切り)

認証について詳しくは、「 外部アプリケーション (OAuth)」をご覧ください。

手順 4: アクセス トークンを使用する

アクセス トークンを取得したら、すべての API 要求の Authorization ヘッダーに含めます。

Authorization: Bearer {access_token}

要求の例:

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

注:

[ {organizationName}]、[ {tenantName}]、[ {access_token} ] を実際の値に置き換えます。

権限

各 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 のエラー応答とは異なります。

パフォーマンスのタイミング

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

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

Server-Timing: total;dur=37.7

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