Microsoft 365 は、多くの企業にとって無くてはならないツールとなっています。
最近は、IDMと連携しバッチ処理でEntra IDのアカウントのメンテナンスやExchange Onlineの操作などを実施する企業が多くなっていると感じます。
身近なツールであるPowerShellを使いGraph APIでどこまでできるのかを試してみました。
認証設定
まずは、PowerShellでMicrosoft 365 に接続できる必要があります。 そのためには、どのように認証するかを設計する必要があります。 スクリプトの主な認証方法は以下の通りです。
-
対話型認証
→人の操作が必要なため、バッチ処理には不向き。 -
マネージド ID
→Azure の仮想マシンなどであれば、推奨される（手軽にPCを利用する場合はNG）。 -
シークレット
-
証明書
証明書の方がセキュアなため、証明書を採用。
鍵管理サービスがあれば、そこから証明書発行が望ましいですが、ここでは自己証明書を使います。
以下の記事を参考にPowerShellで自己証明書を発行し、証明書ファイルを発行します。
https://learn.microsoft.com/ja-jp/entra/identity-platform/howto-create-self-signed-certificate#create-and-export-your-public-certificate
Entra ID側で「アプリの登録」からアプリを作成します（ここでは、MSGraphScriptsという名前にしました）。
「証明書とシークレット」から自己証明書をアップロードします。
登録した拇印を控えておきます。
自己証明書をインストール済みの端末でConnect-MgGraphを実行し、Microsoft 365に接続します。
PowerShellで自己証明書を作成したPCには、証明書登録済みです。
▽PowerShellで実行
Connect-MgGraph -ClientId "{servicePrincipal's Object}" -TenantId "{tenantId}" -CertificateThumbprint "{登録した証明書の拇印}"
権限設定
Graph APIで何をするかによって、上記で準備したサービスを用いた接続に対し、どの権限を与えるか検討します。
今回は、Outlookの予定表（イベント）を作成する処理を検討します。
その場合、以下のリファレンスが使えそうです。
▽イベント作成 https://learn.microsoft.com/ja-jp/graph/api/calendar-post-events?view=graph-rest-1.0&tabs=powershell
▽イベント一覧表示 https://learn.microsoft.com/ja-jp/graph/api/calendar-list-events?view=graph-rest-1.0&tabs=http
現状権限設定を実装していないので、テストアカウント「test1」のイベント一覧を確認するとエラーになります。
では必要な権限を確認します。以下のイベント一覧表示用APIのリファレンスに「アクセス許可」という箇所があります。 https://learn.microsoft.com/ja-jp/graph/api/calendar-list-events?view=graph-rest-1.0&tabs=http#permissions
そこに記載のある以下の３つのいずれかが必要とのことです。ここでは、3つとも許可します。（本来は最小権限の原則に沿った設計が望ましいです）
Calendars.ReadBasic、Calendars.Read、Calendars.ReadWrite
認証設定時に作成したサービスの設定画面から、「APIのアクセス許可」＞「アクセス許可の追加」をクリックし、「アプリケーションの許可」を選択した状態で上記３つのアクセス許可設定を検索し、有効化します。
以下の画面になることを確認します。
では、再度イベント一覧表示を試します。
一度、切断します。
Disonnect-MgGraph
再接続します。
Connect-MgGraph -ClientId "{servicePrincipal's Object}" -TenantId "{tenantId}" -CertificateThumbprint "{登録した証明書の拇印}"
再度、イベント一覧を確認すると、いろいろイベントがでてきました（テスト用に作成したイベントです）
今回は、イベントを作成するバッチを作るのでイベント作成リファレンスのアクセス許可を確認します。
https://learn.microsoft.com/ja-jp/graph/api/calendar-post-events?view=graph-rest-1.0&tabs=powershell#permissions
ここでは「Calendars.ReadWrite」が必要とのことです。先の手順ですでに許可しているので、問題なさそうです。
動作確認
せっかくなのでイベント作成してみます。
イベントにリソースメールボックスの会議室を登録したかったのですが、オブジェクトの作成方法がわからなかったので、事前にOutlookで作成したイベントから会議室オブジェクトを$location変数に格納して利用することにしました。
リファレンスを参考にし、スクリプトでイベントを作成します。
transactionIdは、一意である必要があるらしく、適当に設定しました。
$params = @{
subject = "クリスマスイブ"
body = @{
contentType = "HTML"
content = "メリークリスマス"
}
start = @{
dateTime = "2024-12-24T04:00:00"
timeZone = "UTC"
}
end = @{
dateTime = "2024-12-24T05:00:00"
timeZone = "UTC"
}
location = $location
attendees = @(
@{
emailAddress = @{
address = "test1@XXXXXXX"
name = "テスト1"
}
type = "required"
}
@{
emailAddress = @{
address = "test10@XXXXXXX"
name = "テスト10"
}
type = "required"
}
)
transactionId = "7E163156-7762-4BEB-A1C6-729EA8175515"
}
$userId="test1@XXXXXXX"
New-MgUserEvent -UserId $userId -BodyParameter $params
Outlook on the webにtest1でログインすると、カレンダーにイベントが作成されました。
以上です。
Graph APIのリファレンスをみていただいたらわかるように、あらゆる操作が可能です。
細かい要件をスクリプトで実装することで、工数や操作ミスの削減につなげられると思います。
非常に強力なツールですが、認証や権限、鍵運用の設計には注意が必要です。
