他のアプリケーションからAutomation AnywhereをREST API経由で制御できる仕組み「Automation Anywhere Control Room API」は、Control Room上にSwagger UIが実装されており、仕様を見たり実際にAPIコールを行ってみることができます。
Swagger UIではAPIコールの際のパラメータをWeb上で設定することができるため、コードを書かなくても気軽にREST APIを呼べるのが特徴です。
- Swaggerの概要をまとめてみた。 by @gcyata さん
Swagger UI の使い方
フリートライアルとCommunity Editionでは、以下のURLでAPIの実装を閲覧できます。
- フリートライアル: https://trial.cloud.automationanywhere.digital/swagger/
- Community Edition: https://community.cloud.automationanywhere.digital/swagger/
Swagger UIで以下のように一覧が表示されます。
「Authentication API」をクリックすると、詳細がHTMLページとして表示されます。
使いたいHTTPメソッドを選択してTry It out!
HTMLで記載されたページには、利用できるHTTPメソッド(get, post, put, delete等)一覧が表示されます。利用したいものをクリックして展開します。
HTMLメソッドには「Parameters」セクションと「Responses」セクションがあります。Parametersでは、HTMLメソッドに引き渡すパラメータをJSON形式で指定します。それに対してどのような返り値になるかをエラーコード毎に記載しているのがResponsesです。
Parametersセクションの「Try It Out」ボタンを押すと、パラメータの編集ができるようになります。
パラメータを編集してExecuteする
パラメータ編集後、「Execute」ボタンを押すと、実際にREST APIコールを実行できます。結果はResponsesセクションに表示されます。
本来はプログラミングコードの中からREST APIコールをしないといけないのですが、このように、WebブラウザベースのUI操作だけでコールができてしまうのはとても簡単で、APIのテストをするのにはとても適しています。
課題: Responseが「TypeError: Failed to fetch」となる...
さて、ここまでは前置きで、ここからが本題です。
たとえば、Authentication APIで、最初にユーザー認証を行う「/authentication」をコールしてみるとします。
"username"と"password"のペアを指定してコールすることができますので、「Try It Out」ボタンを押し、bodyのテキストボックスでapiKeyは消してusernameとpasswordに適切な文字列を指定して「Execute」ボタンを押してみると...Server responseに表示されるのは、Code=「Undocumented」、Details=「TypeError: Failed to fetch」(取得に失敗) というエラーでした。
これは、つまり想定していないエラーということになります。
curlでAPIコールしてみると...
これだけだと手掛かりがないので、curlという、コマンドラインからREST APIを呼ぶことができるツールを使って呼んでみましょう。Swagger UIでは、Executeすると、ResponsesのセクションにAPIコールと同等のcurlコマンドを表示してくれます。これをコピペしてそのまま実行すればよいわけです。
ちなみに、curlコマンドは元々Linuxのコマンドですが、Windows 10でもApril 2018 Updateから標準コマンドとなっており、特に追加インストールなく実行できます。もしこの要件を満たしていないOSの場合は、ダウンロードしてインストールしてください。
さて、コマンドプロンプトを開いて、Swagger UIに表示されていたcurlコマンドをそのままコピペして実行してみます。
C:\Users\Public>curl -X POST "http://trial.cloud.automationanywhere.digital/v1/authentication" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"username\": \"(User Name)\", \"password\": \"(Password)\"}"
すると、以下が表示されます。
<html>
<head><title>301 Moved Permanently</title></head>
<body bgcolor="white">
<center><h1>301 Moved Permanently</h1></center>
</body>
</html>
HTMLページとして出力されていますが、つまり301 Moved PermanentlyというHTTPエラーコードが返ってきていることがわかりました。Swagger UIの中では301は未定義でしたので、Undocumentedとなったのですね。
原因は...
このエラーコード301ですが、リダイレクト済みであることを表すエラーなのですが、いろいろネットを検索して調べていると、URLのSSL対応のためにHTTPをHTTPSにリダイレクトしていると起こるであろうことが想像できました。そうです。つまり、HTTPSでなくHTTPでAPIコールを行っていたのが原因だったのです。
よく見ると、Swagger UIの冒頭の方に、Schemeを選ぶドロップダウンがあり、HTTPかHTTPS化を選ぶようになっていました。これをHTTPSに直して実行すると、正しく実行できました。また、curlコマンドもよく見ると、やはり引数のURLがHTTPになっていたので、HTTPSに直すと正常に実行できました。
これは、トライアルでもCommunity Editionでもそうですが、インターネット上にホストされるクラウド版では、軒並みいまはHTTPSでホストされているために、HTTPSでAPIコールをしないとこのエラーが発生します。
...ということで、原因がわかってしまえば何のことはないのですが、このエラーでしばらく原因がわからずハマってしまったので、メモしておきます。