#FeatureBlog - 19.4 - ライブラリに SOAP / Swagger ベースの Web サービスを追加する

[mamina (Mamina Araki)]

#FeatureBlog - 19.4 - ライブラリに SOAP / Swagger ベースの Web サービスを追加する

このブログ記事は #FeatureBlog - 19.4 - SOAP and Swagger (based REST services for Library projects) を元に作成されており、日本のユーザー向けに修正と加筆を行っています。原文は こちら をご覧ください。

はじめに

SOAP または Swagger ベースの Web サービスと連携するワークフローを開発するときに、Studio 上でリクエストの構築に苦労した経験はありませんか？

UiPath 2019 ファスト トラックから、ライブラリ プロジェクトにサービスを追加できる機能が登場しました。これにより、SOAP または Swagger ベースの Web サービスと UiPath の連携がよりシンプルになりました。

本記事では、[新しいサービス (New Service)] 機能を使い、ライブラリにサービスを追加する方法を紹介します。また、ライブラリに追加されたサービスを使用し Orchestrator のプロセスを実行する例も、チュートリアル形式で解説します。

新規ライブラリを作成し、サービスを追加する

1. Studio を立ち上げ、スタートメニューから [新規プロジェクト (New Project)] > [ライブラリ (Library)] を選択します。[新しい空のライブラリ (New Blank Library)] ダイアログが表示されるので、[名前 (Name)] と [説明 (Description)] をそれぞれ入力してください。

   

2. 新規ライブラリを作成した後、Studio の [デザイン (Design)] タブの [新しいサービス (New Service)] を選びます。もしくは、[プロジェクト (Project)] パネルの [サービス (Services)] の上で右クリックし、[新しいサービス (New Service)] を選びます。

   

   

3. [サービスエディター (Service Editor)] が開くので、[ファイルまたはリンク (File Or Link)] フィールドに、SOAP/Swagger サービスが提供する WSDL ファイル/Swagger ファイルの URL を指定してください。サービス記述が WSDL または Swagger 形式であれば、どの URL でも指定することができます。今回の例では、Orchestrator API の Swagger URL を使用します。

   ※ご利用の Orchestrator API Swagger の URL がわからない場合は こちらのガイド を参考にしてください。Swagger ドキュメントの URL は、Swagger ページ上部から取得可能です。

   

4. [読み込み (Load)] ボタンをクリックします。読み込みには少々時間がかかります。

   

5. 読み込みが完了すると、指定したサービスの利用可能なエンドポイントがすべて表示されます。[名前空間 (Namespace)] は好きな名前空間に変えることもできます。今回は例として、[名前空間 (Namespace)]に既定の名前空間ではなく、OrchestratorAPI と入力しました。[保存 (Save)] ボタンをクリックし、[サービスエディター (Service Editor)] 画面を閉じます。

   

   新しいサービスが追加されると、次のように [プロジェクト (Project)] パネル上に新しいサービスが追加されたのがわかります。

   

ライブラリ アクティビティを作成する

次の情報を引数として取り、Orchestrator のプロセスを開始するアクティビティを作成します。

• Orchestrator ログイン ID
• Orchestrator ログイン パスワード
• フォルダー名
• プロセス名
• ロボット名

プロセスを開始するにあたって、上記の引数をそのままリクエストのパラメーターとして使用することはできません。以下のステップを踏んで、プロセスの開始に必要なパラメーターを取得する必要があります。

• セッション認証を行い、Bearer トークンを取得する
• フォルダー名から Folder Id を取得する
• ロボット名から Robot Id を取得する
• プロセス名から Release Key を取得する
• プロセスを開始する

上記のステップでは、次の 5 つの Orchestrator API エンドポイントを使用します。

• POST /api/Account/Authenticate
• GET /odata/Folders
• GET /odata/Robots
• GET /odata/Releases
• POST /odata/Jobs/UiPath.Server.Configuration.OData.StartJobs

※上記のエンドポイントにリクエストする際に認証ユーザーが必要な権限を持っていないと、リクエストが失敗します。エンドポイントごとに必要となる権限については Orchestrator ガイド をご参照ください。

