Microsoft Graph PowerShell SDK の試し方

Microsoft Graph を使用する方法として、Microsoft Graph PowerShell SDK を使用する方法があります。もともと SDK を使用しなくても PowerShell なら比較的容易に Microsoft Graph をはじめとした REST API を使用できますが、なるべく自分でコードを書きたくない場合は Microsoft Graph PowerShell SDK を使用するというのも選択肢になります。

なお Microsoft Graph PowerShell SDK はすでに GA していますが、ところどころ実装が不安定なものがあるので注意が必要です。また、Microsoft Graph 全体を操作できるようにしているため、Microsoft Graph PowerShell SDK をインストールすると大量のコマンドが使えるようになります。リソースなどの単位で PowerShell Module も分けられているため、PowerShell Module も大量にインストールされます。多くのシナリオにおいて、これらのコマンドのほとんどは使われることはありません。そのため、本当に Microsoft Graph PowerShell Module を使用することが適切なのか、もしくは (OAuth で MSAL を使用したとしても残りの部分は) PowerShell の標準機能だけで実装することが適切なのか、検討する必要があります。

なおこの記事の内容は Microsoft Graph PowerShell SDK (Microsoft.Graph PowerShell module) v1.0.1 で動作確認をしています。このバージョンは Windows PowerShell で使用するとリクエストのクエリ文字列の内容に問題が生じるので、PowerShell は Windows PowerShell ではなく PowerShell 7 (v7.0.3) を使用して動作確認をしています。

Microsoft Graph PowerShell SDK のインストール

以下のページに記載されています。

Install the Microsoft Graph PowerShell SDK
https://docs.microsoft.com/en-us/graph/powershell/installation

ユーザー権限で Microsoft Graph PowerShell SDK を試す

  1. 以下のようにコマンドを実行します。今回はユーザー情報とメールを取得するので以下のような Scope を指定してコマンドを実行します。
Connect-Graph -Scopes "User.Read","Mail.Read"
  1. コンソールに出力された内容に従って code を使用して認証を行います。
  2. 認証が終わるとコンソールに「Welcome To Microsoft Graph!」と出力されます。
  3. 以下のコマンドを実行すると、現在の認証情報を確認できます。
Get-MgContext
  1. 以下のようにコマンドを実行します。/me 相当の情報が取得できます。実際に戻り値を利用するには変数に代入するなどして各プロパティの値を参照するなどの処理を行うことになります。
Get-MgUser -UserId <認証したユーザーの UPN>

実行例)

Get-MgUser -UserId User01@contoso.onmicrosoft.com
  1. 以下のようにコマンドを実行します。/me/messages 相当の情報が取得できます。実際に戻り値を利用するには変数に代入するなどして各プロパティの値を参照するなどの処理を行うことになります。
Get-MgUserMessage -UserId <認証したユーザーの UPN>

実行例)

Get-MgUserMessage -UserId User01@contoso.onmicrosoft.com
  1. 以下のようにコマンドを実行します。取得しているアクセス トークンを使用して、自由に Microsoft Graph のリクエストを送信することができます。ここでは受信トレイ内のメールの件名を取得しています。
(Invoke-MgGraphRequest -Method GET -Uri 'https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages?$select=subject')["value"] | %{$_.subject}

コマンドの実行がすべて完了してもし Microsoft Graph から切断する場合は以下のコマンドを実行します。

Disconnect-Graph

アプリケーション権限で Microsoft Graph PowerShell SDK を試す

  1. Windows PowerShell を起動します。
  2. 以下のようにコマンドを実行します。
New-SelfSignedCertificate -Subject "<アプリの名前>" -CertStoreLocation "Cert:\CurrentUser\My" -NotBefore <前の日の日付> -NotAfter <将来の日付>

実行例)

New-SelfSignedCertificate -Subject "App01" -CertStoreLocation "Cert:\CurrentUser\My" -NotBefore 2020/10/19 -NotAfter 2021/10/20
  1. 以下のようにコマンドを実行して証明書を CER ファイルにエクスポートします。
