Microsoft Graph PowerShell SDK の試し方

2020/10/21 Microsoft Graph

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 SDK の特定のモジュールのみを利用する方法もあります)。多くのシナリオにおいて、これらのコマンドのほとんどは使われることはありません。そのため、本当に Microsoft Graph PowerShell Module を使用することが適切なのか、もしくは (OAuth で MSAL を使用したとしても残りの部分は) PowerShell の標準機能だけで実装することが適切なのか、検討する必要があります。

なお紹介する内容は以下の環境で動作確認をしています。このバージョンは Windows PowerShell で使用するとリクエストのクエリ文字列の内容に問題が生じるので、PowerShell は Windows PowerShell ではなく PowerShell 7 を使用して動作確認をしています。

  • Microsoft Graph PowerShell SDK 1.6.1
  • PowerShell 7.1.4

Microsoft Graph PowerShell SDK について

Microsoft Graph PowerShell SDK はオープン ソースで開発されている PowerShell Module で、Microsoft Graph を PowerShell から実行しやすくしたものです。プロジェクトは GitHub で管理されており、PowerShell Module は MIT ライセンスで配布されています。有償で提供される製品とは異なり MIT ライセンスで無償で配布されている PowerShell Module のため、Microsoft による技術サポートの提供も限定的であったり内容によっては対応されなかったりします。

microsoftgraph/msgraph-sdk-powershell: Powershell SDK for Microsoft Graph
https://github.com/microsoftgraph/msgraph-sdk-powershell

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-MgGraph -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-MgGraph

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

基本的な内容は以下の技術情報に記載されています。

Use app-only authentication with the Microsoft Graph PowerShell SDK
https://docs.microsoft.com/en-us/graph/powershell/app-only?tabs=azure-portal

Azure AD へのアプリケーションの登録がまずは必要です。以下に手順を紹介します。

  1. Azure Portal にサインインします。
  2. [Azure Active Directory] – [アプリの登録] – [新規登録] をクリックします。
  3. [名前] に任意のアプリの名前を入力します。(例 : App01)
  4. [サポートされているアカウントの種類] から [この組織ディレクトリのみに含まれるアカウント] を選択します。
  5. [リダイレクト URI] で [Web] を選択し、テキスト ボックスは空欄のままにします。
  6. [登録] をクリックします。
  7. 表示された [アプリケーション (クライアント) ID] と [ディレクトリ (テナント) ID] の値を控えておきます。
  8. [管理] – [API のアクセス許可] – [アクセス許可の追加] をクリックします。
  9. [Microsoft Graph] – [アプリケーションの許可] をクリックし、[Mail.Read] と [User.Read.All] を選択して [アクセス許可の追加] をクリックします。
  10. [構成されたアクセス許可] の中の [種類] が [委任済み] である [User.Read] の右側の [・・・] をクリックし、[アクセス許可の削除] をクリックします。確認が表示されるので [はい、削除します] をクリックします。
  11. [<テナント名> に管理者の同意を与えます] をクリックします。確認が表示されるので [はい] をクリックします。

次に証明書を発行します。

  1. Windows PowerShell を起動します。
  2. 以下のようにコマンドを実行します。証明書が発行され、cer ファイルと pfx ファイルが出力され、コンソール上に証明書の Thumbprint が表示されます。
$mycert = New-SelfSignedCertificate -Subject "<アプリの名前>" -CertStoreLocation "Cert:\CurrentUser\My" -NotAfter (Get-Date).AddYears(1) -KeySpec KeyExchange
$mycert | Export-Certificate -FilePath <エクスポート先のファイル名>
$mycert | Export-PfxCertificate -FilePath <エクスポート先のファイル名> -Password $(ConvertTo-SecureString -String "<エクスポートした PFX ファイルを保護する任意のパスワード>" -Force -AsPlainText)
$mycert | Select Thumbprint

実行例)

$mycert = New-SelfSignedCertificate -Subject "App01" -CertStoreLocation "Cert:\CurrentUser\My" -NotAfter (Get-Date).AddYears(1) -KeySpec KeyExchange
$mycert | Export-Certificate -FilePath c:\temp\mycert.cer
$mycert | Export-PfxCertificate -FilePath c:\temp\mycert.pfx -Password $(ConvertTo-SecureString -String "1234" -Force -AsPlainText)
$mycert | Select Thumbprint
  1. Azure Portal で先ほど登録したアプリのページに戻ります。
  2. [管理] – [証明書とシークレット] – [証明書] をクリックします。
  3. [証明書のアップロード] をクリックします。
  4. 先ほど出力された CERファイルを選択して [追加] をクリックします。
  5. 以上で準備は完了です。以下のいずれかの方法で Connect-MgGraph コマンドを実行して Microsoft Graph に接続します。

証明書の拇印を指定して証明書ストアから読み込んで接続するには以下のようにコマンドを実行します。

Connect-MgGraph -ClientId "<登録したアプリのアプリケーション (クライアント) ID>" -TenantId "<アプリを登録したテナントのディレクトリ (テナント) ID>" -CertificateThumbprint "<証明書の拇印>"

実行例)

Connect-MgGraph -ClientId "b502ac25-c0b0-4436-bd12-fdb79ece2341" -TenantId "7d046331-5ea5-4306-87ae-8d51f3dcc71e" -CertificateThumbprint "C1BF2E11A13E4F898627AFAA7FF848A63AD2D68E"

X509Certificate2 オブジェクトを指定して接続するには以下のようにコマンドを実行します。この例では証明書ストアから証明書を読み込んでいます。

Connect-MgGraph -ClientId "<登録したアプリのアプリケーション (クライアント) ID>" -TenantId "<アプリを登録したテナントのディレクトリ (テナント) ID>" -Certificate:(Get-ChildItem -Path Cert:\CurrentUser\My\<証明書の拇印>)

実行例)

Connect-MgGraph -ClientId "b502ac25-c0b0-4436-bd12-fdb79ece2341" -TenantId "7d046331-5ea5-4306-87ae-8d51f3dcc71e" -Certificate:(Get-ChildItem -Path Cert:\CurrentUser\My\C1BF2E11A13E4F898627AFAA7FF848A63AD2D68E)

証明書の名前を指定して証明書ストアから読み込んで接続するには以下のようにコマンドを実行します。

Connect-MgGraph -ClientId "<登録したアプリのアプリケーション (クライアント) ID>" -TenantId "<アプリを登録したテナントのディレクトリ (テナント) ID>" -CertificateName "CN=<証明書のサブジェクト名>"

実行例)

Connect-MgGraph -ClientId "b502ac25-c0b0-4436-bd12-fdb79ece2341" -TenantId "7d046331-5ea5-4306-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