それぞれのエンドポイントに対してライブラリ アクティビティを作成することにより、機能のモジュール化をすることができます。したがって大規模なプロジェクトの場合は、API 呼び出しごとに異なるワークフローを作成したほうが望ましいでしょう。しかし、今回はワークフローを簡略化するために、それぞれの API 呼び出しをする合計 5 つのシーケンスを 1 つのワークフロー ファイル内に作成します。

それでは、Studio に戻ってアクティビティの作成をします。

シーケンスの追加と引数の作成

1. 新規の [フローチャート (Flowchart)] を作成し、[名前 (Name)] に適切な名前を入力します。今回は例として StartProcess_SpecificRobot という名前にしました。ライブラリ プロジェクトを作成すると既定で生成される NewActivity.xaml ファイルは削除します。[プロジェクト (Project)] パネルは次のようになります。

   

2. API 呼び出しごとに [シーケンス (Sequence)] アクティビティを追加します。今回 5 つのエンドポイントに対しリクエストをするため、5 つの [シーケンス (Sequence)] アクティビティを追加します。それぞれアクティビティの [表示名 (Display Name)] は、画像内の例のようにわかりやすいものに変更します。アクティビティの追加後は次のようになります。

   

3. 次に、サービスの名前空間をワークフローに追加します。次のように [インポート (Imports)] パネルから名前空間 OrchestratorAPI の追加をします。

   

4. 必要な引数をすべて定義します。合計 7 つの引数を定義します。

   引数	方向	引数の型	説明
   TenantName	入力	String	Orchestrator テナント名
   Username	入力	String	Orchestrator ユーザー名
   Password	入力	SecureString	Orchestrator パスワード
   FolderName	入力	String	ロボットとプロセスが所属するフォルダー名
   ProcessName	入力	String	開始するプロセス名
   RobotName	入力	String	プロセスを実行するロボット名
   Status	出力	String	API 呼び出し結果のステータス

5. これら 7 つの引数を追加した後は、[引数 (Arguments)] パネルは次のようになります。

   

認証シーケンス

1. 最初に 認証 シーケンスから編集をします。[アクティビティ (Activities)] パネルから [Authenticate] アクティビティを検索します。

   

   [Authenticate] アクティビティを 認証 シーケンスに追加します。[Authenticate] アクティビティのプロパティは非常にたくさんありますが、今回着目するプロパティは [LoginModel] と [Response] の 2 つのみになります。この 2 つのプロパティに対し、適切な型を選んで変数を作る必要があります。フィールド上で Ctrl + K ショートカット キーを押し、変数を作成するのが一番手っ取り早い方法になります。

   

   [LoginModel] プロパティに対しては、OrchestratorAPI.LoginModel 型の AuthenticateLoginModel という名前の変数を作ります。下記スクリーンショットのように、[既定値 (Default)] に New OrchestratorAPI.LoginModel と入力し、変数の初期化を行ってください。一方、[Response] プロパティに対しては、OrchestratorAPI.AjaxResponse 型の AuthenticateResponse という名前の変数を作ります。AuthenticateResponse 変数は API のリクエスト結果を格納するための変数であるため、変数の初期化は不要です。

   

2. AuthenticateLoginModel 変数の 3 つのプロパティに対し値を代入していきます。Orchestrator API Swagger ページの POST /api/Account/Authenticate エンドポイントを参照すると、どのプロパティに、どのような型のデータを設定すべきかがわかります。

   

   2 つの [代入 (Assign To)] アクティビティを [Authenticate] アクティビティの前に追加し、それぞれ [左辺値 (To)] と [右辺値 (Value)] に、次のように値を代入します。

   左辺値 (To)	右辺値 (Value)
   AuthenticateLoginModel.TenancyName	TenantName
   AuthenticateLoginModel.UsernameOrEmailAddress	Username

