Microsoft Graph PowerShell SDK の魅力をマスターする

2023年2月13日

彼は幸せそうに見えますが、Microsoft Graph PowerShell SDKのフォイブルのいくつかをまだヒットしていません... — 彼は幸せそうに見えますが、まだSDKフォイブルのいくつかをヒットしていません…

グラフ API 要求を PowerShell コマンドレットに変換すると、うまくいかないことがあります

テクノロジーを長く扱うほど、その長所と短所について知るようになります。私はMicrosoft Graph PowerShell SDKを約2年間使用しています。私は、SDK によって PowerShell スクリプトの開発に慣れているユーザーが Graph API にアクセスしやすくする方法は気に入っていますが、SDK の欠点の一部は嫌いです。

この記事では、最も胸焼けを引き起こすMicrosoft Graph PowerShell SDK の特異性について説明します。非推奨になる前に Azure AD および MSOL モジュールからスクリプトを変換するときに注意すべき点はすべてです (そういえば、興味深いツールそれはこの仕事に役立つかもしれません)。

$Nullを尊重しない

時々あなたはただプロパティに何かを書きたくないだけです、そしてそれは何です PowerShell の$Null変数のためです。ただし、Microsoft Graph PowerShell SDK コマンドレットは、$Nullを使用する場合に気に入らない。たとえば、新しい Azure AD ユーザーアカウントを作成するとします。このコードは、新しいアカウントのプロパティを含むハッシュテーブルを作成し、 新規管理ユーザー コマンドレット。

$NewUserProperties = @{
    GivenName = $FirstName
    Surname = $LastName
    DisplayName = $DisplayName
    JobTitle = $JobTitle
    Department = $Null
    MailNickname = $NickName
    Mail = $PrimarySmtpAddress
    UserPrincipalName = $UPN
    Country = $Country
    PasswordProfile = $NewPasswordProfile
    AccountEnabled = $true }
$NewGuestAccount = New-MgUser @NewUserProperties

新規管理ユーザー $Nullが有効な PowerShell 値であっても、部門プロパティの値が無効であるため失敗します。

