UiPath Friends Orchestrator ハンズオン勉強会 パート3 資料

こんにちは！UiPath Friendsコミュニティ運営メンバの @masatomix です。この記事は 2020/8/28(金)に開催予定の、UiPath Friends Orchestrator ハンズオン勉強会 - パート3 向けの資料です。

前回 のコンテンツを理解済みの方を対象にしています。

さて今回は、下記のハンズオンを行います。

• UiPath Orchestrator の機能概要(今回ご紹介分)
• キューの機能をもっと活用してみよう
• API を使ってOrchestratorのデータを取得してみよう

対象の方

• 会社で UiPath Orchestrator(以下OC)を導入するみたいなんだけど、ヒトに構築をお願いするにもひととおりはさわっておかなくちゃなー、って方。
• OCは導入済みだけど、キュー機能とかAPI機能とかOrchestratorならではの使い方を知りたいって方
• 前回のコンテンツを理解済みの方
• UiPath Love な方

などなどです。

前提事項

• 今回も完全にオンライン開催なので、ご自身のWindowsPCをご準備ください。
• PCへは、管理者権限のユーザでログインできるようにしてください。
• あらかじめ UiPath Studio Community 版をインストールしておいてください。
• 本資料は UiPath Studio Community 2020.4.3 で疎通確認していますが、近しいバージョンであれば問題ないと思います。
• ご自身が操作可能なUiPath Orchestratorをご準備いただき、UiPath StudioをそのOCに接続しておいてください。
  • 前々回のハンズオンで、Community版(2020/05現在は Community Cloud って呼ぶのかな)を準備するハンズオンがあります。
  • 実施すると Community Cloud 版の Orchestratorに接続済みのUiPath Studio環境を構築できます。
• UiPath Studio Enterprise 版をお使いの場合は、対応するEnterprise版のOCをご準備ください( Enterprise版についてはオンプレのOC 2019.10.17 に対して、 Studio Enterprise 2019.10.4でいちおう疎通確認してあります)。
• ハンズオン環境としてZoomをご用意ください (運営側で当日のZoomリンクを用意するため、参加者のアカウント登録は不要です)。
• Zoomの配信とご自身のStudio操作のため、モニタを複数ご用意することをおすすめします。
• API のハンズオンについては、Postman というツールを使います。サインアップやインストールが必要なので、あらかじめ実施しておくとスムースです(ハンズオンでも、その時間はとります)。

1. UiPath Orchestrator の機能概要(今回ご紹介分)

キューの機能(復習)

キュー(Queue)とは 「無制限に項目を保持できる収納機能です。」 とのこと(公式より)。処理したいデータをOC上のキューに投入することで、ワークフロー間でデータをやりとりする機構です。

前回も踏まえてキュー機能を整理すると

• 「データ投入」と「データ取得・処理」のワークフローを分けることができる
• 複数ロボットによる処理の並列化 ができる
• 繰り返し処理を RE Frameworkにお任せすることで、処理の記述がよりシンプルになる
• それぞれのデータの処理結果に応じた例外を投げることで「失敗で異常終了する」「失敗したけどリトライする」などを自動でやってもらうことができる(これも半分は RE Framework の機能)

といった感じです。今回はエラー処理についてもうすこし掘り下げてみようと思います。

キュー機構を用いた、エラー処理について

さて前回はデータの重複登録や複数ロボットによる処理の重複 の対処について説明をしましたが、今回はエラー処理について。

ワークフローで順番にデータを処理していると**「このデータは入力チェックエラーになったから、何度リトライしてもダメなエラー」** だったり 「たまたまタイムアウトしたけど、リトライしたらうまくいくかもというエラー」 などに遭遇しますが、キュー機構には、キューのデータに処理結果のステータスをセットするだけで「即失敗」とか「リトライさせる」とかを自動でやってくれる機能があります。

Orchestrator のキュー機構が管理する処理結果のステータスは「成功 / 失敗(ビジネス例外) / 失敗(アプリ例外) 」です。処理結果に応じて適切なステータスを設定するようにしてください。以下に、それぞれのステータスの意味をかきます。

• 失敗(ビジネス例外): 入力チェックでエラーなどいわゆる業務例外で、リトライしてもダメな失敗
• 失敗(アプリ例外): ときどき発生するエラーなどいわゆるシステム例外で、リトライしたらふつうに正常終了するかもしれない、という失敗
• 成功: 正常に終了