3. 次に、パスワードの設定を行います。AuthenticateLoginModel.Password は String 型です。一方、引数 Password は SecureString 型であるため、代入前に String 型に変換する必要があります。 変換後の平文のパスワードを保持するための String 型変数を PlainPassword という名前で作成します。

   [代入 (Assign To)] アクティビティを追加し、[左辺値 (To)] と [右辺値 (Value)] に、次のように値を設定します。

   左辺値 (To)	右辺値 (Value)
   PlainPassword	New System.Net.NetworkCredential(String.Empty, Password).Password

   PlainPassword 変数に平文のパスワードを格納後、その PlainPassword 変数を AuthenticateLoginModel.Password に代入をします。

   左辺値 (To)	右辺値 (Value)
   AuthenticateLoginModel.Password	PlainPassword

4. 認証 シーケンスは次のようになります。

   

5. 最後に、[Authenticate] アクティビティが返す Bearer トークンを保持する String 型の変数を作成します。この変数に BearerToken という名前をつけます。Bearer トークンは他のシーケンスで使用する必要があるため、変数の [スコープ (Scope)] を StartProcess_SpecificRobot に変更します。

   

   BearerToken 変数には [Authenticate] アクティビティが返すレスポンスの Result プロパティ (Object 型) の値を代入します。BearerToken 変数は String 型であるため、代入するときに ToString メソッドを使い String 型に変換します。

   

   [左辺値 (To)] と [右辺値 (Value)] は次のようになります。

   左辺値 (To)	右辺値 (Value)
   BearerToken	AuthenticateResponse.Result.ToString

Folder Id の取得シーケンス

1. Folder Id を取得するシーケンスを作ります。[フォルダー (Folder)] とは UiPath 2019.10 LTS で追加された機能です。これまでの [組織単位 (OrganizationUnit)] と似た機能を提供し、ユーザーのアクセス コントロールやリソースを分離する役割があります。詳細は こちら のガイドをご参照ください。

2. [アクティビティ (Activities)] パネル上で [GetFolders] アクティビティを検索し、Folder Id の取得 シーケンスに追加します。さきほどの [Authenticate] アクティビティと同様に、[GetFolders] アクティビティにもたくさんのプロパティが存在しますが、[Response] と [Filter] と [BearerToken] の 3 つのプロパティに対してのみ設定をします。

3. [Response] プロパティ上で Ctrl + K ショートカット キーを押し、変数 FoldersResponse を作成します。[Filter] プロパティには、フォルダーをフィルタリングする際の条件式を代入します。条件式は次のようになります。

   "DisplayName eq '" + FolderName + "'"

4. [BearerToken] プロパティには作成済みの変数 BearerToken を代入します。

   [GetFolders] アクティビティの [プロパティ (Properties)] パネルは次のようになります。

   

5. [GetFolders] アクティビティのプロパティの設定が終わった後、[代入 (Assign To)] アクティビティを [GetFolders] アクティビティの後に追加します。[代入 (Assign To)] アクティビティの [右辺値 (Value)] に FoldersResponse.Value(0).Id を入力し、[左辺値 (To)] フィールド上で Ctrl + K ショートカット キーで新しい変数を作り、その変数の名前を FolderId にします。

   左辺値 (To)	右辺値 (Value)
   FolderId	FoldersResponse.Value(0).Id

   FolderId 変数は GenericValue 型で生成されるため、Nullable<Int64> 型に変更します。さらに、この変数は他のシーケンスでも使いたいので、[スコープ (Scope)] を StartProcess_SpecificRobot に変更します。

   [変数 (Variables)] パネルは次のようになります。

   

Robot Id の取得シーケンス

1. Robot Id を取得するシーケンスを作ります。

   [GetRobots] アクティビティを [アクティビティ (Activities)] パネルで検索し、Robot Id の取得 シーケンスに追加します。そして [GetRobots] アクティビティの [Response] プロパティ上で Ctrl + K ショートカット キーを押し、新たな変数 RobotsResponse を作成します。

   

2. さきほどの [GetFolders] アクティビティと同じように、ロボットも名前でフィルタリングしたいので、[Filter] プロパティに次の式を入力します。

   "Name eq '" + RobotName + "'"

3. 次に、どのフォルダーに所属するロボットなのかを指定する必要があります。[X_UIPATH_OrganizationUnitId] プロパティに作成済みの FolderId 変数を代入します。

4. 最後に [BearerToken] プロパティに BearerToken 変数を代入し、[GetRobots] アクティビティ プロパティの設定は終了となります。

   

