グラフ API を使用するために Workplace 365 PowerShell スクリプトをアップグレードする方法

グラフの方が速い

間違いなく、グラフ API 呼び出しを使用すると、PowerShell コマンドレットよりも Office 365 を取得する方がはるかに高速です。のような複雑なスクリプトでは、より明白です。 グループおよびチームアクティビティ スクリプトグラフ API 呼び出しが Exchange オンラインおよび SharePoint オンライン モジュールのコマンドレットを置き換えるため、グラフ バリアント (5.1) の方がはるかに高速です ( 4.8) 。特にテナントが数千のグループをサポートしており、Graph API バージョンのスクリプトが純粋な PowerShell バージョンの処理に苦労しているグループを大量に処理できる場合、速度は重要です。

変換する例を探す

より高速なスクリプトを持つことは良いことですが、アクティビティレポートの複雑さは、おそらくtを説明するのに適したテストケースではありませんそれが良い考えであるかどうかを判断するために通過する必要がある彼の決定プロセス をクリックして、Graph API を使用するようにスクリプトをアップグレードし、改善を測定します。シンプルさが良いので、アップグレードするために何をする必要があるかを見てみましょう Microsoft 365 グループ メンバーシップ レポート スクリプト.このスクリプトでは、次のコマンドレットを使用します。

• 取得-AzureADUser: テナント内の Azure AD アカウントの一覧を取得します。マイクロソフト Azure AD モジュールを廃止する意向を発表しました 2021 年 6 月に、これは Azure AD 呼び出しを Graph API 呼び出しに置き換えるために必要なスクリプト更新の種類の良い例です。
• 取得統一グループ: テナント内のチームのリストを取得します。
• 受信者を取得する: ユーザー アカウントが属するグループの一覧を取得します。

2 つのコマンドレットは Exchange オンライン管理モジュールから取得され、1 つは Azure AD モジュールから取得されます。これらのコマンドレットによってフェッチされたデータをフィルター処理、並べ替え、および処理するために、他の処理の多くが行われますが、基本的には、これらのコマンドレットを Graph API 呼び出しで置き換える必要があります。簡単に聞こえます。

グラフ API の使用

任意のスクリプトが Graph API を使用する前に、スクリプトは Azure AD 登録済みアプリ.このアプリは、スクリプトがデータにアクセスできるように権限の所有者として機能します。登録されているすべてのアプリには、一意の識別子があります。登録されたアプリを作成すると、アプリのシークレットを生成できます。アプリを実行する際には、アプリを使用する権限があることを証明する秘密を知る必要があります。

電話をかける前に、テナント ID を知る必要があります。これは、テナントが返す GUID です。 取得します。 コマンドレット。ザ コネクトマイクロソフトチーム コマンドレットは、この情報も返します。アプリを使用して Graph API にアクセスする前に、すべてをまとめ、アプリ識別子、アプリ シークレット、テナント識別子を知る必要があります。スクリプトでは、このようなコードがよく見られます。

$AppId = "a09cf913-5ff9-48a2-8015-f28f2854df26"
$AppSecret = "u6X7_i8K-yhh-b4-z5FEmj_wH_M~nIOz4n"
$TenantId = "22e90715-3da6-4a78-9ec6-b3282389492b"

Graph API アプリを使用してアクセス許可のしくみを理解し、アプリが処理するデータを操作するために必要なアクセス許可のみを確実に受け取るようにする上で重要な部分です。我々のアプリの場合、我々は必要があります。

• グループ.読み取り.すべて: テナント内の Microsoft 365 グループに関する情報を読み取る場合。
• グループメンバー.読み取り.すべて: Microsoft 365 グループのメンバーシップに関する情報を読み取ります。
• ユーザー.読み取り.すべて: テナントの Azure AD アカウントに関する情報を読み取ります。

すべてのプログラミングタスクと同様に、ブラウズ後に正しいアクセス許可を割り当てるのは、すぐに第二の性質になります。 マイクロソフトのドキュメント をクリックして、正しいアクセス許可を見つけます。

管理者は、アプリに割り当てられたアクセス許可の使用を許可することに同意します。ハッカーは OAuth の同意をデータにアクセスするアクセス許可を得る方法として使用できるため、目を離さない方が賢明です。 組織内で与えられる同意、または、有無に関係なく マイクロソフトの MCAS 用の新しいアプリ ガバナンス アドオン.

アクセス トークン

適切に許可されたアプリ、アプリの秘密、テナント識別子を備え、アプリは、アクセストークンを要求することができます。 トークン エンドポイントへの要求の投稿.Office 365 データへのグラフ API 呼び出しの場合、次のようになります。

https://login.microsoftonline.com/tenant-identifier/oauth2/v2.0/token

応答として発行されたベアラー トークンは、アプリがユーザー、グループ、サイトなどのデータにアクセスするために必要なアクセス許可を持っていることを確認し、アクセスが読み取り専用か読み取り/書き込みかを確認します。トークンは、Graph API に対して行われた要求の承認ヘッダーに含まれます。アクセス トークンは 1 時間後に期限切れになるため、長時間実行されるプログラムは処理を続行するためにトークンを更新する必要があります。

このすべては複雑に聞こえますが、一度1つのスクリプトのためにそれを行うと、それは第 2 の性質は、アクセス トークンを取得し、Graph API 呼び出しを使用して開始する準備ができています。

PowerShell コマンドレットの置き換え

