■Workspace ONE UEM API Explorerについて
今年初めて vExperts Advent Calendar に参加させていただきます。どうぞ宜しくお願い致します。
今回の記事のテーマは、「Workspace ONE UEM(以下UEM)の持つREST APIの動作確認をしてみること」です。
VMware製品の持つAPIの多くは、以下のページでどのようなものがあるかを確認することが可能です。
ただ、UEMのAPIについては上記ページに記載はなく、UEMホストそのものに同様のページが設けられています。具体的には各UEMホストの、以下のURLに準備されています。
- https://<UEMのFQDN>/api/help/#!/apis
※2020/9/25追記：確認する範囲では<UEMのFQDN>でもAPI Explorerにはアクセス可能ですが、多くのSaaS共有環境では、API のURLは普段管理コンソールとして利用するcnXXX.awmdm.comの先頭二文字のcnをasに入れ替えた値となります(API ExplorerのFQDNも本来はこちらになります)。
UAGなどでTunnelやContent Gatewayなどの構成要件としてAPIとの通信が必要な場合は、<UEMのFQDN>ではなく、asXXX.awmdm.comなどのような、API用URLをご確認の上、通信を許可してください。なお管理者権限にもよりますが、API用URLについてはSaaS共有環境であれば[グループと設定]＞[すべての設定]＞[システム]＞[高度な設定]＞[サイトURL]で確認可能です(2020/9/25時点)。
REST API用のURLの確認画面。
※画像はConsole Administrator権限で確認した際のもの
上記URLにアクセスすると、Workspace ONE UEM API Explorerが表示されます。
REST APIの動作確認というと、postmanなどのREST Clientをインストールしたり、FireFoxやChromeにREST Clientのプラグインを追加したりする方が多いかと思います。
UEMがバージョン8.xのころは私も上記の方法でREST APIの動作確認を行っていましたが、バージョン9.2ごろから、このWorkspace ONE UEM API ExplorerからREST APIの動作を確認することができるようになりました。
今回は一例として、「UEMに登録されているユーザーアカウントをREST APIで取得」したいと思います。
今回は、ハンズオンラボ環境を使用するので、以下のホストのREST APIにアクセスしています。
※アクセスしてページを表示するだけならいつでもできますが、実際にAPIを利用するには、ハンズオンラボコース（HOL-2051-09-UEM）の登録と開始が必要です。
- hol.awmdm.com
上記ページにアクセスすると、以下のような画面が表示されます。
 |
| このエントリを記述した2019年12月12日時点で筆者が確認する限り、 この画面はどのUEMホストにおいても日本語化されていないようです。 |
上記の画面から、画面左上のAPIsをクリックすると、APIを用途ごとに分類したページが表示されます。
今回はユーザをREST APIで取得するため、右上の検索欄にuserと入力します。
userと入力すると検索条件に合致するAPIがリストされていきます。
今回は、/users/searchというAPIを利用するので、画面をスクロールダウンして探し出し、API名をクリックします。
クリックすると、API検索画面の最上部が表示されます。この画面をスクロールダウンすると/users/searchのパラメータ入力画面があるのですが、いったんここでは[AUTHORIZE]ボタンをクリックします。
[AUTHORIZE]ボタンをクリックすると、UEMに対してREST APIでGETやPOSTを行う権限を持つユーザーのログイン情報や、使用しているUEMのテナント情報などを投入する画面がポップアップ表示されます。
 |
| オレンジ色の枠内で示したエリアで、必要な情報を入力します。 全部表示されない場合は、オレンジ枠内右側のスクロールバーを スクロールダウンし、適宜必要な項目を表示/入力します。 |
今回は、以下3つの情報を入力します。
- ユーザー認証情報(ユーザー名/パスワード)
- REST APIキー
- 組織グループID
まずはユーザー認証情報です。これは単純に、UEM管理コンソールの管理者ユーザー名とパスワードです。
 |
| usernameとpassword欄に入力し、 [Authorize]ボタンをクリックします。 |
次に、REST APIキーです。これは、UEM管理コンソール上にログイン後、グループと設定＞すべての設定＞システム＞高度な設定＞API＞REST APIで閲覧できます。デフォルト状態ではコピーすることができませんが、[オーバーライド]することでコピー可能になります。
 |
| 管理コンソールにログインして。。 |
 |
| [グループと設定]（画面左下）→[すべての設定]をクリック |
 |
| ポップアップ表示されたら、 [システム]→[高度な設定]→[API]→[REST API]と進み、 [オーバーライド]をクリック。 |
 |
| オーバーライド後、画面に表示されたAPIキーの中から、 アカウントタイプが「管理者」のAPIキーをコピー |
ここまで来たら、あとはAPIの画面に戻り、aw-tenant-code欄にAPIキーをペーストします。
 | |
| ユーザー名/パスワードを入力した後に[AUTHORIZE]用の ポップアップ画面が閉じるため、再度画面右上の [AUTHORIZE]ボタンをクリックして、 aw-tenant-code欄にAPIキーをペーストし、 ポップアップ画面内の[Authorize]ボタンをクリックします。 |
最後に組織グループIDです。これはUEM管理コンソールログイン後、画面左上のタブにマウスオーバーした際に表示される「グループID」です。
 |
| 画像は『■ HOL-1957-01-UEM(5)：組織グループってなんだ？ - その１ 』から。 ※今回使用する値とは異なります |
グループIDをコピーし(または控え)たら、先ほどと同様APIの画面に戻り、aw-groupid欄にペーストします。
 |
| 画面右上の[AUTHORIZE]ボタンをクリックして、 aw-groupid欄に組織グループIDをペーストし、 ポップアップ画面内の[Authorize]ボタンをクリックします。 |
それではテスト用に作成したユーザー情報を取得してみます。
認証情報等を入力した画面が閉じたら、画面をスクロールダウンし、/users/searchのクエリ入力画面にてfirstname欄にtestと入力します(※この環境では事前にtestというファーストネームを持つユーザーを3つ作成しています)。正常にAPIが動作すれば、3つのユーザーの情報を取得してくれるはずです。
クエリを入力したら、[Try it out!]をクリックし、リクエストを実行します。
実行すると、[Try it out!]ボタンの下に、CurlでこのREST APIをたたく場合のオプション付きの実行例が表示されます。UEMにアクセス可能なLinuxでこのコマンドを使用することでも、同様の結果が得られます。
そしてさらにスクロールダウンすると、レスポンスが出力されています。
今回はユーザー情報の取得を実施しましたが、ほかにも様々なAPIが用意されています。
普段からUEMを利用される方は、ご利用中のUEMコンソールのAPIをのぞいてみると、今の管理操作をちょっと楽にしてくれる、思わぬAPIを見つけられるかもしれませんね。
明日の vExperts Advent Calendar 2019 - Adventar は masotsuka さんです。
どうぞ宜しくお願い致します。