2019年12月12日木曜日

■Workspace ONE UEM API Explorerについて

この投稿は、vExperts Advent Calendar 2019 - Adventar 12日目の記事です。

今年初めて vExperts Advent Calendar に参加させていただきます。どうぞ宜しくお願い致します。

今回の記事のテーマは、「Workspace ONE UEM(以下UEM)の持つREST APIの動作確認をしてみること」です。

VMware製品の持つAPIの多くは、以下のページでどのようなものがあるかを確認することが可能です。


ただ、UEMのAPIについては上記ページに記載はなく、UEMホストそのものに同様のページが設けられています。具体的には各UEMホストの、以下のURLに準備されています。

  • https://<UEMのFQDN>/api/help/#!/apis

上記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つの情報を入力します。
  1. ユーザー認証情報(ユーザー名/パスワード)
  2. REST APIキー
  3. 組織グループ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):組織グループってなんだ? - その1 』から。
※今回使用する値とは異なります

グループ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 - Adventarmasotsuka さんです。
どうぞ宜しくお願い致します。