みなさま、ごきげんよう。永瀬です。

今回は、Control Room (CR) の API 呼び出しです。またしても前後編で2回にわたってお届けします。

前編では、Postman というツールを紹介しながら、CR の API を呼び出して「デバイスをリセット」する具体的な手順を見ていきます。

8月上旬のクラウド版 CR アップグレードで Bot Agent が自動的にアップグレードされず、キューにジョブが溜まり続けて Bot が実行できなくなる現象を踏んでしまった方もいらっしゃるのではないでしょうか。
その問題の解消手順に含まれていた、API でデバイスをリセットしてジョブをクリアするステップを確認していきます。

次回の後編では、Postman の便利な使い方や Unattended Bot Runner としての実行を API 経由でキックする手順、また、Bot 内から REST API を呼び出す手順も簡単に紹介します。

なお、以下の AA 社の KB 記事を読んで、そのまま作業ができてしまう方は、今回の記事の内容は理解されていますので、また次回にお会いしましょう。

https://apeople.automationanywhere.com/s/article/Deployed-bots-stuck-as-Queued-on-device-with-message-as-waiting-for-user-and-or-device
Deployed bots stuck as "Queued" on device with message as "waiting for user and/or device"
（※閲覧には A-People へのログインが必要です）

　

※本記事は Automation Anywhere A360.21 (Build 9664) 時点での情報です。

※2021年3月15日に「Automation Anywhere Enterprise A2019」は「Automation Anywhere Automation 360」にブランド名が変更されています。

※「A-People > knowledge」は Automation Anywhere 社とパートナー契約を結んでいるユーザーのみ参照可能となります。

　

□目次

１．REST API について

２．Postman について

３．REST API 呼び出しの具体例

　　３a．Authentication API

　　３b．Devices Reset API

　

それでは、さっそく見ていきましょう。

　

---

　

１．REST API について

REST API は、ざっくりいうと HTTP リクエストで API (Application Programing Interface) を呼び出す仕組みで、RESTful API とか Web API とかとも呼ばれます。Web サービスに対して、URL を指定して HTTP パケットを送信することで、API を呼び出すことができます。

きちんとした説明は、以下の URL のようなネット上の情報を参照してください。

https://www.redhat.com/ja/topics/api/what-is-a-rest-api
REST API とは（Red Hat）

https://e-words.jp/w/RESTful_API.html
RESTful API 【REST API】（e-Words）

　

---

　

２．Postman について

Postman は API Client といわれるアプリケーションです。Visual Studio Code など、使い慣れた API Client がある方は、この章はとばしてください。次章で紹介する具体的な API 呼び出しの手順は、お使いの API Client を使用して実施してください。

「API Client ってなに？」とか「やっぱり Postman が好き！」という方は、Postman をインストールしていきましょう。Postman は無償で使用できます。以下の URL から「The Postman app」をダウンロードしてください。Windows 版、Linux 版、Mac 版の各種が用意されていますが、この後の手順は Windows 版の前提で進めていきます。

https://www.postman.com/downloads/
Download Postman

　

ダウンロードしたインストーラーを実行してください。Postman app はユーザープロファイル内（C:\Users\<UserName>\AppData\Local\Postman）にインストールされますので、インストールに管理者権限は不要です。UAC による権限昇格はありません。

インストールが完了すると、「サイン イン」を求める画面になります。ユーザーアカウントを作成しログインして使用することもできますし、アカウントを作成せずログインしないでそのまま使用することもできます。ログインしない場合は、下部の薄くなった文字の「Skip and go to the app」のリンクをクリックして、ホーム画面から進むことができます。

　

Postman には便利な機能がいろいろありますが、今回は API を呼び出すための API Client 機能をメインに触れます。Postman のチュートリアルは充実していますので、その他の機能にご興味のある向きは、公式ドキュメントを読みながら、是非各自で掘り下げていただければと思います。

https://learning.postman.com/
Postman Learning Center

　

---

　

３．API 呼び出しの具体例

それでは、いよいよデバイスをリセットする API を実際に呼び出していきましょう。

手順としては、まず CR にログインして認証トークンを取得しておいて、操作したい API （今回はデバイスのリセット）を呼び出します。

　

　　３a．Authentication API

デバイスをリセットする API を呼び出す前準備として、CR にログインしてユーザー認証を受け、トークンを取得する必要があります。ブラウザーで CR への設定変更をする際に、まずは CR にログインする必要があるのと同じです。

API でユーザー認証をするためには、「POST: /v1/authentication」を呼び出します。パラメーターはリクエストの Body 部として json 形式で渡します。

API でのユーザー認証は、１）ユーザー名とパスワードでログインする方法と、２）ユーザー名と API キーを使ってログインする方法の、二通りあります。パスワードを使用する方法は Postman に直接パスワードを保存する必要があるため、同じ保存するにしても意味のない文字列の羅列になる API キーを使用するほうがより安全といわれています。今回は ２）API キーを使ってログインしていきます。

まず、API キーを生成します。API キーの生成には CR での権限が必要です。「API キーの生成」権限を付与するロールを作成し、ユーザーに付与してください。

・新規にロールを作成する。
・「API キーを生成」の権限をユーザーに付与する。

　

ユーザーに「API キーを生成」の権限を付与したら、権限を付与したユーザーで CR に再ログインし、API キーを生成します。

