Microsoft Graph APIの変更通知をAzure Function Appで受け取る方法

Microsoft 365上のリソースは変更があった際（例えば、ユーザーの情報の変更やメールの受信など）にMicrosoft Graph APIを使うことで通知を受け取ることができます。

今回はユーザー情報が変更された時にAzure Function Appで通知受け取る方法について、説明します。

変更通知を受け取ることができるリソースは下記のサイトに記載されています。

概要: Microsoft Graph API変更通知 - Microsoft Graph v1.0 | Microsoft Learn

変更通知を受け取るための手順
Azure ADアプリの登録
Azure Function Appの構築
サブスクリプションの登録
変更通知の受け取り
サブスクリプションの更新
まとめ

変更通知を受け取るための手順

変更通知を受け取るための手順は下記の通りとなります。

Azure ADアプリの登録
Azure Functionの構築
サブスクリプションの登録

各手順の詳細を説明していきます。

Azure ADアプリの登録

変更通知を受け取るためには、リソースごとのアクセス許可が必要となります。

今回はユーザーの変更通知を受け取る方法を紹介したいと思うので、以下のアクセス許可でAzure ADアプリを登録してください。

アクセス許可の種類：アプリケーションの許可
アクセス許可：User.ReadWrite.All

なお、認証にはクライアントシークレットを利用するため、クライアントシークレットも発行してください。

後の手順で利用するので、テナントID、アプリケーションID、クライアントシークレットはメモしておいてください。

Azure AD アプリの登録の詳細な手順は下記を参照してください。

Microsoft Graph の認証方法 - JBS Tech Blog

Azure Function Appの構築

Azure Function Appの作成

変更通知を受け取り先として、Azure Function AppのHTTPトリガーを利用します。

Azure Portalにログインして、下記の設定でAzure Functionを作成してください。

記載していない設定値は任意で構いません。

ランタイムスタック：.NET
バージョン：6(LTS)
オペレーティングシステム：Windows

※処理を.NETで記載するため、.NETを選択していますが、他の方法を代替できる場合は、.NET以外でも問題ありません。

HTTPトリガーの追加

関数アプリができたら、HTTPトリガーを追加します。

開発環境：ポータルでの開発
テンプレート：HTTP trigger
新しい関数：<任意の関数名>
Authorization level：Function

「コードとテスト」を選択して、下記の処理を記載してください。

#r "Newtonsoft.Json"

using System.Net;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;
using Newtonsoft.Json;

public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    //QureyパラメーターのvalidationTokenを取得
    string validationToken = req.Query["validationToken"];

    //validationTokenが存在する場合は返却
    //サブスクリプション登録時の検証として、validationTokenを返却する必要がある
    if(!string.IsNullOrEmpty(validationToken))
    {
        log.LogInformation($"Received Token: '{validationToken}'");
        return new OkObjectResult(validationToken);
    }

    //仕様上、5秒以内に処理を返す必要がある
    //複雑な処理をする場合は、DBなどにキューとしてデータを登録しておき、別の機能で処理させる
    //今回は検証のため、ログにコンテンツを出力して、200を返している
    using(StreamReader reader = new StreamReader(req.Body))
    {
        string content = await reader.ReadToEndAsync();
        log.LogInformation(content);
        
        return new OkResult();
    }
}

動作確認

HTTPトリガーが追加できたら、2パターン動作確認を行います。

validationTokenありのパターン

まずはvalidationTokenありのパターンです。

「テストと実行」から下記の設定を行い、「実行」ボタンを押下します。

HTTPメソッド：POST
キー：master(Host key)
クエリ（名前）：validationToken
クエリ（値）：<任意の値>

実行結果は下記になればOKです。

HTTP応答コード：200 OK
HTTP応答コンテンツ：<クエリ(値)で指定した値>

コンテンツありのパターン

次にコンテンツありのパターンです。

同じく「テストと実行」から下記の設定を行い、「実行」ボタンを押下します。

HTTPメソッド：POST
キー：master(Host key)
クエリ（名前）：なし
クエリ（値）：なし
ボディ：<JSON形式で任意の値>

実行結果は下記になればOKです。

HTTP応答コード：200 OK
HTTP応答コンテンツ：なし

ログにボディに指定した値が表示されることも確認してください。

関数のURLの取得

変更通知の送り先として、関数のURLを取得します。

「関数のURLの取得」を押下していただき、キーをmasterにして、URLをコピーしてください。

サブスクリプションの登録

変更通知の登録を行います。

ここでいうサブスクリプションはAzureのサブスクリプションではなく、変更通知を購読する、という意味のサブスクリプションになります。

前述しておりますが、今回はユーザーの変更通知を受け取ります。

Microsoft Graph PowerShellを使い、Azure AD アプリに登録時に発行されたテナントID、アプリケーションID、クライアントシークレットでMicrosoft 365に接続します。

接続後、下記のコマンドを使って、変更通知のサブスクリプションを登録します。

$params = @{
	changeType = "updated"
	notificationUrl = "< 関数のURL >"
	resource = "/users"
	expirationDateTime = [System.DateTime]::UtcNow.AddDays(1)
	clientState = "SecretClientState"
}
New-MgSubscription -BodyParameter $params

参考：サブスクリプションを作成する - Microsoft Graph v1.0 | Microsoft Learn

HTTPトリガーのモニターから実行履歴を見ると、validationTokenありのリクエストが来ていることがわかります。

変更通知の受け取り

続いて、ユーザーの情報を更新して、変更通知を受け取ってみます。

今回は手動でテナントにいるユーザーの部署を人事部から総務部に変更してみます。

更新後に再度HTTPトリガーのモニターを確認すると、下記のログが出力されています。

ログを見てもらえるとわかりますが、変更通知は変更対象のオブジェクトIDを返すのみで、どんな変更があったかは記載されていません。

具体的な変更内容を確認するために、別で対象のユーザー情報を取得して確認する必要があります。ユーザー情報の変更内容を取得するためにはMicrosoft Graph API のデルタクエリを使用する必要があります。詳細は別の記事で説明したいと思いますが、参考情報だけ共有いたします。

参考：ユーザーに対する増分の変更を取得する - Microsoft Graph | Microsoft Learn

サブスクリプションの更新

変更通知のサブスクリプションには有効期限があります。また、変更通知を受けた際にタイムアウトやエラーを返すと変更通知のサブスクリプションは停止します。

※リソースごとに設定可能な有効期限は異なります。

そのため、実運用ではサブスクリプションの監視と定期的な有効期間の更新が必要となります。例えば、以下のコマンドを利用して、関数アプリなどで定期的に実行する様に構成します。

現在のサブスクリプションを取得するコマンド

Get-MgSubscription

参考：サブスクリプションを一覧表示する - Microsoft Graph v1.0 | Microsoft Learn

サブスクリプションの有効期限を更新するコマンド

$subscriptionId = "< サブスクリプションID >" $params = @{ expirationDateTime = [System.DateTime]::UtcNow.AddDays(1) } Update-MgSubscription -SubscriptionId $subscriptionId -BodyParameter $params

参考：サブスクリプションを更新する - Microsoft Graph v1.0 | Microsoft Learn