Microsoft Graph を使用して PowerShell スクリプトをビルドする

このチュートリアルでは、Microsoft Graph API を使用してユーザーの代わりにデータにアクセスする PowerShell スクリプトを構築する方法について説明します。

注:

Microsoft Graph を使用してアプリ専用認証を使用してデータにアクセスする方法については、このアプリ専用認証チュートリアルを参照してください。

このチュートリアルの内容:

ヒント

このチュートリアルに従う代わりに、アプリの登録と構成を自動化するクイックスタートツールを使用して、完成したコードをダウンロードできます。ダウンロードしたコードは、変更を加えずに機能します。

GitHub リポジトリをダウンロードまたは複製し、README の指示に従ってアプリケーションを登録し、プロジェクトを構成することもできます。

前提条件

このチュートリアルを開始する前に、開発用コンピューターに PowerShell がインストールされている必要があります。 PowerShell 5.1 が最小要件ですが、PowerShell 7 をお勧めします。

また、Exchange Online メールボックスを持つ Microsoft の職場または学校アカウントも必要です。 Microsoft 365 テナントをお持ちでない場合は、 Microsoft 365 開発者プログラムを通じてテナントの資格を得る可能性があります。詳細については、 FAQ を参照してください。または、 1 か月間の無料試用版にサインアップするか、Microsoft 365 プランを購入することもできます。

注:

このチュートリアルは、PowerShell 7.2.2 および Microsoft Graph PowerShell SDK バージョン 1.9.5 で記述されています。このガイドの手順は、他のバージョンで動作する可能性がありますが、テストされていません。

ポータルでアプリを登録する

残り 20 分

この演習では、ユーザー認証を有効にするために、Azure Active Directory に新しいアプリケーションを登録します。アプリケーションは、Microsoft Entra 管理センターを使用するか、 Microsoft Graph PowerShell SDK を使用して登録できます。

ユーザー認証用にアプリケーションを登録する

このセクションでは、デバイスコードフローを使用したユーザー認証をサポートするアプリケーションを登録します。

注:

Microsoft Graph PowerShell SDK のユーザー認証用のアプリケーションの登録は省略可能です。 SDK には、独自のアプリケーション登録と対応するクライアント ID があります。ただし、独自のアプリケーション ID を使用すると、特定の PowerShell スクリプトのアクセス許可スコープをより詳細に制御できます。

Microsoft Entra 管理センター
PowerShell

ブラウザーを開き、 Microsoft Entra 管理センターに移動し、グローバル管理者アカウントを使用してログインします。
左側のナビゲーションで [Microsoft Entra ID] を 選択し、[ ID] を展開し、[ アプリケーション] を展開して、[ アプリの登録] を選択します。
[新規登録] を選択します。アプリケーションの名前 (例: Graph User Auth Tutorial) を入力します。

必要に応じて、[サポートされているアカウントの種類] を設定します。以下のオプションがあります:

オプション	サインインできるユーザー
この組織のディレクトリ内のアカウントのみ	Microsoft 365 組織内のユーザーのみ
組織のディレクトリ内のアカウント	Microsoft 365 組織内のユーザー (職場または学校アカウント)
任意の組織ディレクトリ ... のアカウント。個人の Microsoft アカウント	Microsoft 365 組織内のユーザー (職場または学校アカウント) と個人の Microsoft アカウント

[リダイレクト URI]を空のままにします。
[登録] を選択します。アプリケーションの [概要 ] ページで、 アプリケーション (クライアント) ID の値をコピーして保存します。次の手順で必要になります。 [サポートされているアカウントの種類] に対してのみこの組織ディレクトリの [アカウント] を選択した場合は、ディレクトリ (テナント) ID もコピーして保存します。
[管理] の下の [認証] を選択します。 [ 詳細設定 ] セクションを見つけて、[ パブリッククライアントフローを許可する] トグルを [はい] に変更し、[保存] を選択 します。

PowerShell を使用するには、Microsoft Graph PowerShell SDK が必要です。インストール手順については、「 Microsoft Graph PowerShell SDK のインストール」を参照してください。

重要

PowerShell スクリプトには、アプリケーション管理者、クラウドアプリケーション管理者、またはグローバル管理者ロールを持つ職場/学校アカウントが必要です。アカウントにアプリケーション開発者ロールがある場合は、Microsoft Entra 管理センターに登録できます。

RegisterAppForUserAuth.ps1という名前の新しいファイルを作成し、次のコードを追加します。

