uipath-orchestrator-api-node
UiPath Orchestrator のAPI を、Node.jsから呼び出すライブラリです。
Table of Contents
Installation
$ npm install uipath-orchestrator-api-node
Quick Examples
Get a list of Robots
ロボット一覧を取得してみます。
const api = new OrchestratorApi(config)
// まずは認証
await api.authenticate()
// ロボットを取得する
const robots: any[] = await api.robot.findAll()
for (const robot of robots) {
console.log(robot)
}
実行結果
{
LicenseKey: null,
MachineName: 'PBPC0124',
MachineId: 4,
Name: 'PBPC0124_kino',
Username: 'xx\\kino',
ExternalName: null,
Description: null,
Version: '19.10.2.0',
Type: 'Development',
HostingType: 'Standard',
ProvisionType: 'Manual',
Password: null,
CredentialStoreId: null,
UserId: null,
CredentialType: null,
RobotEnvironments: 'Main',
IsExternalLicensed: false,
Id: 2,
ExecutionSettings: null }
{
...
このように、Orchestrator上の情報をAPI経由で取得することができます。
Search for Robots
検索条件を指定することで、条件に合致するリソースを検索することもできます。
const api = new OrchestratorApi(config)
await api.authenticate()
// ロボットを取得する
const machinename = 'PBPC0124'
const userName = 'xx\\kino'
const robots: any[] = await api.robot.findAll({
$filter: `MachineName eq '${machinename}' and Username eq '${userName}'`,
})
console.log(robots)
実行結果
[
{
LicenseKey: null,
MachineName: 'PBPC0124',
MachineId: 4,
Name: 'PBPC0124_kino',
Username: 'xx\\kino',
ExternalName: null,
Description: null,
Version: '19.10.2.0',
Type: 'Development',
HostingType: 'Standard',
ProvisionType: 'Manual',
Password: null,
CredentialStoreId: null,
UserId: null,
CredentialType: null,
RobotEnvironments: 'Main',
IsExternalLicensed: false,
Id: 2,
ExecutionSettings: null
}
]
「`MachineName eq '${machinename}' and Username eq '${userName}'`」
などとRobotの
プロパティ名とその値を指定することで、条件に一致するRobotを検索することができました。
条件指定は $filter
以外にも $top
や $select
などいくつかありますが、その仕様は API リクエストの構築 のサイトに詳しく書いてあります。
Documents
こちら に、サンプルとともにドキュメントを整理しています。
Development status
対応状況(2020/08/08時点)
各APIへの対応状況です。専用のメソッドを用意しているモノに「〇」をつけています。用意していない場合も汎用のメソッドを呼び出す事で、基本的にどのAPIも呼び出すことが可能だと思います。 専用メソッドの実装は気まぐれでやってるので、割と歯抜けでスイマセン。。
No. | リソース | 検索 (findAll) |
検索 (find) |
作成 (create) |
更新 (update) |
削除 (delete) |
一括更新 (upload) |
その他 | 備考 |
---|---|---|---|---|---|---|---|---|---|
1 | license | 〇 | |||||||
2 | machine | 〇 | 〇 | 〇 | 〇 | 〇 | 〇 | ||
3 | robot | 〇 | 〇 | 〇 | 〇 | 〇 | 〇 | ||
4 | user | 〇 | 〇 | 〇 | 〇 | 〇 | 〇 | 名前で検索(findByUserName) | |
5 | process | 〇 | Packageの検索(findPackage) Packageの削除(deletePackage) Packageのアップロード(uploadPackage) Packageのダウンロード(downloadPackage) |
||||||
6 | release | 〇 | プロセス画面上の「名前」で検索(findByProcessKey) | ||||||
7 | job | 〇 | 〇 | ジョブの開始/終了(StartJobs/StopJob) | |||||
8 | schedule | 〇 | |||||||
9 | log | 〇 | 条件で検索(findByFilter) | ||||||
10 | auditlog | 〇 | 条件で検索(findByFilter) | ||||||
11 | queueDefinition | 〇 | 〇 | 〇 | 〇 | 〇 | 名前で検索(findByName) | ||
12 | queueItem | 〇 | 〇 | 〇 | 〇 | 削除は論理削除 | |||
13 | queueOperation | TransactionのスタートでqueueItemを取得(getQueueAndStartTransaction) Transactionのステータス変更(setTransactionResult) |
|||||||
14 | setting | 〇 | 〇 | 〇 | 〇(update) | キーで検索(findByKey) ファイルからデータ作成(readSettingsFromFile) データをExcel出力(save2Excel) |
|||
15 | asset | 〇 | 〇 | 〇 | 〇 | 〇 | 〇 | Robot毎Asset更新(uploadPerRobot) Robot毎Asset検索(findAllEx) |
|
16 | environment | 〇 | 〇 | 〇 | 〇 | 〇 | |||
17 | role | 〇 | 〇 | 〇 | 〇 | 〇 | |||
18 | folder | 〇 | 〇 | 〇 | 〇 | 〇 | 名前で検索(findByDisplayName) ユーザ割当(assignUsers/removeUser) フォルダを参照可能なユーザ検索(getUsers) ユーザが参照可能なフォルダ検索(getFolders) フォルダ一括削除(removeFolders) |
||
19 | tenants | 〇 | 〇 | 〇 | 〇 | 〇 | |||
20 | hostLicense | 〇 | 〇 | 〇 | 〇 | 〇 | |||
21 | util | 一括ダウンロード(excelDownload) ExcelデータPrint(excel2Console) |
|||||||
22 | 汎用 | 〇 | 〇 | 〇 | 〇 | 〇 | getArray getData postData putData deleteData |
また、
を追加しました。
Preferences
さて本ライブラリを使用するには、接続するUiPath Orchestratorの情報など、環境設定が必要です。
UiPath Orchestrator がEnterprise版の場合は、テナント名、OCへログインするユーザ名とパスワードなどを下記のように:
$ cat config/local.json
{
"userinfo": {
"tenancyName": "default",
"usernameOrEmailAddress": "admin",
"password": "xxxxxx"
},
"serverinfo": {
"servername": "https://www.example.com/"
}
}
UiPath Orchestrator がCommunity版の場合は、Community版OC画面から取得できる情報を下記のように:
$ cat config/local.json
{
"serverinfo": {
"servername": "https://platform.uipath.com/[AccountLogicalName]/[ServiceName]",
"refresh_token": "[User Key]",
"tenant_logical_name": "[Tenant Logical Name]",
"client_id": "[Client Id]]"
}
}
参考: UiPath Orchestrator Community Edition のAPIを呼び出す件と、カスタムアクティビティをつくってみた
もしくは、Enterprise/Community にかかわらず、APIをワークフローから呼び出すつまり「Orchestrator への HTTP 要求」アクティビティと同等にしたい場合は、下記の設定画面から取得できる情報を用いて
以下のように設定します。
{
"robotInfo": {
"machineKey": "4eccxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx[マシンキー]",
"machineName": "[マシン名]",
"userName": "xx\\xxxx[Windowsアカウント]"
},
"serverinfo": {
"servername": "https://www.example.com/"
}
}
上記のような設定ファイルを環境に応じて作成してください。
Usage
How to use in TypeScript
TypeScriptから利用する方法です。 最終的に、ディレクトリ構成はこんな感じになります。
$ tree
.
├── src
│ └── index.ts
├── config
│ └── local.json
├── package.json
└── tsconfig.json
$
それぞれのファイルはたとえば以下のようにします。
$ cat src/index.ts
import config from 'config'
import OrchestratorApi from 'uipath-orchestrator-api-node'
async function main() {
const api = new OrchestratorApi(config)
// まずは認証
await api.authenticate()
// ロボットを取得する
const robots: any[] = await api.robot.findAll()
for (const robot of robots) {
console.log(robot)
}
// ライセンスを取得する
const license: any = await api.license.find()
console.log(license)
}
if (!module.parent) {
main()
}
$ cat package.json
{
"name": "api_use_ts",
"version": "1.0.0",
"description": "",
"main": "dist/index.js",
"scripts": {
"tsc": "tsc",
"start": "node ."
},
"license": "ISC",
"devDependencies": {
"@types/config": "0.0.36",
"@types/node": "^13.7.0",
"npm-run-all": "^4.1.5",
"typescript": "^3.7.5"
},
"dependencies": {
"config": "^3.2.5",
"uipath-orchestrator-api-node": "latest"
}
}
$ cat tsconfig.json
{
"compilerOptions": {
"target": "ES2019",
"module": "commonjs",
"sourceMap": true,
"outDir": "./dist",
"strict": true,
"esModuleInterop": true,
"forceConsistentCasingInFileNames": true
},
"include": [
"src/**/*"
],
}
実行してみます。
$ npm i
$ npx tsc
$ node dist/index.js
How to use in JavaScript
JavaScriptから利用する方法です。 最終的に、ディレクトリ構成はこんな感じになります。
$ tree
.
├── config
│ └── local.json
├── index.js
└── package.json
$
それぞれのファイルは以下のようにします。
$ cat index.js
const config = require('config')
const { OrchestratorApi } = require('uipath-orchestrator-api-node')
const oc = new OrchestratorApi(config)
const main = async () => {
const token = await oc.authenticate()
const robots = await oc.robot.findAll()
for (const robot of robots) {
console.log(robot)
}
}
if (!module.parent) {
main()
}
$ cat package.json
{
"name": "api_use",
"version": "1.0.3",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "",
"license": "ISC",
"dependencies": {
"uipath-orchestrator-api-node": "latest",
"config": "^3.2.5"
}
}
実行してみます。
$ npm i
$ node index.js
How to customize with configuration file
ちなみに設定ファイルは Own Coding で、
const api2 = new OrchestratorApi({
userinfo: {
tenancyName: 'default',
usernameOrEmailAddress: 'aaa',
password: 'bbb',
},
serverinfo: {
servername: 'https://platform.uipath.com/',
},
})
などとしてもOKですし、
NODE_CONFIG='{"userinfo":{"tenancyName":...}' node dist/index.js
などと実行時の環境変数として渡してあげてもOKです。
ライブラリのログ出力
本ライブラリは Bunyan を用いてコンソールにログを出力しています。
出力レベルはERRORレベル以上のため、詳細にログを見たい場合はlocal.json
に
"serverinfo": {
"servername": "https://www.example.com/"
},
// ココより下を追記 (下記は、debug以上を出力する設定)
"logging": [
{ "name": "main", "level": "debug" },
{ "name": "httpLogger", "level": "debug" }
]
// main/httpLogger は内部で使用しているLoggerの名前
など設定して、適宜表示を制御してください。
source and npm repository
ソースコードやnpmのリポジトリです。
- https://github.com/masatomix/uipath-orchestrator-api-node
- https://www.npmjs.com/package/uipath-orchestrator-api-node
Revision history
改訂履歴
- 0.8.2 tokenモードでauthenticate したときにエラー処理を追加した。
- 0.8.1 Tokenを直接渡されたときのFlag isToken を追加
- 0.8.0 Interfaceファイルの場所変更、getRuntimeLicenses、getNamedUserLicenses などのDto名変更など
- 0.7.9 ライセンスの利用状況を取得するメソッド
license.getRuntimeLicenses
,license.getNamedUserLicenses
を追加 - 0.7.8 Excel出力時に直接ファイルでなく、バイナリデータを取得するメソッド
save2ExcelBlob
を追加 - 0.7.7 configに Tokenを書けるように機能追加。Content-Typeを
application/x-www-form-urlencoded
でなくapplication/json
に集約。configにuserinfoが存在しない場合、organizationUnit情報をとろうとして異常終了していたのを修正。 - 0.7.6 Excelファイルの入出力を別のライブラリとして切り出したので、それをdependするように変更
- 0.7.5 Excel出力で、Windows認証されたユーザTypeも出力するよう処理を追加。
- 0.7.4 いくつかの機能追加
- OrganizationUnitIdを切り替える機能を追加(
api.organizationUnitId=2
など)。 -
api.util.excelDownload
は、操作アカウントが参照可能なフォルダの情報を出力するように変更。 -
api.machine.findAll
は通常ライセンスキーが入らないが、Excel出力時は入れるように処理追加。 - ユーザ・フォルダ関連情報の出力については、TypeがUserであるすべてのユーザ・フォルダ関連を出力するよう変更
- OrganizationUnitIdを切り替える機能を追加(
- 0.7.3 ExcelDownloadにフォルダを追加
- 0.7.2 strictSSLの設定、効いてなかったのを修正
- 0.7.1 Folderサービス追加,POSTで204が返ってくるとエラーになっていたのを修正
- 0.7.0
- uploadの戻り値変更
Promise<any>
->Promise<any[]>
- Robot の
findByRobotName(name: string)
の戻り値を変更any
->Promise<any>
- save2Excelの戻り値を変更
Promise<void>
->Promise<string>
(フルパス) - ライブラリ操作機能を追加
- setting に
getWebSettings
メソッドを追加。 - utilのダウンロード対象に libraryを追加
- Testケースのエラーログ出力を微調整
- uploadの戻り値変更
- 0.6.6 自己署名証明書などのサーバだと、リクエスト時に証明書検証エラーになるため、設定ファイルに回避するパラメタを記載可能にした(参考)。あと多少のリファクタリングと、ドキュメント整備。
- 0.6.5 util に excel 一括ダウンロード機能(hostテナント向け)メソッドを追加。またExcelがない環境むけにExcelファイルをConsoleへダンプする機能を追加。
- 0.6.4 ITenantCrudService,IHostLicenseCrudService,IEnvironmentCrudService,を追加。
- 0.6.3 Jobサービスに、Relese/Robot列を加えた findAllEx メソッドを追加。OrchestratorApi をexportしないとjsから利用できなかった( require('xxx').default ってやらないとダメ) ので、exportを追加
- 0.6.2 ダウンロードメソッド
api.util.excelDownload('./')
を追加。Machine/Robot/User/Asset のテンプレートにREADMEシートを追加 - 0.6.1 Assetの微調整。またDocument追加
- 0.6.0 Logライブラリ(log4js)が、Webと相性がわるいぽく、ライブラリを Bunyan へ変更。Assetの操作を追加。
- 0.5.0 Roleテスト実装(かなりテストレベル)。Excelテンプレを修正(Excel書き出しを自前実装にしたのでエラーになるカラムがなくなったため)。ファイルがindex.tsのみだったのをサービス毎に分割。Upload機能暫定追加(Robot/User/Machine)
- 0.4.5 各種APIにsave2ExcelというメソッドでExcelダウンロードできる機能を追加。まだダンプレベルで項目の精査中、レベル。対象は、machine,robot,release,process,job,user,queueDefinitions,setting,log,auditlog
- 0.4.4 Orchestratorの環境設定操作のAPI 追加。設定情報をExcelファイルでダウンロードする機能も。
- 0.4.3 Organization Unit に対応。configのuserinfoに、「"organizationUnit": 1」 などと記述出来るようにした。
- 0.4.2 Excel形式のログダウンロード機能追加(xlsx-populate-wrapper 追加)、AuditLog機能追加。ダウンロードサンプルを追加。構成をリファクタリング、Networkがエラーを返すときはステータスコードなども返す。(割とテストレベルかも、、)。
- 0.3.9 実行ログのダウンロード機能を追加。またそのlog機能についてドキュメントを整備。
- 0.3.8 queueDefinition/queue,queueOperation についてドキュメントを整備。あとコードのフォーマット(lint)。ロジックは変更なしです。
- 0.3.7 nupkg関連のアップロード・ダウンロード機能を追加。各種機能のドキュメントを追加
- 0.3.6 ドキュメントの整理のみ。
- 0.3.5 release追加、jobの開始・停止を追加。Statのサンプルを追加
- 0.3.4 ODataをそのまま返すオプションを追加。UserのCRUD追加。
- 0.3.3 Robot/Machine のCRUD作成完了。テストコードも追加。Loggerの設定を見なおし。設定ファイルに外だし。
- 0.3.2 認証ナシプロキシを設定できるように。電文を見たいときなどデバッグ時にご活用ください
- 0.3.1 Queue/Transactionを操作するAPIに対応。
- 0.3.0 QueueItemのCRUDを追加(もともとqueueって名前だったけどqueueItemに変更しました)。QueueDefinitionのCRUDを追加
- 0.2.5 findAllもOptionalな引数を追加(GETのパラメタとして)。ActionsでUTするように整理
- 0.2.3 user はCRUD作成完了、UnitTest追加( jest )、API に、汎用的なメソッドを追加。requestライブラリはformでなげると application/x-www-form-urlencoded になるのでjsonに変更
- 0.2.0 Id指定でのロボットの取得、プロセス一覧の取得、対象オブジェクトごとにメソッドを整理、Enterprise/Community版 両対応
- 0.1.0 初版作成
Contributing
Contributions, issues and feature requests are welcome!
Feel free to check issues page.
Show your support
Give a
License
Copyright © 2020 Masatomi KINO.
This project is Apache--2.0 licensed.
This README was generated by readme-md-generator