5. Robot Id の取得 シーケンスに戻ります。[代入 (Assign To)] アクティビティを [GetRobots] アクティビティの後に追加します。[代入 (Assign To)] アクティビティの [左辺値 (To)] と [右辺値 (Value)] には次のように入力してください。RobotId 変数は新たに作成する必要があります。Nullable<Int64> 型にし、[スコープ (Scope)] を StartProcess_SpecificRobot に変更します。

   左辺値 (To)	右辺値 (Value)
   RobotId	RobotsResponse.Value(0).Id

   Robot Id の取得 シーケンスと [変数 (Variables)] パネルは次のようになります。

   

Release Key の取得シーケンス

1. Release Key の取得 シーケンスは、上述の Robot Id の取得 シーケンスの作成手順とほとんど変わりません。

   プロセスを取得するには [GetReleases] アクティビティを使用します。このアクティビティにも [Filter] プロパティが存在するので、次の式を入力し、プロセス名でフィルタリングを行います。

   "Name eq '" + ProcessName + "'"

2. Release Key を取得するために、[代入 (Assign To)] アクティビティを追加します。[左辺値 (To)] と [右辺値 (Value)] は次のように入力します。ReleaseKey 変数を String 型で作成し、[スコープ (Scope)] の変更をすることも忘れないでください。

   左辺値 (To)	右辺値 (Value)
   ReleaseKey	ReleasesResponse.Value(0).Key.ToString

   

ジョブの開始シーケンス

1. それでは最後のシーケンス、ジョブの開始 の編集作業に入りましょう。このシーケンスでは、これまでのステップで取得した BearerToken、FolderId、RobotId そして ReleaseKey を組み合わせて API リクエストを構築します。

2. [StartJobs] アクティビティを [アクティビティ (Activities)] パネルから “ジョブの開始” シーケンス上にドラッグ アンド ドロップします。プロパティ [StartJobParameters] 上で、Ctrl + K ショートカット キーを押し、OrchestratorAPI.StartJobParameters 型の新しい変数 StartJobParams を作成します。[変数 (Variables)] パネルで StartJobParams 変数の [既定値 (Default)] に New OrchestratorAPI.StartJobParameters と入力します。

3. [Response] プロパティに対しても新しい変数 StartJobResponse を作成し、代入をします。この変数の型は OrchestratorAPI.ODataResponseOfListOfJobDto になります。

   

4. [X_UIPATH_OrganizationUnitId] と [BearerToken] プロパティには、これまでと同様に FolderId 変数と BearerToken 変数をそれぞれ代入します。

5. 次に、StartJobParams 変数の設定を行います。[Authenticate] アクティビティにパラメーターを設定したときと同じように、どのプロパティに値を設定しないといけないかを Orchestrator API Swagger ページで確認します。POST /odata/Jobs/UiPath.Server.Configuration.OData.StartJobs エンドポイントの [Data Type] は次のように定義されていることがわかります。

   

6. まず、StartJobParameters 型のオブジェクトの StartInfo プロパティを初期化します。[代入 (Assign To)] アクティビティを[StartJobs] アクティビティより前に追加してください。

   

   左辺値 (To)	右辺値 (Value)
   StartJobParams.StartInfo	New OrchestratorAPI.StartProcessDto

7. StartInfo プロパティの初期化後、3 つの [代入 (Assign To)] アクティビティを追加します。さらに、StartInfo の RobotIds、ReleaseKey、Strategy プロパティに値を代入します。

   次のスクリーンショットのようになります。

   

   上から順に [左辺値 (To)] と [右辺値 (Value)] を、次のように設定します。今回、特定のロボットの Id を指定してジョブを開始するため、StartJobParams.StartInfo.Strategy に OrchestratorAPI.StartProcessDtoStrategy.Specific を代入しています。

   左辺値 (To)	右辺値 (Value)
   StartJobParams.StartInfo.RobotIds	{CLng(RobotId)}
   StartJobParams.StartInfo.ReleaseKey	ReleaseKey
   StartJobParams.StartInfo.Strategy	OrchestratorAPI.StartProcessDtoStrategy.Specific

