Microsoft GraphAPIを使ってみよう。-実践 編-

はじめに

こんにちは、くらっちです。
前回記事でMicrosoft GraphAPIを利用するためのアプリ登録手順を説明したので、今回は登録したアプリを使って PowerShell で GraphAPI を利用する手順を説明します。

※前回記事はこちら
kurattyodiary.hatenablog.com

目次

クライアント資格情報による認証

Microsoft Graph にアクセスする際は認証が必要になります。
その認証方法は下記の４パターンです。
　・デバイスコードによる認証
　・認証コードによる認証
　・パスワードによる認証
　・クライアント資格情報による認証

今回は「クライアント資格情報による認証」に絞って紹介します。
この認証で、サインインを必要とせずMicrosoft Graphに対して認証することができます。
実行時にサインインを求められないため「自動化されたタスクやスクリプト」に最適です。

例として「自組織のすべてのグループ」を取得するためのサンプルを用意しました。
PowerShellで下記ソースコードを実行すると「自組織のすべてのグループ」を取得できます。
※<>内は登録したアプリの情報に修正してください。

サンプルコード

#######################GraphAPI接続 start
$clientid = "<アプリケーション（クライアント）ID>"
$tenantName = "<アプリを登録したテナントのドメイン>　例（sampledomain.onmicrosoft.com）"
$clientSecret = "<クライアント シークレット>"
  
$ReqTokenBody = @{
    Grant_Type    = "client_credentials"
    Scope         = "https://graph.microsoft.com/.default"
    client_Id     = $clientID
    Client_Secret = $clientSecret
} 
 
$TokenResponse = Invoke-RestMethod -Uri "https://login.microsoftonline.com/$tenantName/oauth2/v2.0/token" -Method POST -Body $ReqTokenBody
#######################GraphAPI接続 end

#######################GraphAPIで情報取得
$apiUrl = 'https://graph.microsoft.com/v1.0/Groups/'
$Data = Invoke-RestMethod -Headers @{Authorization = "Bearer $($Tokenresponse.access_token)"} -Uri $apiUrl -Method Get
$Groups = ($Data | select-object Value ).Value
$Groups | Format-Table DisplayName, Description -AutoSize

解説

アクセストークン取得

前回登録したアプリでアクセストークンを取得します。
アクセストークンには、アプリ自体とアプリに付与されているアクセス許可に関する情報が含まれており、このアクセストークンを取得することでGraph APIを利用可能にします。

2行目～13行目でアクセストークンを取得します。
　2行目：Azure ADで登録したアプリの「アプリケーション（クライアント）ID」を入力。
　3行目：「アプリを登録したテナントのドメイン」を入力します。
　4行目：Azure ADで登録したアプリの「クライアント シークレット」を入力します。
　※今回クライアント シークレットは直書きしていますが、パスワードと同じ扱いをする必要があるため、実稼働する場合は暗号化するなどしてください。

$clientid = "<アプリケーション（クライアント）ID>"
$tenantName = "<アプリを登録したテナントのドメイン>　例（QiitaTest2020.onmicrosoft.com）"
$clientSecret = "<クライアント シークレット>"

6行目～11行目で「クライアント資格情報による認証」を実施します。

$ReqTokenBody = @{
    Grant_Type    = "client_credentials"
    Scope         = "https://graph.microsoft.com/.default"
    client_Id     = $clientID
    Client_Secret = $clientSecret
} 

13行目でアクセストークンを取得します。

$TokenResponse = Invoke-RestMethod -Uri "https://login.microsoftonline.com/$tenantName/oauth2/v2.0/token" -Method POST -Body $ReqTokenBody

Graph APIの指定

17行目：Graph APIを指定します。指定するGraph APIは下章の手順に従って確認します。

$apiUrl = '<Graph API>'　例（'https://graph.microsoft.com/v1.0/Groups/'）

ソースコードに記載するGraph APIを探す方法

1．Graph Explorer にアクセスします。
2．左側メニューの「Sample queries」で、利用するAPIをキーワード検索します。
3．左側メニューから利用するAPIをクリックします。
4．画面上部にGraphAPIの使用例が表示されるのでコピーします。

※「自分の組織内のすべてのグループ」の場合
　左側メニューから list all groups in my organization を選択します。
　画面上部には https://graph.microsoft.com/v1.0/groups と表示されます。

Graph APIの実行

18行目：Graph APIを実行します。

$Data = Invoke-RestMethod -Headers @{Authorization = "Bearer $($Tokenresponse.access_token)"} -Uri $apiUrl -Method Get

19行目：Graph APIを通して取得したデータから、「Value」のみを抽出します。
20行目：Valueから「表示名」列と「説明」列を抽出します。

$Groups = ($Data | select-object Value ).Value
$Groups | Format-Table DisplayName, Description -AutoSize

取得結果

実行した結果、こんな感じ。

displayName           description
-----------           -----------
テストチーム５       　説明文５
テストチーム２       　説明文２
PowerShell作成チーム１ 説明文
テストチーム３       　説明文３
テストチーム４       　説明文４

取得した結果はソート順、抽出条件、表示件数を指定していません。
20行目を下記のどれかに変更することでソート順、抽出条件、表示件数を調整できます。

# オプション例--------------------------------
# フィルター
$Groups | Where-Object {$_.description -match "^説明文*"} | Format-Table DisplayName, Description -AutoSize
# ソート順変更（-Descending：降順、未入力：昇順）
$Groups | Sort-Object Description -Descending　| Format-Table DisplayName, Description -AutoSize
# 表示数変更（-First：先頭から〇個、-Last：末尾から〇個）
$Groups | select-Object -First 3 | Format-Table DisplayName, Description -AutoSize
# フィルター　表示数　表示列（左から順に実行されていく、フィルターと表示数の定義が逆になると結果も変わってしまう）
$Groups | Where-Object {$_.description -match "^説明文*"} | select-object -first 3 | Format-Table DisplayName, Description -AutoSize

参考ページ

・リストグループ（MS公式サイト）
・CONNECT AND NAVIGATE THE MICROSOFT GRAPH API WITH POWERSHELL
・PowerShellでMicrosoft Graph APIを使用する