Get-ChildItem -Path Cert:\CurrentUser\My\<手順 2 で発行した証明書の Thumbprint> | Export-Certificate -FilePath <エクスポート先のファイル名>

実行例)

Get-ChildItem -Path Cert:\CurrentUser\My\1844DDF33847CB699C6CAEF5DE9DF382380E127D | Export-Certificate -FilePath C:\temp\cert.cer
  1. Azure Portal にサインインします。
  2. [Azure Active Directory] – [アプリの登録] – [新規登録] をクリックします。
  3. [名前] に任意のアプリの名前を入力します。(例 : App01)
  4. [サポートされているアカウントの種類] から [この組織ディレクトリのみに含まれるアカウント] を選択します。
  5. [リダイレクト URI] で [Web] を選択し、値はブランクのままにします。
  6. [登録] をクリックします。
  7. 表示された [アプリケーション (クライアント) ID] と [ディレクトリ (テナント) ID] の値を控えておきます。
  8. [管理] – [API のアクセス許可] をクリックします。
  9. [構成されたアクセス許可] の中の [User.Read] の右端の [・・・] をクリックし、[アクセス許可の削除] をクリックします。
  10. 確認が表示されるので [はい、削除します] をクリックします。
  11. [アクセス許可の追加] をクリックします。
  12. [よく使用される Microsoft API] – [Microsoft Graph] をクリックします。
  13. [アプリケーションの許可] をクリックします。
  14. 一覧の中から [Mail] を展開して [Mail.Read] のチェックを有効にします。
  15. 同様に一覧の中から [User] を展開して [User.Read.All] のチェックを有効にします。
  16. [アクセス許可の追加] をクリックします。
  17. [構成されたアクセス許可] 画面に戻るので、[<テナント名> に管理者の同意を与えます] をクリックします。
  18. 確認が表示されるので [はい] をクリックします。
  19. [管理] – [証明書とシークレット] をクリックします。
  20. [証明書のアップロード] をクリックします。
  21. 手順 3 でエクスポートした CER ファイルを選択し、[追加] をクリックします。
  22. Windows PowerShell を起動します。
  23. 以下のようにコマンドを実行します。
Connect-Graph -ClientID <アプリケーション (クライアント) ID> -TenantId <ディレクトリ (テナント) ID> -CertificateName "CN=<手順 2 で指定した Subject 名>"

実行例)

Connect-Graph -ClientID 03dc5655-c303-42c2-81e2-bc98255c7e75 -TenantId 6d046331-5ea5-4307-87ae-8d51f3dcc71e -CertificateName "CN=App01"
  1. 以下のコマンドを実行すると、現在の認証情報を確認できます。
Get-MgContext
  1. 以下のコマンドを実行します。/users 相当の情報が取得できます。実際に戻り値を利用するには変数に代入するなどして各プロパティの値を参照するなどの処理を行うことになります。
Get-MgUser
  1. 以下のようにコマンドを実行します。/users/<対象ユーザー>/messages 相当の情報が取得できます。実際に戻り値を利用するには変数に代入するなどして各プロパティの値を参照するなどの処理を行うことになります。
Get-MgUserMessage -UserId <任意のユーザーの UPN>

実行例)

Get-MgUserMessage -UserId User01@contoso.onmicrosoft.com
  1. 以下のようにコマンドを実行します。取得しているアクセス トークンを使用して、自由に Microsoft Graph のリクエストを送信することができます。ここではユーザーの UPN を取得しています。
(Invoke-GraphRequest -Method GET -Uri 'https://graph.microsoft.com/v1.0/users?$select=userPrincipalName')["value"] | %{$_.userPrincipalName}
  1. コマンドの実行がすべて完了してもし Microsoft Graph から切断する場合は以下のコマンドを実行します。
Disconnect-Graph