使用 Microsoft Graph 建置 PowerShell 腳本
本教學課程會教導您如何建置 PowerShell 腳本,以使用 Microsoft 圖形 API 代表使用者存取數據。
注意
若要瞭解如何使用 Microsoft Graph 來存取使用僅限應用程式驗證的數據,請參閱本 僅限應用程式的驗證教學課程。
在本教學課程中,您將:
提示
除了遵循本教學課程,您可以透過 快速入 門工具下載已完成的程序代碼,以自動化應用程式註冊和設定。 下載的程式代碼不需要修改即可運作。
您也可以下載或複製 GitHub 存放庫 ,並遵循自述檔中的指示來註冊應用程式並設定專案。
必要條件
開始本教學課程之前,您應該已在開發計算機上安裝 PowerShell 。 PowerShell 5.1 是最低需求,但建議使用 PowerShell 7。
您也應該有具有 Exchange Online 信箱Microsoft公司或學校帳戶。 如果您沒有Microsoft 365 租使用者,您可能有資格透過 Microsoft 365 開發人員計劃;如需詳細資訊,請參閱 常見問題。 或者,您可以 註冊 1 個月的免費試用版,或購買Microsoft 365 方案。
注意
本教學課程是使用 PowerShell 7.2.2 和 Microsoft Graph PowerShell SDK 1.9.5 版所撰寫。 本指南中的步驟可能適用於其他版本,但尚未經過測試。
在入口網站中註冊應用程式
在此練習中,您將在 Azure Active Directory 中註冊新的應用程式,以啟用 用戶驗證。 您可以使用 Microsoft Entra 系統管理中心或使用 Microsoft Graph PowerShell SDK 來註冊應用程式。
註冊應用程式以進行用戶驗證
在本節中,您將使用 裝置程式代碼流程註冊支援使用者驗證的應用程式。
注意
為 Microsoft Graph PowerShell SDK 註冊應用程式以進行使用者驗證是選擇性的。 SDK 有自己的應用程式註冊和對應的用戶端標識碼。 不過,使用您自己的應用程式識別碼可讓您更充分地控制特定 PowerShell 腳本的許可權範圍。
開啟瀏覽器並流覽至 Microsoft Entra 系統管理中心 ,並使用全域系統管理員帳戶登入。
選Microsoft左側導覽中的 [Entra ID ],依序展開 [ 身分識別]、[ 應用程式],然後選取 [ 應用程式註冊]。
選取 [新增註冊]。 輸入應用程式名稱,例如
Graph User Auth Tutorial
。視需要設定 支持的帳戶類型 。 選項如下:
選項 誰可以登入? 僅限此組織目錄中的帳戶 只有您Microsoft 365 組織中的使用者 任何組織目錄中的帳戶 任何Microsoft 365 組織中的使用者 (公司或學校帳戶) 任何組織目錄中的帳戶...和個人Microsoft帳戶 任何Microsoft 365 組織中的使用者 (公司或學校帳戶) 和個人Microsoft帳戶 將 [重新導向 URI ] 保留空白。
選取 [登錄]。 在應用程式的 [ 概觀] 頁面上,將應用程式 (用戶端的值複製 ) 標識 符並加以儲存,您將在下一個步驟中加以儲存。 如果您只針對支持的帳戶類型選擇 [此組織目錄中的帳戶],也請複製 [目錄 (租使用者) 標識符並加以儲存。
選取管理下的驗證。 找出 [ 進階設定] 區 段,並將 [ 允許公用用戶端流程 ] 切換為 [ 是],然後選擇 [ 儲存]。
注意
請注意,您未在應用程式註冊上設定任何 Microsoft Graph 許可權。 這是因為範例會使用 動態同意 來要求使用者驗證的特定許可權。
新增用戶驗證
在本節中,您會以Microsoft Graph 的使用者身分驗證 PowerShell 會話。 這是取得必要的 OAuth 存取令牌以呼叫 Microsoft Graph 的必要專案。
Microsoft Graph PowerShell SDK 提供兩種使用者驗證驗證方法:互動式瀏覽器和裝置程式代碼驗證。 互動式瀏覽器驗證會使用裝置的預設瀏覽器來允許使用者登入。 裝置程式代碼驗證允許在沒有預設瀏覽器的環境中進行驗證。 在此練習中,您將使用裝置程式代碼驗證。
重要
如果您尚未安裝 Microsoft Graph PowerShell SDK,請在繼續之前立即 安裝它 。
驗證使用者
開啟 PowerShell 並使用下列命令來設定
$clientID
工作階段變數,並將 your-client-id> 取代<為應用程式註冊的用戶端識別碼。$clientId = <your-client-id>
$tenantId
設定會話變數。 如果您選擇只允許組織中的使用者在註冊應用程式時登入的選項,請將tenant-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
取得使用者
在本節中,您會取得已驗證的使用者。
在已驗證的 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
會建置對 取得使用者 API 的要求。 此 API 有兩種方式可供存取:
GET /me
GET /users/{user-id}
Microsoft圖形 PowerShell SDK 不支援 GET /me
API 端點。 若要使用 GEt /users/{user-id}
端點,我們必須提供 參數的 {user-id}
值。 在上述範例中 $context.Account
,會使用 值。 此值包含已驗證使用者的用戶主體名稱, (UPN) 。
要求特定屬性
函式會使用 -Select
命令上的 參數來指定所需的屬性集。 這會將 $select查詢參數 新增至 API 呼叫。
強型別傳回型別
函式會傳回 MicrosoftGraphUser
從 API 的 JSON 回應還原串行化的物件。 因為命令使用 -Select
,所以只有要求的屬性在傳回的物件中會有值。 所有其他屬性都會有預設值。
清單收件匣
在本節中,您會列出用戶電子郵件收件匣中的訊息。
在已驗證的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
會建置對 列出訊息 API 的要求,特別是使用 GET /users/{user-id}/mailFolders/{folder-id}/messages
端點。 使用該端點時,API 只會傳回所要求郵件資料夾中的訊息。 在此情況下,由於收件匣是使用者信箱內的預設已知資料夾,因此可透過其已知名稱存取: -MailFolderId Inbox
。 非預設資料夾的存取方式相同,方法是將已知名稱取代為郵件資料夾的ID屬性。 如需可用已知資料夾名稱的詳細資訊,請參閱 mailFolder 資源類型。
存取集合
不同於 Get-MgUser
上一節中傳回單一物件的命令,這個方法會傳回訊息的集合。 Microsoft Graph 中傳回集合的大部分 API 不會在單一回應中傳回所有可用的結果。 相反地,他們會使用 分頁 來傳回部分結果,同時提供方法讓用戶端要求下一個「頁面」。
默認頁面大小
使用分頁的 API 會實作預設頁面大小。 對於訊息,預設值為10。 用戶端可以使用 $top 查詢參數來要求更多 (或更少 ) 。 在 Microsoft Graph PowerShell SDK 中,這是使用 -Top 25
參數來完成。
注意
透過 -Top
傳遞的值是上限,而不是明確的數位。 API 會傳回一些訊息 ,最多可達 指定的值。
排序集合
函式會在要求上使用 -OrderBy
參數,要求依收到訊息的時間排序結果, (receivedDateTime
屬性) 。 它包含 DESC
關鍵詞,因此會先列出最近收到的訊息。 這會將 $orderby查詢參數 新增至 API 呼叫。
傳送郵件
在本節中,您會以已驗證的使用者身分傳送電子郵件訊息。
在已驗證的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
。
選擇性:新增您自己的程序代碼
在本節中,您將使用自己的 Microsoft Graph PowerShell SDK 命令。 這可能是來自 Microsoft Graph 檔 或 Graph 總管的代碼段,或您所建立的程式碼。 此區段為選擇性。
選擇 API
在您想要嘗試Microsoft圖形中尋找 API。 例如, 建立事件 API。 您可以使用 API 檔中的其中一個範例、在 Graph 總管中自定義 API 要求,並使用產生的代碼段,或使用 Find-MgGraphCommand
命令來尋找對應的命令。
例如,要建立事件的其中一個 API 端點是 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
必要許可權重新連線。
提示
使用 參數 -ForceRefresh
搭配 Connect-MgGraph
命令可確保套用新設定的許可權。
執行命令
現在您已連線到必要的許可權,請執行您選擇的命令。
恭喜!
您已完成 PowerShell Microsoft Graph 教學課程。 既然您有一個可呼叫 Microsoft Graph 的工作應用程式,您可以實驗並新增新功能。
- 瞭解如何搭配使用 僅限應用程式驗證 與 Microsoft Graph PowerShell SDK。
- 請造訪 Microsoft Graph 概觀 ,以查看您可以使用 Microsoft Graph 存取的所有數據。
在這個區段有遇到問題嗎? 如果有,請提供意見反應,好讓我們可以改善這個區段。