PowershellでMicrosoft Graph APIを使う方法について

こんにちは。

本日は、Microsoft Graph APIの使い方についてご紹介いたします。

（１）事前準備　～初めてのGraph API～

Microsoft Graph API（旧Office 365 Unified API）によって、Azure AD、Intune、Excel など、様々なプラットフォームから、1 つのパス（URI）を使ってデータにアクセスをすることができるようになりました。従来の Office 365 API を使用する場合は、Office Graph REST API、Outlook REST API、OneDrive REST API など、複数のエンドポイントを呼び出すことがありましたが、Microsoft Graph API で単一のエンドポイントから幅広くクラウド リソースをご利用いただけます。様々なエンドポイントをまとめる API になっていますので、リソースごとのアクセス トークンの取り直しが不要であり、しかも、リソースに対するアクセス許可をより細かくコントロールすることも可能です。

早速、本機能の使用方法についてご紹介していきます。

まずは Azure で Microsoft Graph API を使用するアプリを登録する必要があります。Azure AD の認証も必要となりますので、管理者として PowerShell を実行し、「Install-Module AzureAD」か「Install-Module AzureADPreview」を実行しモジュールをインストールしてください。Powershell v4.0 が必要最小限ですので、PowerShell のバージョンもご確認ください。

アプリを登録する際は、テナントの管理者アカウントで実行するか、Azureメニューでの「ユーザーとグループ」＞「ユーザー設定」の「ユーザーはアプリケーションを登録できる」という設定を有効にする必要があります。

Azure Portal にサインインし、次の作業を行ってください。

１）Azure メニューで、「Azure Active Directory」＞「アプリの登録」を選択します。

２）「新しいアプリケーションを登録」をクリックし、「作成」ブレードでアプリケーション情報を指定します。「アプリケーションの種類」と「リダイレクトURI」は目的によって異なりますので、詳しくはAzure ADの認証シナリオをご覧ください。このブログ記事では Azure AD Authentication Library（ADAL）を使用しますので、「アプリケーションの種類」は「ネイティブ」に、「リダイレクトURI」は「urn:ietf:wg:oauth:2.0:oob」に設定します。

３）アプリケーションを作成したら、アプリケーションのブレードが開きます。「アプリケーションID」は PowerShell スクリプトで利用しますので、メモしておきます。

４）「設定」＞「必要なアクセス許可」を選択します。

５）「追加」＞「APIアクセスの追加」＞「APIを選択します」を選択します。

６）「Microsoft Graph」＞「選択」を選択したら、「アクセスの有効化」のブレードが開き、アクセス許可一覧が表示されます。

７）アプリに必要な最小限のアクセス許可を選択して保存します。PowerShell スクリプトごとに必要なアクセス許可を後述します。Microsoft Graph API のアクセス許可の詳細についてはMicrosoft Graphのアクセス許可のリファレンスをご覧ください。

８）テナントのすべてのアカウントにアプリを使用するアクセス許可を付与したい場合は、「アクセス許可の付与」をクリックし、プロンプトに同意します。

以上の作業を完了したら Microsoft Graph API を使うアプリが利用できます。

次はこのアプリに接続し、Microsoft Graph API を使用する Powershell スクリプトを紹介いたします。

＊Intune 機能を使用しますので、一般ユーザーのアカウントではスクリプトを実行できません。全体管理者、もしくは制限付きの「Intuneサービス管理者」になる必要があります。ユーザーを制限付き管理者に設定するためには、管理者として「ユーザーとグループ」＞「すべてのユーザー」を選択し、リストから一人のユーザーを選択し、「ディレクトリロール」から制限付き管理者の種類を保存します。

ロール割り当ての詳細についてはAzure Active Directoryでの管理者ロールの割り当てをご覧ください。

（２）デバイス一覧の取得

上記の準備ができたら、Intune に登録されたデバイス一覧を取得するスクリプトを実行してみましょう。

まず、こちらのスクリプトをダウンロードします。91  行の clientID という変数に別のアプリケーション ID が入力してあります。clientID の値を先ほど登録したアプリのアプリケーション ID と入れ替えることで、アクセス許可をコントロールできるようになります。

デバイス一覧を取得するには、次の Microsoft Graph のアクセス許可が必要となります：

Read Microsoft Intune Devices (DeviceManagementManagedDevices.Read.All)

Microsoft Graph API の次の URI が使用されます：

１）https://graph.microsoft.com/beta/managedDevices
―　すべてのデバイスの情報を取得します。

２）https://graph.microsoft.com/beta/managedDevices/{deviceID}
―　ユーザー ID を取得するために一台のデバイスの情報を抽出します。

Windows Azure Active Directory API から次のアクセス許可も必要となります：

Access the directory as the signed-in user (Directory.AccessAsUser.All)

Windows Azure Active Directory API の次の URI が使用されます：

１）https://graph.microsoft.com/v1.0/users/{userID}
―　ユーザーIDでデバイスの持ち主を検索し名前を取得します。

アプリケーションのブレードの「設定」＞「必要なアクセス許可」＞「Microsoft Graph」＞「アクセスの有効化」の一覧からアクセス許可を承認できます。委任されたアクセス許可を変更しても「アクセス許可の付与」のプロンプトに改めて同意しないと許可が他のユーザーに付与されない場合もありますのでご注意ください。

＊Microsoft Graph API の機能一覧と URI の応答の詳細についてはをGraphエクスプローラーを気軽にお試しください。呼び出しの応答プレビューが見られますので、API を試したい時には便利です。

実際にダウンロードしたスクリプトを、PowerShell から実行することで、デバイスの一覧が取得可能です。以下のようなデバイス情報が多数出力されます。

なお、スクリプトを実行する際は資格情報を入力します。なお、現在、資格情報を入力せずに Microsoft Graph API の Intune 機能を使用することはできませんので、ご了承ください。