・左下のユーザー名を展開して「マイ設定」のリンクをクリックして、「マイ設定」画面を表示する。
・右上の「API キーを生成」ボタンを押下します。
・古いキーが無効になる警告が出ますが、「はい」を選択します。
・API キーが生成されるので、「コピー」ボタンでクリップボードにコピーし、メモ帳などに貼り付けておきます。
　一度生成した API キーは、もう一度生成するまで有効なままです。

　

　

　

　

ようやく Postman の出番です。POST メソッドで「/v1/authentication」にアクセスします。

・メインウィンドウで「＋」ボタンを押下して新しいタブを追加します。
・デフォルトで「GET」になっているメソッドをドロップダウンリストから
　「POST」に変更し、CR の URL と API の URL を指定します。
　例えば「https://xxxxxxxx.my.automationanywhere.digital/v1/authentication」のように
「<Base CR URL> + /v1/authentication」なります。

　

　

ユーザー名と API キーをパラメーターとして渡します。

・「Body」を選択し、「raw」を選択します。
・右端の矢印から「JSON」を選択します。
・以下の json を貼り付けます。
　＜ユーザー名＞と＜API キーの値＞を自分の環境の値に置き換えてください。

{
"username": "＜ユーザー名＞",
"apiKey": "＜API キーの値＞"
}

　

準備ができたら、リクエストを送信して API を呼び出してみましょう。

・「Send」ボタン押下でリクエストを送信します。
・「Status: 200 OK」と表示されて、「"token":」とそれに続く文字の羅列が表示されたら、
　API によるユーザー認証は成功です。

　

【TIPS】
「Status: 200 OK」にならない場合、ユーザー名や API キーの文字列の中に「\」バックスラッシュ（円記号）が含まれていないか確認してください。「\」が含まれている場合は、エスケープシーケンスの「\」を一つ追加してエスケープしてあげてください。（「\」は「\\」に置き換える）

　

API によるユーザー認証の詳細については、Automation Anywhere 社の公式ドキュメントを参照してください。

https://docs.automationanywhere.com/bundle/enterprise-v2019/page/enterprise-cloud/topics/control-room/control-room-api/cloud-authenticate-apikey.html
Authenticate with username and apiKey API

https://docs.automationanywhere.com/bundle/enterprise-v2019/page/enterprise-cloud/topics/control-room/control-room-api/cloud-control-room-apikey-role.html
Create and assign API key generation role

https://docs.automationanywhere.com/bundle/enterprise-v2019/page/enterprise-cloud/topics/control-room/control-room-api/cloud-authenticate-password.html
Authenticate with username and password API

　

　　３b．Devices Reset API

いよいよ本題の「デバイスのリセット」を行います。

API でデバイスをリセットするためには、「POST: /v2/devices/reset」を呼び出します。パラメーターはリクエストの Body 部として json 形式で渡します。

・メインウィンドウで「＋」ボタンを押下して新しいタブを追加します。
・デフォルトで「GET」になっているメソッドをドロップダウンリストから
　「POST」に変更し、CR の URL と API の URL を指定します。
　例えば「https://xxxxxxxx.my.automationanywhere.digital/v2/devices/reset」のように
「<Base CR URL> + /v2/devices/reset」なります。

　

先ほど取得したトークンをヘッダーに設定します。

・「Header」を選択します。
・「KEY」列に「X-Authorization」と指定し、「VALUE」列にトークンの値を指定します。
　先ほど取得したトークンの値に置き換えてください。両端のダブルクォーテーションは不要です。

　

【TIPS】
API キーは次回生成しなおすまで有効ですが、トークンは 20 分で無効になります。
「Status: 401 Unauthorized」で「Your session expired」となったら、もう一度「/v1/authentication」を呼び出して、トークンを取得しなおしてください。

　

CR で、リセットしたい対象のデバイス ID の値を確認します。
この記事の冒頭に紹介した AA 社の KB 記事に記載の方法とは異なりますが、こちらのほうがわかりやすいかと思い、紹介します。

・CR で［デバイス］ビューから、目的のデバイスの詳細ページを開いた時に、URL に含まれる数字がデバイス ID です。
　下図ではこのデバイスのデバイス ID は「503」になります。

　

リセットしたい対象のデバイス ID をパラメーターとして渡します。

・「Body」を選択し、「raw」を選択します。
・右端の矢印から「JSON」を選択します。
・以下の json を貼り付けます。
　＜デバイス ID＞を自分の環境の値に置き換えてください。数値なのでダブルクォーテーションは不要です。

{
"deviceIds": {
"ids": [
＜デバイス ID＞
]
}
}

　

「デバイスのリセット」API は、上図のように呼び出しに成功すると「Status: 204 No Content」が返ってきます。指定したデバイス ID がすでに CR 側で存在しない場合でも、API 呼び出し自体は成功して「Status: 204」が返ってくることにご注意ください。

　

デバイスのリセットに成功すると、CR で［アクティビティ］－［進行中］ビューに溜まっていたキューのジョブが消えて、次のジョブが正常に実行できる状態になります。

　

なお、現在のところ「POST: /v2/devices/reset」API の公式ドキュメントは公開されていません。swagger もしばらく更新されておらず、情報は冒頭の KB 記事のみで公開されている状況です。
　

---

　

今回はここまで。API によるデバイスのリセットを皆さん自身で実施いただく際の一助になれば幸いです。
次回は Postman の便利な使い方や、Bot の実行（いわゆる RunAsUser API）を紹介する予定です。

また次回まで、みなさまごきげんよう。