8. これで [StartJob] アクティビティを実行するために必要な準備が整いました。リクエストの結果を出力引数の Status に格納する必要があるので、[StartJob] アクティビティの後に [代入 (Assign To)] アクティビティを追加し、[左辺値 (To)] と [右辺値 (Value)] に次のように入力をします。

   

   左辺値 (To)	右辺値 (Value)
   Status	StartJobResponse.Value(0).State.ToString

テスト実行

1. プロセスを開始するリクエストの結果を出力コンソール上で確認するため、[一行を書き込み (Write Line)] アクティビティを追加します。

   

2. [引数 (Arguments)] パネル上で [入力 (In)] 引数すべてに値を入力し、ワークフローを実行します (Ctrl + F6 ショートカット キー)。Password 引数に対しては、テスト目的なので次の式を代入します。第 2 引数には Orchestrator にログインするときに使うパスワードを平文で設定してください。

   New System.Net.NetworkCredential(String.Empty, "Orchestrator平文パスワード").SecurePassword

   実行が成功すると、出力コンソール上に [Pending] という文字列が表示されます。

   

   [Pending] と表示されていますが、これはプロセスを実行するロボットが、Orchestrator にハートビートを送る次のタイミングで、プロセスが開始されるためです。

   テストが終わったら、[引数 (Arguments)] パネルで設定した既定値を必ず削除するようにしてください。

サンプル ライブラリ プロジェクト

サンプルは こちら からダウンロードできます。

Orchestrator API の Swagger URL として、ダミーの URL: https://platform.uipath.com:443/swagger/docs/V2 が設定されています。こちらはご自分の Orchestrator API の Swagger URL に変更する必要があります。

また、こちらのサンプル ライブラリ プロジェクトをダウンロードまたはクローンし、Studio から開くと次のようにアクティビティが正常に読み込めないというエラーが表示されます。これは、Studio でこのプロジェクトを初めて開くときに発生する問題です。

エラーは以下の手順で解決できます。

1. [プロジェクト (Project)] パネルの [サービス (Services)] 内に表示される、OrchestratorAPI を右クリックし、表示されたコンテキスト メニューから [サービスを修復 (Repair Service)] を選ぶことで解決できます。ただし、今回は Orchestrator API の Swagger URL も変更する必要があるので、コンテキストメニューから [サービスを編集 (Edit Service)] を選びます。

   

2. [サービスエディター (Service Editor)] が表示されるので、[ファイルまたはリンク (File or Link)] テキストフィールド内の URL をご利用中の Orchestrator の Swagger URL と書き換えてください。書き換え後は [読み込み (Load)] ボタンを押します。

   

3. エンドポイントの読み込みが終わると、[名前空間 (Namespace)] が既定の名前空間で上書きされてしまうので、OrchestratorAPI と入力し直します。最後に [保存 (Save)] ボタンを押します。

おわりに

読者の皆さんはこのライブラリをパブリッシュし、別のワークフローからライブラリ アクティビティを呼び出すところまでチャレンジしてみてください

参考情報

UiPath Studio ガイド - ライブラリへのウェブサービスの読み込み

UiPath Japan の GitHub アカウント

[YingXiuShi (Eisyu)]

お世話になります。

上記手順通りに作成しましたが、 [Authenticate]アクティビティで下記エラーになっています。
＝＝＝＝＝
Authenticate: Could not deserialize the response body.

Status: 200
Response:
<!doctype html>.uipathPlatform::-webk
＝＝＝＝＝＝＝

設定内容：
Swagger URL ：https://cloud.uipath.com/[Account Logical Name]/[Tenant Name]/swagger/docs/V2

[Authenticate] アクティビティEndPoint:“https://cloud.uipath.com/[Account Logical Name]/api/Account/Authenticate/”

ステータスが200なので承認自体は通ったと思いますが、「認証：応答本文を逆シリアル化できませんでした。」のメッセージの解決方法が分かりません。
設定が間違ってたでしょうか。

ご存知でしたらご教授願います。

[qbrandon (Quentin Brandon)]

/api/Account/Authenticateは「deprecated」となりましたので、OAuthをご利用いただきたいと思います。

こちらをご確認ください：

About authorizing external applications