失敗(アプリ例外)となったデータは、キュー上は「リトライ」という状態になり、新たに同じデータがキューに投入されます。なので、だれかが再度データの処理を試みてくれます¹。リトライはキューの定義で規定したリトライ回数だけ、繰り返されます。

さてこのステータスの設定とリトライについてですが、じつはRE Frameworkが全部やってくれるので、キューを使うときは積極的に使っていきましょう。具体的には RE Framework をいれると、

• BusinessRuleException をスローしたら、「失敗(ビジネス例外)」 ステータスがセットされる
• BusinessRuleException 以外の例外をスローしたら**「失敗(アプリ例外)」**ステータスがセットされる
• 例外をスローしなければ 「成功」 ステータスがセットされる

を自動でやってくれます。便利ですね。

キューから順番にデータを取り出すのもRE Framework がやってくれるので、まとめると、開発者はワークフローを開発する際、

• RE Framework がとりだしてくれたデータにアクセスして業務処理を実行。
• 処理結果に応じて、上記の3パタンの処理を記述する

だけでオッケーです。

さいごに、どんな結果のときに、どの例外を発生させるかの指針を書いておきます。

	ビジネス例外	アプリケーション例外
どちらの例外を発生させるかの指針	入力チェックでエラーになるなど、リトライしても意味がない即失敗としたいエラー	たまたまタイムアウトしたとか、次は成功するかもしれないエラーのとき
スローする例外の型	BusinessRuleException	それ以外の例外
OCからのアラート通知	されない	される
キュー機能とRE Frameworkがやってくれること	キューのステータスを失敗にしてくれる (逆にいうとそれだけなので「ビジネスエラーが発生しました」など、担当者へメール通知などを実装する必要あり	キュー定義に規定された回数のリトライと、それでもダメならキューのステータスを失敗にしてくれる
ワークフロー自体のジョブのステータス	正常終了	正常終了

キュー機能についてのご紹介は以上です。あとでハンズオンで一緒にやってみましょう。

UiPath Orchestrator API について

つづいて、UiPath Orchestrator API です。API はHTTP(s)リクエストをなげて、レスポンスとしてOrchestrator 画面に表示されているような情報をJSONというデータ形式で受け取る仕組みです。

たとえば、

$ curl -G 'https://platform.uipath.com/kinooqmollho/kinoorgDefaean0252851/odata/Machines' \
-H 'X-UIPATH-TenantName: kinoorgDefaean0252851' \
-H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR...割愛'

とリクエストをなげると、下記のようなレスポンスが得られます。

{
    "@odata.context": "https://platform.uipath.com/kinooqmollho/kinoorgDefaean0252851/odata/$metadata#Machines/UiPath.Server.Configuration.OData.ExtendedMachineDto",
    "@odata.count": 5,
    "value": [
        {
            "@odata.type": "#UiPath.Server.Configuration.OData.ExtendedMachineDto",
            "LicenseKey": "bbf74601-xxxx",
            "Name": "WINDOWSESXI",
            "Description": "",
            "Type": "Standard",
            "Scope": "Default",
            "NonProductionSlots": 0,
            "UnattendedSlots": 1,
            "HeadlessSlots": 0,
            "TestAutomationSlots": 0,
            "Id": 32753,
            "RobotVersions": [
                {
                    "Count": 1,
                    "Version": "18.4.7.0"
                },
                {
                    "Count": 1,
                    "Version": "20.4.3.0"
                }
            ]
        },
        {
            "@odata.type": "#UiPath.Server.Configuration.OData.ExtendedMachineDto",
            "LicenseKey": "483f8011-xxxx",
            "Name": "WINDOWS",
            "Description": null,
            "Type": "Standard",
            "Scope": "Default",
            "NonProductionSlots": 0,
            "UnattendedSlots": 0,
            "HeadlessSlots": 0,
            "TestAutomationSlots": 0,
            "Id": 36369,
            "RobotVersions": [
                {
                    "Count": 2,
                    "Version": null
                }
            ]
        }
    ]
}

JSONのデータなので見にくいですが、戻り値のvalue の部分を表にするとこんな感じです。OC上のマシンの情報が取れていますね。

LicenseKey	Name	Description	Type	Scope	NonProductionSlots	UnattendedSlots	HeadlessSlots	TestAutomationSlots	Id
bbf74601-xxxx	WINDOWSESXI		Standard	Default	0	1	0	0	32753
483f8011-xxxx	WINDOWS		Standard	Default	0	0	0	0	36369

APIには上記のようにマシン、ロボ、パッケージ、プロセス、ジョブ、ライセンス、ログなどいわゆる画面に表示されるデータを取得する系のAPI だけでなく、ジョブを実行する、パッケージをアップロード・ダウンロードする、タスクをアサインする、などのいわゆるアクション系(？)のAPIもあります。

なので、Orchestrator のようなWEB画面をつくってみたり(実際にやってみました↓)、AWSなどで定期的にOC APIを呼び出してライセンスの使用状況をSlackに通知する、などの通知アプリを作り込んだりできます。

(プロセス一覧からジョブを実行してみたりしている)

今回のハンズオンでは、上記のような curl という黒い画面のツールではなく、HTTPリクエストを送信する便利ツールのPostmanを使ってみましょう。

ハンズオン環境の確認

前提にも書きましたが、以下ハンズオンを行うにあたって

• 操作できる UiPath Orchestrator (Community Cloud版でも、オンプレでも)をご用意ください。
• そのOCへ接続済みの、UiPath Studioをご用意ください。
  • 繰り返しとなりますが、前回の記事を実施することで「OC接続済みのUiPath Studio と OC」を準備することができます。
  • うまくいっていれば、タスクトレイのアイコンが青もしくは緑になっていると思います。

Community版 Studio の場合

Enterprise版 Studio の場合

2. キューの機能をもっと活用してみよう

OCのキュー機能をつかったエラー処理をやってみましょう。
実際に、キューにデータを投入するワークフローと、それらを処理するワークフローを実行してみます。流れは以下の通り。

• OC画面上で、キューを定義します。
• Studioでデータ投入用のプロジェクトをGitから取得し、実行します。
• Studioでデータ取得用のプロジェクトをGitから取得します。
• Studioからデータ取得用のワークフローを実行して、発生した例外によってどんな処理がされるかを確認します。

データ投入用のプロジェクトは**「メールサーバからメールを受信して、その情報をキューに投入」**しています。
メールサーバはこちらで準備してあるものをそのままお使いください。下記の通り数件、受信箱にメールが届いている状態にしてあります。

もう一方の、データ取得用のプロジェクトは**「キューから値を取り出して、発生する状況に応じていくつかの例外をスローする」**ようにしてあります。
上記内容をキューから取り出し、キューから取得した件名から「正常データ」「異常データ(リトライ不可)」「異常データ(リトライ可能)」を判定し、それぞれの例外をスローします。もちろん、実際利用するケースではココの業務ロジックは要件に応じて作り込んでください。

処理シーケンスの詳細はのちほど説明します。

OC画面上で、キューを定義します。

キューの定義は、前回と全く同じですので、前回の設定が残っている方は作業不要です。

OCへログインし、左メニューの「キュー」をクリック(「監視」ではなく「オートメーション」がわのキューです)

右肩のプラスボタンをクリック

下記の通り入力して「追加」をクリックします。

• 名前:「mailQueue」
• 一意の参照:「はい」
• 自動リトライ:「はい」
• 最大リトライ回数: 「1」

Queueの定義が作成できました。

「一意の参照」はキューへのデータ投入時に、同じデータを重複して投入しない機構でしたね。
「自動リトライ」と「最大リトライ回数」は、アプリ例外発生時に再実行をさせるか どうかで、一回だけ再実行するという設定です。

Studioでデータ投入用のプロジェクトをGitから取得し、実行します。

ココも実は、前回のハンズオンと全く同じワークフローですので、時間の都合で説明は省略するかもしれません。
「ただキューにデータを入れるワークフロー」とお考えいただければ結構です。

GitHub にソースコードをアップロード済みなので、コードはそこから取得してみます。GitHubから取得といっても手順どおりやるだけです。簡単です。

UiPath Studioを起動して「チーム」をクリック

「リポジトリを複製」 をクリック

リポジトリURLに https://github.com/masatomix/UiPath-OC-Hands-on2_PutQueue.git と入れて「開く」をクリックします。

前回のハンズオンを実施済みの方は、同じディレクトリにすでにファイルが存在して「開く」をクリックできないかもしれません。
その場合は別のディレクトリにチェックアウトするか、元のファイルをいちど削除してやり直すなど、適宜ご対応ください。
(もちろん元のファイルをGitのupdateコマンドで最新版にしてもOKです)

プロジェクトをダウンロードすることができました。プロジェクトは簡略化のため Attended Frameworkを使っています。

コードの説明は、前回とまったく同じなので割愛します。

さてキューへのデータ投入ワークフローを実行してみましょう。
上部リボンメニューの「実行」をクリックしてください。Main.xaml が実行されると思います。(「ファイルを実行」を選ぶとたぶん Process.xamlが実行されちゃうのでご注意)

なんだか、実行されているようです。

2021/03/09追記:
メールサーバはハンズオン用にこちらで用意したのですが、そろそろこのメールサーバは使えないようにしてしまいます。なので他のメールサーバ(Gmailですが)
に変更する手順を記事にしましたので、こちらを見ながら適宜設定を行ってください。
UiPath のメールアクティビティ用に Gmail を設定する

お手間をかけますがよろしくお願いします

さて、OC画面を開いてキューに投入されたデータをみてみましょう。画面をみると、残りの件数が「4件」になってるのがわかります。また、右の点々より「トランザクションを表示」を選ぶことで、4件の詳細を見ることも可能です。

キューへのデータ投入は、以上です。

Studioでデータ取得用のプロジェクトをGitから取得します。(メインパート)

**さて今回のメインパートです。**キューからデータを取得するプロジェクトを取得します。
Studioを起動して「チーム」をクリック

「リポジトリを複製」 をクリック

リポジトリURLに https://github.com/masatomix/UiPath-OC-Hands-on2_GetQueue.git と入れて「開く」をクリックします。

こちらも、前回のハンズオンを実施済みの方は、同じディレクトリにすでにファイルが存在して「開く」をクリックできないかもしれません。
その場合は別のディレクトリにチェックアウトするか、元のファイルをいちど削除してやり直すなど、適宜ご対応ください。
(もちろん元のファイルをGitのupdateコマンドで最新版にしてもOKです)

RE Frameworkを用いたプロジェクトをダウンロードすることができました。

コードの詳細

RE Framework は

• キューから一つデータを取り出して
• Process.xaml を呼び出す
• Process.xaml の実行時に
  • BusinessRuleException 以外の例外をスローしたらキューデータに**「失敗(アプリ例外)」**ステータスがセットされる
  • BusinessRuleException をスローしたら、キューデータに**「失敗(ビジネス例外)」** ステータスがセットされる
  • 例外をスローしなければ キューデータに**「成功」** ステータスがセットされる

というのを、キューからデータが取れるだけ、自動で繰り返してくれるフレームワークでした。
RE Frameworkは全体を理解するのは多少難しいかもしれませんが、上記を理解できていればとりあえず使うことはできると思います。

さて実際のロジックを記述する Process.xaml (からさらに呼ばれる ProcessInternal.xaml ) にサンプルを記述済みなので、開いてみてください。

メールの件名 Subject の文字列でSwitchして

• 件名が「異常データ」だったら

  • BusinessRuleExceptionをスローするので、キューデータのステータスが「失敗」となります。

• 件名が「タイムアウトするデータ」だったら

  • BusinessRuleException以外の例外をスローするので、アプリ例外と判定されてキューにはリトライのデータが再投入されます。ワークフローは再投入されたデータをふたたび取り出して実行してくれます。結果は同じで、また失敗となります²。キューの定義でリトライ回数を1回にしたので、再度失敗したのち、そのキューデータは「失敗」となります。

  ちなみに最初に投入されたキューデータのステータスは「リトライ済み」です。

• それ以外だったら

  • 正常に処理されるので、キューデータのステータスは「成功」になります。

としてあります。
参考: ちなみにRE Framework はザックリこんな感じ

もともとキューに投入されていた4件のデータは、ワークフローが動いた結果、下記のような状態になるはずです。

項番	ステータス	参照	例外	例外の理由	備考
5	失敗	<202008230703.07N73uE1083188..	ApplicationException	次は成功するかもしれないエラーです	項番1のリトライ分
4	成功	<202008230305.07N35AP9030097..
3	成功	<202008230305.07N35b22030275..
2	失敗	<202008230702.07N72Wp5082952..	BusinessRuleException	リトライ不可能な例外なので、即失敗	リトライされないで失敗
1	リトライ済み	<202008230703.07N73uE1083188..	ApplicationException	次は成功するかもしれないエラーです

Studioからデータ取得用のワークフローを実行して、発生した例外によってどんな処理がされるかを確認します。

さてデータを取得するワークフローを実行してみます。
上部リボンメニューの「実行」をクリックしてください。Main.xaml が実行されると思います。(「ファイルを実行」を選ぶとたぶん Process.xamlが実行されちゃうのでご注意)

キューにあるデータたちが、繰り返し処理されていますね！

おわったら、再度OC画面を開いてキューに投入されたデータをみてみましょう。「トランザクションを表示」を選ぶと、さきほど想定した結果とおなじようになっているかと思います。

キューの機構とRE Frameworkを用いることで、自分では「繰り返し処理」や「リトライ処理」を全くコーディングしなくてもOK、というのが分かったと思います。便利ですね。。

キューに関するハンズオンは以上になります。

3. API を使ってOrchestratorのデータを取得してみよう

つづいて、Postmanを用いた、Orchestrator APIのハンズオンです。流れは以下の通りです。

• インストーラのダウンロードと、サインアップ
• HelloWorld をやってみる
• UiPath Orchestrator APIに必要なアクセストークンを取得する
  • 認証情報などを変数として定義する
  • ほかにも、いくつか変数を定義する
• マシン一覧を取得してみる
• UiPath Orchestrator API のテンプレートを利用する

インストーラのダウンロードと、サインアップ

今回使用する Postman はこんなアプリケーションです。URLを指定して必要な条件を設定し「Send」をクリックすると、リクエストが飛んで実行結果が得られるようになっています。

さっそく、サインアップやインストールをやっていきましょう。まずは、https://www.postman.com へアクセス。

右上の「Sign Up」をクリック。

ご用意いただいたアドレスなど、必要な情報を入力して「Create free account」をクリック

また名前を聞かれるんですが、適当に。roleもなんでもよいと思います。「Continue」をクリック

Team はいったんナシで。「Continue Without a Team」をクリック

Desktop Agent についてはとりあえず 「Skip for now」をクリック。

サインアップ・サインインが完了したようですね。

サインインした状態で、再度 https://www.postman.com/ へアクセスすると、右上のアイコンが「Download」になってるのでクリックします。

環境に応じたファイルをダウンロードしてください。一般的には「Windows 64-bit」 が多いかと。

ダウンロードしたファイル (2020/08/26現在 Postman-win64-7.31.0-Setup.exe) をダブルクリックすると、下記の通りアプリケーションが起動します。
(2回目以降はスタートメニューから起動可能です)

右上の「Sign In instead」をクリック

先ほどと同じログイン情報を入力して「Sign in」をクリック

アプリケーションでトップページ表示されました！

HelloWorld をやってみる

ではさっそく使ってみます。HelloWorld的なモノとしてUiPathとは関係ないんですが、RESTのAPIでよくつかわれるお天気Webサービス（REST） を呼び出してみましょう。

URLは、http://weather.livedoor.com/forecast/webservice/json/v1?city=130010 です

2020/08/26追記:
まさかの2020/7末で、お天気Webサービスがサービス終了していました。
期待するJSONデータなどは得られないモノの、何らかのレスポンスが返っては来るので、いったんそのままにしておきます、、、。

curl だと

$ curl 'http://weather.livedoor.com/forecast/webservice/json/v1?city=130010'

こうです。

メイン部分の「+」ボタンをクリックして、「Request」を新規作成します。

HTTPリクエストを記述するための画面が表示されるので下記のように「http://weather.livedoor.com/forecast/webservice/json/v1?city=130010」と入れてみます。入れた時点でパラメタが解析されて「Query Params」にセットされたりしているのがステキですね。

さて「Send」をクリックします。

結果が表示されました！簡単ですね。

「Request」は保存しておくことができるので、「Save」をクリックします。

下記のようなダイアログが開きます。まず名前(Request name)を「130010の天気」とかにします。
どうも「Request」を保存するには「Collection」というフォルダ的なモノがないとダメなので「+ Create Collection」をクリック。

Collection名を「Test Folder」として、右のチェックをクリック。

「Save To Test Folder」をクリックすると、、

Test Folder というハコのなかに、保存されましたね！

保存した「Request」はいつでも再実行できるので、よく使うヤツなどは保存しておくとよいでしょう。また、これらはアカウントに紐付いて保存されるようなので、別のコンピュータでログインしても、同じモノが表示されるようになっています。

Hello World は以上です。

UiPath Orchestrator APIに必要なアクセストークンを取得する

いよいよ、UiPath Orchestrator のAPIリクエストを投げてみましょう。UiPath Orchestrator API は、

• Enterprise版 → OCにログインするユーザー名、パスワードでアクセストークンを取得する
• Community Cloud版 → OC画面上から取得できる ユーザー キー、クライアントIDを使ってアクセストークンを取得する

とやって認証をおこなったのち、各リクエストにその「アクセストークン」をつけることで、APIを呼び出すことができます。
今回はCommunity Cloud版について、ハンズオンしてみます。

前準備として、必要なデータを取得しておきます。
OC画面( https://cloud.uipath.com/ ) からご自身のOCへログインし、左メニューの「管理」をクリック

持っているテナントが表示されるので、テナント左の△アイコンをクリック >> 右にある雲のマークをクリックすると(むかしよりどんどんわかりにくくなってます)

下記の画面が表示されます。ユーザキー、クライアントID、アカウントの論理名、テナントの論理名、が確認できると思います。後で使うのでメモしておくか、画面を開いたままにしておきましょう。

さてさて、アクセストークンの取得APIの呼び出しは、curlだとこうなります( [Client Id] / [User Key] は画面上の「クライアント ID」/「ユーザー キー」の値に置き換えてください)。

$ curl -X POST https://account.uipath.com/oauth/token  \
-H 'Content-Type:application/json' \
--data '{"grant_type": "refresh_token", "client_id": "[Client Id]", "refresh_token": "[User Key]"}'

では Postman で。

メイン部分の「+」ボタンをクリックして、「Request」を新規作成します。

• Methodのプルダウンを「GET」から「POST」にして、URLを「https://account.uipath.com/oauth/token」と入力します
• パラメタは「Body」を選択して
  • 形式を「raw」
  • Text → JSON
• Bodyのデータは、下記の通り。

{
  "grant_type": "refresh_token",
  "client_id": "[Client Id]",   ← 画面から取得したモノで、手動で置き換える
  "refresh_token": "[User Key]"  ← 画面から取得したモノで、手動で置き換える
}

とします。

たとえばこんな感じってコトですね。

例

{
  "grant_type": "refresh_token",
  "client_id": "8DEv1Axxxxx", 
  "refresh_token": "jrmefJDvxxxxxx"
}

さて、実行です。
Sendで実行してみると、、、アクセストークンが取得できましたね！

UiPath Orchestrator APIを使うのに必要な、アクセストークンを取得できました。
このリクエストは「Save」して適宜名前をつけて保存しておきましょう。

認証情報などを変数として定義する

Body部は

{
  "grant_type": "refresh_token",
  "client_id": "8DEv1Axxxxx", 
  "refresh_token": "jrmefJDvxxxxxx"
}

などと実際の値が入ってると思いますが、ヒトによって異なる値なので、再利用のために変数化しておきます。

まずBody部に、{{clientId}} などとして変数を埋め込んで おきます。

変更後

{
  "grant_type": "refresh_token",
  "client_id": "{{clientId}}",
  "refresh_token": "{{userKey}}"
}

「Request」は下記のようになったはずです。リクエストとして送信される電文に、変数を埋め込むことができました。

埋め込んだ変数に実際の値を設定するために、Postmanのアプリ上で clientId,userKey という変数を定義します。
まずは右上の三本線のアイコン(？)をクリック。

Manage Environmentsというポップアップが上がったと思います。これは**変数たちの定義を入れておくハコ「Environments」**の管理画面です。変数たちを定義する場所って考えればOKです。
というわけで「Add」をクリック。

「Cloud」って名前の「Environment」をひとつ定義しました。そして「Add」をクリック。

保存できたようです。
つづいて、CloudってEnvironmentに先の変数たちを定義していきますので、「Cloud」をクリックして中に入ります。

下記の通り「clientId,userKey」と入力してください。
また変数ごとの「Initial value(初期値)」が記述可能なので、OC画面から取得したいつもの値を入力しておきます。「Current Value(現在値)」の方にも同じ値がセットされるはずです。セットされない場合は、明示的に初期値で現在値を上書きするために「Reset All」をクリックしてください。

最後に「Update」をクリック。

保存できたようなので上部「×」ボタンでポップアップを閉じます。

さて、変数にセットした値を再度確認したり、値を実際に使ったりするには、右上のEnvironmentsのプルダウンをデフォルトの「No Environment」から「Cloud」へ変更します。

選択されたEnvironment に定義された変数たちの値を確認するために、目玉のマークをクリックすると、、、

ポップアップで値を確認することができます。Current ValueにOC画面上の文字列が設定されていることが確認できましたね。
ちなみに、この画面の右肩の「Edit」から、さきほどの変数定義画面に遷移することもできます。

ではこのリクエストを実行してみましょう。
といっても「Send」ボタンを押すだけです。前回同様、値が取れたのではないかと思います。

以上で、変数を定義できるようになりましたね。

ほかにも、いくつか変数を定義する

そのほかのOC画面で取得した項目も含め「Cloud」のEnvironmentに以下の変数を定義していきます。

変数名	説明
clientId	OC画面の「クライアントID」
userKey	OC画面の「ユーザーキー」
tenantName	OC画面の「テナントの論理名」
url	https://platform.uipath.com/[accountName(の実際の値)]/[tenantName(の実際の値)] 例:https://platform.uipath.com/kinooqmollho/kinoorgDefaean0252851 など。
token	認証リクエストの戻り値のaccess_tokenの値

tenantName は開いておいたOC画面上の値を、さきほどと同様の方法(三本線アイコン >>「Cloud」を選択して... )で変数に定義してください。
url はAPIを投げる先のURLとして上記の値を設定してください。[xxの実際の値]となっている部分は変数でなく値そのものを入れてください。 また、末尾のkinoorgDefaean0252851 の部分は、OC画面にアクセスするさいのURL ではなく、テナント論理名なのでご注意ください。

APIのURLのprefixが、https://platform.uipath.com だったり https://cloud.uipath.com だったりするケースがあるようです(2020/08/27時点どちらでも取れるっぽい)。
https://cloud.uipath.com へ移行している印象なので、適宜URLを変えてみてください。

さいごに tokenです。先ほどの認証リクエストの戻り電文

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVxxx.eyJodHRwczovL3VpcGF0aC9lbxxxxx.B4u8jk4uK7Y39ug3jFlsGxyFnnKAfsMkNP3lEJdM57igJwm0DNE21yXXYjADt7wKeywHxxxx",
  "id_token": "-- 割愛 --",
  "scope": "openid profile email offline_access",
  "expires_in": 86400,
  "token_type": "Bearer"
}

のうち、access_token の値は今後のリクエストでなんども使用します。
なのでtokenという変数に上記のaccess_tokenの値: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVxxx.eyJodHRwcz...を設定してください。

以上で変数の定義はおしまいです。
画面上で変数を確認すると、こんな感じです。

準備はここまでです。つかれましたね。

マシン一覧を取得してみる

さていよいよAPIを使ってリクエストを投げてみます。
メイン部分の「+」ボタンをクリックして、「Request」を新規作成。

Postman にセットするパラメタ値は以下の通り。

まずはURL。
URLは「{{url}}/odata/Machines」とします。 {{url}} は「Cloud」Environment上にセットした値で置換されるのでした。またメソッドは「GET」で。

つづいて認証情報。
Authorizationタブ をクリックして、Typeプルダウンで「Bearer Token」を選択、右側のTokenに {{token}} と設定。認証リクエストで取得した値がココにセットされるって事ですね。

最後にテナント名です。
Headersタブをクリックして、Key:「X-UIPATH-TenantName」,Value:「{{tenantName}}」と設定。
ちなみに小さく hidden と書いてあるところをクリックすると、その他のHeader 情報も確認することができます。

以上で完了。
さっそくリクエストを送信してみましょう。「Send」をクリックすると

**マシンの一覧のJSONデータが取得できましたね！**JSONだとわかりにくいですが「"@odata.count": 5」なのでマシンが5台、valueの値がJSON配列になっていて、5台のマシンの情報( 例: "Name": "DESKTOP-6502OD6"など) が取得できていることが分かります。

以上で「認証リクエストを送信してトークンを取得して、そのトークンをつけてマシン一覧を取得する」ことができました。

このリクエストは「Save」して適宜名前をつけて保存しておきましょう。

UiPath Orchestrator API のテンプレートを利用する

ブラウザで、https://postman.uipath.rocks/ にアクセスしてみましょう。

なんだか難しい画面が表示されたと思いますが、誰か(UiPath社公式なのかな？情報見つからず) がUiPath Orchestrator APIを使うためのPostmanのテンプレートを公開してくれています。最後にそれを使ってみましょう。

右上の「Run in Postman」をクリックすると、下記のようなダイアログが表示されるので 「Postman for Windows」 を選択します。

左の「Collections」のところに、テンプレートがインポートされました。

インポートされたものたちは、今回ハンズオンで作成していた「Request」とおなじオブジェクトです。たとえば「Get Machines」を開いて、Sendをクリックして実行してみましょう。

先ほど自分たちで作ったものと同じ結果が得られたようですね。

ハンズオンでいろいろと変数を定義しましたが、それらはテンプレが参照している変数名にあわせて定義をしたので、特に設定変更をすることなくテンプレートを利用することができました。

テンプレートにはさまざまなOC APIが登録されているので、いろいろ使ってみてください。

また、公開されているテンプレートには

• 認証してtoken変数を自動で設定してくれる
• tenantName をurlの末尾から自動で取って設定してくれる

などなどがJavaScriptで記述されています。少し細かな説明を別記事に書いたので、気になる方はご参照ください。

時間がない方向け

お忙しい方や、ハンズオンが時間切れになっちゃう場合を想定して、とにかくAPIを呼び出すだけ出あれば、上記のハンズオンで出てきた以下の変数だけ定義をして、

変数名	説明
clientId	OC画面の「クライアントID」
userKey	OC画面の「ユーザーキー」
tenantName	OC画面の「テナントの論理名」
url	https://platform.uipath.com/[accountName(の実際の値)]/[tenantName(の実際の値)] 例:https://platform.uipath.com/kinooqmollho/kinoorgDefaean0252851 など。
token	認証リクエストの戻り値のaccess_tokenの値

UiPath Orchestrator API のPostmanのテンプレート をダウンロードし、各種APIを呼び出してみてください。

まとめ

• Orchestratorのキューの機能を学びました。
  • キューのステータス管理機構をつかうことによって、処理のリトライなどが可能であることが分かりました。
  • RE Frameworkを使うと繰り返し処理を書かなくても、フレームワークがキューからデータをとってきてくれることがわかりました。
  • 同様に、RE Frameworkをつかうと例外を正しく取り扱うことで、ステータス管理を自動出やってくれることが分かりました。
• Orchestrator API について、
  • 認証リクエストの戻り値のaccess_tokenを使うことで、UiPath Orchestrator APIを呼び出すことができることが分かりました
  • マシン一覧を取得するリクエスト投げるところまでやったので、で一通りPostmanをつかってUiPath Orchestrator APIを呼びだせるようになりました
  • access_tokenやURLなど、横断的につかう情報をEnvironment の変数として外出しできる事を学びました
  • UiPath Orchestrator API のPostmanテンプレートを使って、API呼び出しをおこないました。

Orchestratorを導入することで利用可能になる機能についてご紹介とハンズオンを行いましたが、いかがでしたでしょうか？

謝辞

今回の件でご協力いただいた UiPath Friendsの運営メンバーの方、またもちろん参加してくださった方々に感謝いたします。運営メンバーのかた、いつもコンテンツがギリギリとなり、リハすらできずゴメンナサイ。。

以上、おつかれさまでしたー。。。

関連リンク

• サンプルコード
  • キューにデータを投入するサンプルプロジェクト
  • キューからデータを取得するサンプルプロジェクト
• RE Frameworkとキュー操作を理解するための参考
  • ちなみにRE Framework はザックリこんな感じ
  • Orchestrator API のサンプルコード
• UiPath Orchestrator API のPostmanのテンプレート
• UiPath Orchestrator Community Edition へのサインアップからHelloWorldまで。(UiPath Friends 東京 Orchestratorハンズオン勉強会向け資料) 前々回記事
• UiPath Friends 東京 Orchestrator ハンズオン勉強会 パート2 資料 前回記事
• uipath-orchestrator-api-node Orchestrator API のJavaScript Wrapper。
• OrchestratorのAPI はほとんどのOC画面での操作をRESTのAPIで行うことが可能なので、やろうと思えば Orchestratorみたいなモノもつくれます。ということでAPIをつかったWEBアプリのサンプルを作ってみました。

• ソースはこちら。https://github.com/masatomix/uipath-orchestrator-api-node-samples/tree/develop

1. 同じワークフローが処理するかもしれません ↩

2. (ホントのタイムアウトが発生したケースなどはつぎは成功するかもしれないのですが) ↩