他の何かと同様に、Graph API 呼び出しを使用してデータをフェッチするのに慣れるには少し時間がかかります。フェッチされたデータには注意を払う必要があります。まず、リソースの需要を制限するには、 グラフは一度に限られたデータをフェッチし、それ以上データが利用できないまで反復する必要があります (改ページ位置付けと呼ばれるプロセス)。次に、場合によっては、コマンドレットで使用されるプロパティ名は、Graph API で使用されるものと異なります。たとえば、 取得統一グループ コマンドレットは Notes プロパティのグループの説明を返しますが、グループ API は説明を使用します。

ザ グラフエクスプローラ は、開発者が Graph API の構文とデータに慣れるためのオンライン Microsoft ツールです。スクリプトに呼び出しを含める前に、Explorer を使用して呼び出しをテストする必要があります。グラフ エクスプローラを使用して呼び出しをデバッグすると、多くの時間と心痛を節約できます。図 1 は、ユーザーに返されるグループの推移的なセットを調べるために使用されるグラフ エクスプローラを示しています。

グラフ エクスプローラはグラフ アプリです。他のアプリと同様に、データにアクセスするためのアクセス許可が必要です。呼び出しが失敗した場合、Explorer は、どのアクセス許可が欠落しているかを示し、その割り当てに同意できます。

Azure AD アカウントの取得

スクリプトで置き換える必要がある最初のコマンドレットは、テナント内の Azure AD ユーザーの一覧を取得するコマンドレットです。パワーシェルでは、次のようになります。

$Users = Get-AzureADUser -All:$true

グラフユーザー API は、同じデータをフェッチします。とは異なり、 取得-AzureADUser コマンドレットでは、既定のプロパティ セットが返され、他のプロパティが必要な場合は特定のプロパティを指定する必要があります。使用される呼び出しを次に示します。

$Uri = https://graph.microsoft.com/v1.0/users?&`$select=displayName,usertype,assignedlicenses,id,mail,userprincipalname
$Users = Get-GraphData -AccessToken $Token -Uri $Uri

グラフデータを取得する は、コマンドレットによって返される PowerShell オブジェクトのような形式で Graph API 呼び出しによって返されるデータのページ分割と抽出を処理するラッパー関数です。Graph API 呼び出しと対話するスクリプトにこのような関数を含めることで、作業を楽にすることができます。使用する関数の例を見る場合は、 GitHub のグループ メンバーシップ レポート スクリプトのグラフ バージョン.

チームの取得

2 番目の呼び出しは、チーム対応グループのリストを取得します。次に、このスクリプトはチームを格納するハッシュ テーブルを作成し、グループがプロパティを報告するときにチームが有効かどうかを確認するためのルックアップとして使用できるようにします。PowerShell コードでは、サーバー側のフィルターを使用し、 取得統一グループ コマンドレットを使用してチームを返します。

$Teams = Get-UnifiedGroup -Filter {ResourceProvisioningOptions -eq "Team"} -ResultSize Unlimited | Select ExternalDirectoryObjectId, DisplayName

グラフ グループ API は、同じ種類のフィルターを使用します。

$Uri = "https://graph.microsoft.com/beta/groups?`$filter=resourceProvisioningOptions/Any(x:x eq 'Team')"
$Teams = Get-GraphData -AccessToken $Token -Uri $Uri

ユーザーが属するグループの取得

最後に行う呼び出しは、ユーザー アカウントがメンバーであるグループのセットを検索することです。ザ 受信者を取得する コマンドレットは、アカウントの識別名に基づいてグループの一覧を返すのが非常に高速です。によって返されるユーザー データ 取得-AzureADUser 識別名を与えない (それは Exchange オンライン プロパティです)、我々は実行する必要があります 受信者を取得する 2回: 識別名を取得し、識別名を使用してグループを検索します。

$DN = (Get-Recipient -Identity $User.UserPrincipalName).DistinguishedName
$Groups = (Get-Recipient -ResultSize Unlimited -RecipientTypeDetails GroupMailbox -Filter "Members -eq '$DN'" | Select DisplayName, Notes, ExternalDirectoryObjectId, ManagedBy, PrimarySmtpAddress)

グラフユーザー API は、アカウントのメンバーシップ情報を検索するグループに対して推移的なルックアップを解決できます。私たちは、このような呼び出しを使用することができます:

$Uri = "https://graph.microsoft.com/v1.0/users/" + $user.id +"/transitiveMemberOf"
$Groups = Get-GraphData -AccessToken $Token -Uri $Uri

それです。スクリプト内の他のすべてのコマンドは、Azure AD または Exchange オンラインからフェッチされたデータを処理します。上記の変更とは別に、同じコードが PowerShell と Graph の両方のバージョンのスクリプトに使用されます。

結果

マイレージは、接続先のバックエンド サーバー、サービスの負荷状態、およびその他の要因によって異なる場合があります。EPAマイレージの数字と同じくらい信頼性の高い私のテストは、PowerShellバージョンがそれぞれ約0.6/秒の割合でアカウントを処理したことを明らかにしました。グラフバージョンは、時間を約0.4/秒に短縮しました。言い換えれば、50%の改善。

すべてのスクリプトは、このような速度のブーストの恩恵を受けるとは限りませんし、他のスクリプトは、グラフターボチャージャーをインストールするために、より多くの作業が必要になります。しかし、ポイントは、グラフを搭載したPowerShellは、純粋なPowerShellよりもOffice 365データの処理がはるかに高速であるということです。次に Office 365 用 PowerShell ベースのソリューションの構築に取り組む方法を検討する際には、そのことを念頭に置いてください。

---

Office 365 が実際にどのように機能するかについては、サブスクリプションを作成してください。 IT 担当者向け Office 365 電子書籍。毎月の更新プログラムでは、Office 365 エコシステム全体で重要な情報を購読者に通知します。

関連