New-MgUser : Invalid value specified for property 'department' of resource 'User'.
At line:1 char:2
+  $NewGuestAccount = New-MgUser @NewUserProperties
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidOperation: ({ body = Micros...oftGraphUser1 }:<>f__AnonymousType64`1) [New-MgUser
   _CreateExpanded], RestException`1
    + FullyQualifiedErrorId : Request_BadRequest,Microsoft.Graph.PowerShell.Cmdlets.NewMgUser_CreateExpanded

1つの解決策は、単一のスペースを保持する変数を使用することです。もう一つは、同等のGraphリクエストを実行して$Nullを渡すことです。 Invoke-MgGraphRequest コマンドレット。また、何が起こってはいけないのかについての良い答えでもありません(そして、null値をフィルタリングできないことについても言及していません)。

パイプラインを無視する

パイプラインは、PowerShell の基本的な構成要素です。これにより、コマンドレットによって取得されたオブジェクトを別のコマンドレットに渡して処理できます。ただし、パイプラインの有用性にもかかわらず、SDK コマンドレットはそれをサポートしておらず、SDK コマンドレットが受信オブジェクトの処理を求められるたびにパイプラインが停止します。例えば：

Get-MgUser -Filter "userType eq 'Guest'" -All | Update-MgUser -Department "Guest Accounts"
Update-MgUser : The pipeline has been stopped

なぜこれが起こるのですか?オブジェクトを受け取るコマンドレットは、異なるオブジェクトを区別できないと処理できません。この場合、 Get-MgUser ゲストアカウントのセットを配信しますが、 Update-mgUser コマンドレットは、オブジェクトが UserId パラメーターを介して識別されるのに対し、受信オブジェクトは Id プロパティで ID を提供するため、各オブジェクトの処理方法を知りません。

回避策は、オブジェクトのセットを配列に格納し、オブジェクトを フォーイーチ ループ。

プロパティの大文字と小文字の区別とデータのフェッチ

私は使用しました 表示名 を使用して、Exchange Server 2007 で PowerShell を使い始めてからのオブジェクトの表示名を参照します。Microsoft Graph PowerShell SDK が登場するまで、プロパティ名の D と N を大文字にすることに問題はありませんでしたが、SDK コマンドレットがプロパティ名の特定の形式の大文字と小文字を主張することがあることが判明しました。準拠しないと、データを取得できません。

苛立たしいのは、制限に一貫性がないことです。たとえば、次のコマンドは両方とも機能します。

Get-MgGroup -Filter "DisplayName eq 'Ultra Fans'"
Get-MgGroup -Filter "displayName eq 'Ultra Fans'"

しかし、私はグループメンバーを見つけたいとしましょう Get-MgGroupMember コマンドレット:

[array]$GroupMembers = Get-MgGroupMember -GroupId (Get-MgGroup -Filter "DisplayName eq 'Ultra Fans'" | Select-Object -ExpandProperty Id)

これは機能しますが、個々のグループメンバーを指す一連の識別子になります。次に、スクリプトを作成してグループメンバーシップを報告することで得られた経験から、 Get-MgGroupMember (メンバーシップを扱う他のコマンドレットと同様 Get-MgAdministrationUnitMember のように) は、 追加プロパティ メンバーに関する追加情報を保持します。だから私は試してみます:

$GroupMembers.AdditionalProperties.DisplayName

いいえ！しかし、フォーマットをに変更すると 表示名、私はメンバー名を取得します:

$GroupMembers.AdditionalProperties.displayName
Tony Redmond
Kim Akers
James Ryan
Ben James
John C. Adams
Chris Bishop

イライラする混乱について話してください!表示名だけではありません。任意のプロパティへの参照 追加プロパティ 出力を使用したのと同じ大文字と小文字を使用する必要があります。 ユーザープリンシパル名前 そして 割り当てられたライセンス.

別の例は、サインインログを探す場合です。このコマンドが機能するのは、ユーザープリンシパル名の形式がサインインログデータに格納されているものと同じであるためです。

[array]$Logs = Get-MgAuditLogSignIn -Filter "UserPrincipalName eq 'james.ryan@office365itpros.com'" -All

ユーザープリンシパル名の大文字の部分を指定すると、コマンドはヒットをゼロにします。

[array]$Logs = Get-MgAuditLogSignIn -Filter "UserPrincipalName eq 'James.Ryan@office365itpros.com'" -All

ここでは、2つのSDKフォイブルが展示されています。まず、コマンドレットが識別子のセットを返し、情報を 追加プロパティ (これが当てはまるとは思わない開発者によって見落とされがちな何か)。次に、プロパティの大文字と小文字の完全一致に関するコマンドレットによる一貫性のない主張。

これはすべてグラフAPIの動作方法によるものだと言われています。私の答えは、この種の問題を解決することでエンドユーザーから複雑さを隠すことは、ソフトウェアエンジニアリングの能力を超えていないということです。

GUID とユーザープリンシパル名

グラフ要求のオブジェクト識別は、グローバル一意識別子 (GUID) に依存します。すべてに GUID があります。グラフ要求と SDK コマンドレットはどちらも、GUID を使用して情報を検索します。ただし、一部の SDK コマンドレットでは、ユーザーアカウントを検索するときに GUID の代わりにユーザープリンシパル名を渡すことができます。たとえば、これは機能します:

Get-MgUser -UserId Tony.Redmond@office365itpros.com

アカウントの最新のサインインアクティビティの日付を含める場合を除きます。

Get-MgUser -UserId Tony.Redmond@office365itpros.com -Property signInActivity
Get-MgUser :
{"@odata.context":"http://reportingservice.activedirectory.windowsazure.com/$metadata#Edm.String","value":"Get By Key
only supports UserId and the key has to be a valid Guid"}

その理由は、サインインデータが別のソースから取得され、アカウントのサインインアクティビティを検索するために GUID が必要なため、コマンドを機能させるにはアカウントのオブジェクト識別子を渡す必要があるためです。

Get-MgUser -UserId "eff4cd58-1bb8-4899-94de-795f656b4a18" -Property signInActivity

どこでも GUID を使用する方が安全です。コマンドレットがオブジェクトになる可能性があり、ユーザープリンシパル名が変更される可能性があるため、ユーザープリンシパル名に依存しないでください。

Microsoft Graph PowerShell SDK の v2 の問題に対する修正はありません

Microsoft Graph PowerShell SDK の V2.0 がプレビュー段階になりました。良いニュースは、V2.0がいくつかの素晴らしい進歩をもたらすことです。悪いニュースは、ここで概説した弱点を治すために何もしないということです。私は、マイクロソフトが他のことをする前にSDKの根本的な問題を修正する必要があるという強い意見を表明しました。

多くの問題の根本的な原因は、Graph APIメタデータからMicrosoft Graph PowerShell SDKコマンドレットを生成するためにMicrosoftが使用するAutoRestプロセスであると言われています。岩と固い場所の間に挟まれているようです。SDK コマンドレットを使用すると大きなメリットが得られますが、コマンドレットを使用可能にするプロセスでは、独自の問題が発生します。Microsoft が AutoRest を修正 (または置き換え) し、予測できないコマンドレットの動作に対処するというフラストレーションのために残りの髪の毛が抜ける前に、PowerShell 標準により適した SDK を提供することを期待しましょう。

このような洞察は簡単には得られません。テクノロジーを知り、舞台裏を見る方法を理解する必要があります。の知識と経験から利益を得る IT プロフェッショナル向け Office 365 Office 365 とより広範な Microsoft 365 エコシステムをカバーする最高の電子書籍を購読することで、チームを組んでください。

Office

Posted by admin

マイクロソフトはYammerブランドをダンプします