param(
  [Parameter(Mandatory=$true,
  HelpMessage="The friendly name of the app registration")]
  [String]
  $AppName,

  [Parameter(Mandatory=$false,
  HelpMessage="The sign in audience for the app")]
  [ValidateSet("AzureADMyOrg", "AzureADMultipleOrgs", `
  "AzureADandPersonalMicrosoftAccount", "PersonalMicrosoftAccount")]
  [String]
  $SignInAudience = "AzureADandPersonalMicrosoftAccount",

  [Parameter(Mandatory=$false)]
  [Switch]
  $StayConnected = $false
)

# Tenant to use in authentication.
# See https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-device-code#device-authorization-request
$authTenant = switch ($SignInAudience)
{
  "AzureADMyOrg" { "tenantId" }
  "AzureADMultipleOrgs" { "organizations" }
  "AzureADandPersonalMicrosoftAccount" { "common" }
  "PersonalMicrosoftAccount" { "consumers" }
  default { "invalid" }
}

if ($authTenant -eq "invalid")
{
  Write-Host -ForegroundColor Red "Invalid sign in audience:" $SignInAudience
  Exit
}

# Requires an admin
Connect-MgGraph -Scopes "Application.ReadWrite.All User.Read" -UseDeviceAuthentication -ErrorAction Stop

# Get context for access to tenant ID
$context = Get-MgContext -ErrorAction Stop

if ($authTenant -eq "tenantId")
{
  $authTenant = $context.TenantId
}

# Create app registration
$appRegistration = New-MgApplication -DisplayName $AppName -SignInAudience $SignInAudience `
 -IsFallbackPublicClient -ErrorAction Stop
Write-Host -ForegroundColor Cyan "App registration created with app ID" $appRegistration.AppId

# Create corresponding service principal
if ($SignInAudience -ne "PersonalMicrosoftAccount")
{
  New-MgServicePrincipal -AppId $appRegistration.AppId -ErrorAction SilentlyContinue `
   -ErrorVariable SPError | Out-Null
  if ($SPError)
  {
    Write-Host -ForegroundColor Red "A service principal for the app could not be created."
    Write-Host -ForegroundColor Red $SPError
    Exit
  }

  Write-Host -ForegroundColor Cyan "Service principal created"
}

Write-Host
Write-Host -ForegroundColor Green "SUCCESS"
Write-Host -ForegroundColor Cyan -NoNewline "Client ID: "
Write-Host -ForegroundColor Yellow $appRegistration.AppId
Write-Host -ForegroundColor Cyan -NoNewline "Auth tenant: "
Write-Host -ForegroundColor Yellow $authTenant

if ($StayConnected -eq $false)
{
  Disconnect-MgGraph | Out-Null
  Write-Host "Disconnected from Microsoft Graph"
}
else
{
  Write-Host
  Write-Host -ForegroundColor Yellow `
   "The connection to Microsoft Graph is still active. To disconnect, use Disconnect-MgGraph"
}

ファイルを保存します。
PowerShell を開き、現在のディレクトリを RegisterAppForUserAuth.ps1の場所に変更します。

次のコマンドを実行し、<audience-value> を目的の値に置き換えます (下の表を参照)。

.\RegisterAppForUserAuth.ps1 -AppName "Graph User Auth Tutorial" -SignInAudience <audience-value>

SignInAudience 値	サインインできるユーザー
`AzureADMyOrg`	Microsoft 365 組織内のユーザーのみ
`AzureADMultipleOrgs`	Microsoft 365 組織内のユーザー (職場または学校アカウント)
`AzureADandPersonalMicrosoftAccount`	Microsoft 365 組織内のユーザー (職場または学校アカウント) と個人の Microsoft アカウント
`PersonalMicrosoftAccount`	個人の Microsoft アカウントのみ

プロンプトに従ってブラウザーで https://microsoft.com/devicelogin を開き、指定されたコードを入力し、認証プロセスを完了します。
スクリプト出力から クライアント ID と 認証テナント の値をコピーします。これらの値は、次の手順で必要になります。
```
SUCCESS
Client ID: 2fb1652f-a9a0-4db9-b220-b224b8d9d38b
Auth tenant: common
```

注:

アプリの登録に対して Microsoft Graph のアクセス許可を構成していないことに注意してください。これは、サンプルで動的同意を使用して、ユーザー認証の特定のアクセス許可を要求するためです。

ユーザー認証を追加する

残り 17 分

このセクションでは、Microsoft Graph のユーザーとして PowerShell セッションを認証します。これは、Microsoft Graph を呼び出すために必要な OAuth アクセストークンを取得するために必要です。

Microsoft Graph PowerShell SDK には、対話型ブラウザーとデバイスコード認証の 2 つの認証方法が用意されています。対話型ブラウザー認証では、デバイスの既定のブラウザーを使用して、ユーザーがサインインできるようにします。デバイスコード認証では、既定のブラウザーがない環境での認証が許可されます。この演習では、デバイスコード認証を使用します。

重要

Microsoft Graph PowerShell SDK がまだインストールされていない場合は、先に進む前に今すぐインストールしてください。

ユーザーの認証

PowerShell を開き、次のコマンドを使用して $clientID セッション変数を設定し、 <our-client-id> をアプリ登録のクライアント ID に置き換えます。
```
$clientId = <your-client-id>
```
$tenantId セッション変数を設定します。アプリケーションの登録時に組織内のユーザーのみがサインインできるようにするオプションを選択した場合は、 <tenant-id> を組織のテナント ID に置き換えます。それ以外の場合は、を common に置き換えます。
```
$tenantId = <tenant-id>
```
$graphScopes セッション変数を設定します。
```
$graphScopes = "user.read mail.read mail.send"
```
現在の PowerShell セッション内でユーザーを認証するには、次のコマンドを使用します。
```
# Authenticate the user
Connect-MgGraph -ClientId $clientId -TenantId $tenantId -Scopes $graphScopes -UseDeviceAuthentication
```
ヒント

対話型ブラウザー認証を使用する場合は、 -UseDeviceAuthentication パラメーターを省略します。
ブラウザーを開き、表示された URL を参照します。指定したコードを入力し、サインインします。

重要

https://microsoft.com/deviceloginを参照するときにブラウザーにログインしている既存の Microsoft 365 アカウントに注意してください。プロファイル、ゲストモード、プライベートモードなどのブラウザー機能を使用して、テストに使用するアカウントとして認証することを確認します。

完了したら、PowerShell ウィンドウに戻ります。次のコマンドを実行して、認証されたコンテキストを確認します。

# Get the Graph context
Get-MgContext

ClientId              : 2fb1652f-a9a0-4db9-b220-b224b8d9d38b
TenantId              : 601faea3-be45-4960-898f-92b379b17cd9
CertificateThumbprint :
Scopes                : {Mail.Read, Mail.Send, openid, profile…}
AuthType              : Delegated
AuthProviderType      : DeviceCodeProvider
CertificateName       :
Account               : MeganB@contoso.com
AppName               : PowerShell Graph Tutorial
ContextScope          : CurrentUser
Certificate           :
PSHostVersion         : 2022.4.1
ClientTimeout         : 00:05:00

ユーザーを取得する

残り 12 分

このセクションでは、認証されたユーザーを取得します。

認証された PowerShell セッションで、次のコマンドを実行して現在のコンテキストを取得します。コンテキストは、認証されたユーザーを識別するための情報を提供します。
```
$context = Get-MgContext
```
次のコマンドを実行して、Microsoft Graph からユーザーを取得します。
```
# Get the authenticated user by UPN
$user = Get-MgUser -UserId $context.Account -Select 'displayName, id, mail, userPrincipalName'
```
ヒント

前のコマンドに切り替 -Debug を追加して、API の要求と応答を確認できます。

次のコマンドを実行して、ユーザー情報を出力します。

Write-Host "Hello," $user.DisplayName
# For Work/school accounts, email is in Mail property
# Personal accounts, email is in UserPrincipalName
Write-Host "Email:", ($user.Mail ?? $user.UserPrincipalName)

Hello, Megan Bowen!
Email: MeganB@contoso.com

コードの説明

認証されたユーザーを取得するために使用されるコマンドを検討してください。これは一見単純なコマンドですが、注意する必要がある重要な詳細がいくつかあります。

'me' へのアクセス

Get-MgUser コマンドは、Get user API に対する要求を作成します。この API には、次の 2 つの方法でアクセスできます。

GET /me
GET /users/{user-id}

Microsoft Graph PowerShell SDK では、 GET /me API エンドポイントはサポートされていません。 GEt /users/{user-id} エンドポイントを使用するには、{user-id} パラメーターの値を指定する必要があります。上の例では、 $context.Account 値が使用されています。この値には、認証されたユーザーのユーザープリンシパル名 (UPN) が含まれます。

特定のプロパティの要求

関数は、コマンドの -Select パラメーターを使用して、必要なプロパティのセットを指定します。これにより、 $select クエリパラメーターが API 呼び出しに追加されます。

厳密に型指定された戻り値の型

関数は、API からの JSON 応答から逆シリアル化された MicrosoftGraphUser オブジェクトを返します。コマンドは -Selectを使用するため、返されるオブジェクトには要求されたプロパティのみが値を持ちます。その他のすべてのプロパティには既定値が設定されます。

受信トレイを一覧表示する

残り 10 分

このセクションでは、ユーザーのメール受信トレイにメッセージを一覧表示します。

認証された PowerShell セッションで、 $user 変数が設定されていることを確認します。
```
PS > $user.DisplayName
Megan Bowen
```

次のコマンドを実行して、ユーザーの受信トレイを一覧表示します。

Get-MgUserMailFolderMessage -UserId $user.Id -MailFolderId Inbox -Select `
  "from,isRead,receivedDateTime,subject" -OrderBy "receivedDateTime DESC" `
  -Top 25 | Format-Table Subject,@{n='From';e={$_.From.EmailAddress.Name}}, `
  IsRead,ReceivedDateTime

出力を確認します。

Subject                                    From                    IsRead ReceivedDateTime
-------                                    ----                    ------ ----------------
Updates from Ask HR and other communities  Contoso Demo on Yammer  False  4/19/2022 10:19:02 PM
Employee Initiative Thoughts               Patti Fernandez         False  4/19/2022 3:15:56 PM
Voice Mail (11 seconds)                    Alex Wilber             False  4/18/2022 2:24:16 PM
Our Spring Blog Update                     Alex Wilber             True   4/18/2022 1:52:03 PM
Atlanta Flight Reservation                 Alex Wilber             False  4/13/2022 2:30:27 AM
Atlanta Trip Itinerary - down time         Alex Wilber             False  4/12/2022 4:46:01 PM

コードの説明

ユーザーの受信トレイを一覧表示するために使用されるコマンドを検討してください

既知のメールフォルダーへのアクセス

Get-MgUserMailFolderMessage コマンドは、特に GET /users/{user-id}/mailFolders/{folder-id}/messages エンドポイントを使用して、List messages API への要求を作成します。このエンドポイントを使用すると、API は要求されたメールフォルダー内のメッセージのみを返します。この場合、受信トレイはユーザーのメールボックス内の既定の既知のフォルダーであるため、既知の名前である -MailFolderId Inboxを使用してアクセスできます。既知の名前をメールフォルダーの ID プロパティに置き換えることで、既定以外のフォルダーにも同じ方法でアクセスします。使用可能な既知のフォルダー名の詳細については、「 mailFolder リソースの種類」を参照してください。

コレクションへのアクセス

1 つのオブジェクトを返す前のセクションの Get-MgUser コマンドとは異なり、このメソッドはメッセージのコレクションを返します。コレクションを返す Microsoft Graph のほとんどの API では、使用可能なすべての結果が 1 つの応答で返されるわけではありません。代わりに、ページングを使用して結果の一部を返しながら、クライアントが次の "ページ" を要求するメソッドを提供します。

既定のページサイズ

ページングを使用する API では、既定のページサイズが実装されます。メッセージの場合、既定値は 10 です。クライアントは、 $top クエリパラメーターを使用して、より多く (またはそれ以下) を要求できます。 Microsoft Graph PowerShell SDK では、これは -Top 25 パラメーターを使用して実現されます。

注:

-Top経由で渡される値は、明示的な数値ではなく、上限です。 API は、指定した値までのメッセージ数を返します。

コレクションを並べ替える

関数は、要求で -OrderBy パラメーターを使用して、メッセージの受信時刻 (receivedDateTime プロパティ) で並べ替えられた結果を要求します。 DESC キーワードが含まれているため、最近受信したメッセージが最初に一覧表示されます。これにより、 $orderby クエリパラメーターが API 呼び出しに追加されます。

メールを送信する

残り 8 分

このセクションでは、認証されたユーザーとして電子メールメッセージを送信します。

認証された PowerShell セッションで、 $user 変数が設定されていることを確認します。
```
PS > $user.DisplayName
Megan Bowen
```

次のコマンドを使用して、メール送信 API の要求本文を表すオブジェクトを定義します。

$sendMailParams = @{
    Message = @{
        Subject = "Testing Microsoft Graph"
        Body = @{
            ContentType = "text"
            Content = "Hello world!"
        }
        ToRecipients = @(
            @{
                EmailAddress = @{
                    Address = ($user.Mail ?? $user.UserPrincipalName)
                }
            }
        )
    }
}

メッセージを送信するには、次のコマンドを使用します。
```
Send-MgUserMail -UserId $user.Id -BodyParameter $sendMailParams
```
注:

Microsoft 365 開発者プログラムの開発者テナントでテストしている場合は、送信したメールが配信されず、配信不能レポートが届く場合があります。このような場合は、 Microsoft 365 管理センターからサポートにお問い合わせください。
メッセージが受信されたことを確認するには、前の手順の Get-MgUserMailFolderMessage コマンドを繰り返します。

コードの説明

メッセージの送信に使用するコマンドを検討してください。

メールの送信

Send-MgUserMail コマンドは、メール送信 API への要求を作成します。

オブジェクトの作成

データのみを読み取る Microsoft Graph の以前の呼び出しとは異なり、この呼び出しではデータが作成されます。これを SDK で行うには、要求本文を表すオブジェクトを作成し、目的のプロパティを設定してから、 BodyParameter パラメーターに渡します。

省略可能: 独自のコードを追加する

残り 5 分

このセクションでは、独自の Microsoft Graph PowerShell SDK コマンドを使用します。これは、Microsoft Graph ドキュメントまたは Graph エクスプローラーのコードスニペット、または作成したコードです。このセクションは省略可能です。

API を選択する

試したい API を Microsoft Graph で見つけます。たとえば、 Create イベント API です。 API ドキュメントの例のいずれかを使用するか、Graph Explorer で API 要求をカスタマイズし、生成されたスニペットを使用するか、 Find-MgGraphCommand コマンドを使用して対応するコマンドを見つけることができます。

たとえば、イベントを作成する API エンドポイントの 1 つが POST /users/{id | userPrincipalName}/events。これを使用して、対応する PowerShell コマンドを見つけることができます。

PS > Find-MgGraphCommand -Uri "/users/{id | userPrincipalName}/events" -Method "POST"

   APIVersion: v1.0

Command         Module   Method URI                     OutputType           Permissions           Variants
-------         ------   ------ ---                     ----------           -----------           --------
New-MgUserEvent Calendar POST   /users/{user-id}/events IMicrosoftGraphEvent {Calendars.ReadWrite} {Create1, CreateExp…

   APIVersion: beta

Command         Module   Method URI                     OutputType            Permissions           Variants
-------         ------   ------ ---                     ----------            -----------           --------
New-MgUserEvent Calendar POST   /users/{user-id}/events IMicrosoftGraphEvent1 {Calendars.ReadWrite} {Create, CreateExp…

出力は、 New-MgUserEvent コマンドが対応するコマンドであることを示します。

アクセス許可を構成する

選択した API のリファレンスドキュメントの [アクセス許可] セクションを確認して、サポートされている認証方法を確認します。たとえば、一部の API では、ユーザー (委任された) 認証や個人の Microsoft アカウントがサポートされていません。

現在のセッション (Disconnect-MgGraph) を切断し、 -Scopes パラメーターで必要なアクセス許可に再接続します。

ヒント

Connect-MgGraph コマンドで -ForceRefresh パラメーターを使用すると、新しく構成されたアクセス許可が確実に適用されます。

コマンドを実行する

必要なアクセス許可に接続したら、選択したコマンドを実行します。

おめでとうございます。

100% 完了しました

PowerShell Microsoft Graph チュートリアルを完了しました。 Microsoft Graph を呼び出す作業アプリが作成されたので、新しい機能を試して追加できます。

Microsoft Graph PowerShell SDK でアプリのみの認証を使用する方法について説明します。
Microsoft Graph でアクセスできるすべてのデータについては、 Microsoft Graph の概要に関するページを参照してください。

次の方法で共有

前提条件

ポータルでアプリを登録する

ユーザー認証用にアプリケーションを登録する

ユーザー認証を追加する

ユーザーの認証

ユーザーを取得する

コードの説明

'me' へのアクセス

特定のプロパティの要求

厳密に型指定された戻り値の型

受信トレイを一覧表示する

コードの説明

既知のメール フォルダーへのアクセス

コレクションへのアクセス

既定のページ サイズ

コレクションを並べ替える

メールを送信する

コードの説明

メールの送信

オブジェクトの作成

省略可能: 独自のコードを追加する

API を選択する

アクセス許可を構成する

コマンドを実行する

おめでとうございます。

既知のメールフォルダーへのアクセス

既定のページサイズ