如何从 PowerShell 连接到 Microsoft Graph API？

介绍

Microsoft Graph API 是一种 RESTful Web API，它整合了对各种 Microsoft 365 服务的访问，使开发人员能够创建与跨多个平台（包括 Azure Active Directory、SharePoint、OneDrive、Outlook 等）的数据进行交互的应用程序。 Microsoft Graph PowerShell 适用于所有平台，包括 Windows、macOS 和 Linux。支持现代身份验证。 PowerShell 是一种广泛使用的脚本语言和自动化工具，可用于连接 Graph API 并与之交互，使其成为 IT 专业人员的一项基本技能。在本初学者指南中，我们将全面概述 Graph API，讨论连接到它的先决条件、安装和配置、身份验证，以及使用 PowerShell 连接到 Graph API 的分步指南，并提供示例以及沿途的解释。

安装 Microsoft.Graph PowerShell 模块

首先，您需要安装 Microsoft Graph PowerShell 模块。该模块提供了一组 cmdlet，允许您与 Graph API 进行交互。在提升的 PowerShell 会话中运行以下命令：

使用以下 PowerShell 命令检查是否已安装 Microsoft Graph PowerShell 模块：

Get-InstalledModule | Where-Object {$_.Name -match "Microsoft.Graph"}

安装 Microsoft Graph PowerShell 模块：

Install-Module -Name "Microsoft.Graph"

要为当前用户范围安装 Microsoft graph PowerShell SDK：

Install-Module Microsoft.Graph -Scope CurrentUser

这将安装 Microsoft Graph 和子模块（截至目前有 38 个）。等待安装完成。

更新 Microsoft Graph PowerShell 模块

要更新现有模块，请使用以下命令：

Update-Module Microsoft.Graph

卸载 Microsoft Graph PowerShell 模块

Microsoft Graph 有一个主模块和多个子模块。要卸载Graph模块，我们必须先卸载主模块：

Uninstall-Module Microsoft.Graph

然后卸载Microsoft Graph的所有子模块。最后必须卸载身份验证模块，因为其他模块依赖于它。

#Uninstall all Sub-modules of Graph
Get-InstalledModule Microsoft.Graph.* | ForEach-Object { if($_.Name -ne "Microsoft.Graph.Authentication") {
    Uninstall-Module $_.Name } 
}

#Uninstall the dependant module
Uninstall-Module Microsoft.Graph.Authentication

如何使用PowerShell调用Graph API？

安装 Microsoft.Graph 模块后，您可以开始使用 Graph API 来执行各种任务。它支持委派访问（用户可以登录并同意），以及无人值守场景的仅应用程序访问。使用 Connect-MgGraph 命令通过所需的范围登录。连接后，您可以调用任何可用的 Graph API 方法。

方法 1：通过 PowerShell 的委派访问连接到 Graph API

您将使用委派访问权限以用户身份登录，同意 SDK 代表您执行所需的范围，并调用 Microsoft Graph。以下是使用 PowerShell 获取用户信息的示例：

#Connect to Microsoft Graph
Connect-MgGraph -Scopes "User.Read.All"

#Get All users
$users = Get-MgUser
$users | Select-Object DisplayName, UserPrincipalName, Mail

这将提示进行身份验证，您需要使用管理员帐户登录以同意所需的范围。

连接后，该命令将通过 Welcome To Microsoft Graph! 消息指示成功。 Get-MgUser 命令输出 Microsoft 365 组织中的用户列表。

如果您想连接到 Graph API 的 Beta 版本，请使用 Select-MgProfile -Name "beta" cmdlet。这是获取用户上次登录日期和时间戳的另一个示例：

#Connect to Microsoft Graph
Connect-MgGraph -Scopes "AuditLog.Read.All", "User.Read.All"

#Set the Graph Profile
Select-MgProfile -Name "beta"

#Properties to Retrieve
$Properties = @(
    'Id','DisplayName','UserPrincipalName','UserType', 'AccountEnabled', 'SignInActivity'    
)

#Get All users along with the properties
$AllUsers = Get-MgUser -All -Property $Properties

$SigninLogs = @()
ForEach ($User in $AllUsers)
{
    $SigninLogs += [PSCustomObject][ordered]@{
            LoginName       = $User.UserPrincipalName
            DisplayName     = $User.DisplayName
            UserType        = $User.UserType
            AccountEnabled  = $User.AccountEnabled
            LastSignIn      = $User.SignInActivity.LastSignInDateTime
    }
}

$SigninLogs

#Disconnect MS Graph
Disconnect-MgGraph

同样，要使用 Microsoft Graph API 连接到 SharePoint Online 网站，请使用以下 PowerShell：

#Parameters
$SiteID = "0defaa16-1fc5-4a55-bbec-a06d10de2a42"

#Connect to Microsoft Graph
Connect-MgGraph -Scopes "Sites.FullControl.All"

#Get a SharePoint Site collection
$Site = Get-MGSite -SiteId $SiteId

#Get All document libraries from the site
Get-MgSiteDrive -SiteId $SiteId

将 Microsoft Graph API 与 PowerShell 结合使用的示例

让您了解 Microsoft Graph API 和 PowerShell 的功能。您也可以执行批量操作。这里有一些例子：

• 要获取上下文，请使用：Get-MgContext
• 检索 Office 365 中所有用户的列表：Get-MgUser
• 创建新的 SharePoint 网站：New-MgSite
• 检索特定用户的所有 OneDrive 文件的列表：Get-MgDriveItem -DriveId -DriveItemId

如您所见，Microsoft Graph API 和 PowerShell 具有无限的可能性。

查找图形命令所需的权限范围

我们用于连接 Microsoft Graph 的登录用户或客户端 ID 必须有权访问特定范围。例如，如果您想使用 Update-MgUser 命令更新用户配置文件，您可以使用“User.ReadWrite.All”范围来执行此操作。要查找所需的范围，请使用 Find-MgGraphCommand cmdlet。例如。，

Find-MgGraphCommand -command Update-MgUser | Select -First 1 -ExpandProperty Permissions

要获取 Microsoft Graph PowerShell 模块中所有可用的 cmdlet，您可以使用以下命令：

Get-command -Module Microsoft.Graph*

Microsoft Graph 1.25 版本中有 9275 个可用的 cmdlet！

方法 2：使用 PowerShell 中的 App ID 连接到 Graph API

在我们开始之前，您需要满足一些先决条件：

1. 您需要在 Azure AD 中注册应用程序。
2. 您需要授予应用程序访问 Graph API 的权限。
3. 将证书或客户端密钥添加到应用程序 ID。该证书可以是自签名的或来自权威机构的。

在 Azure AD 中注册应用程序

在使用 PowerShell 连接到 Graph API 之前，必须在 Azure AD 中注册应用程序以获得必要的权限和凭据。

要在 Azure AD 中注册应用程序，请执行以下步骤：

1. 登录 Azure AD 门户 (https://aad.portal.azure.com/)。

2. 单击左侧菜单中的“Azure Active Directory”>> 单击“应用程序注册”>> 单击“新注册”。

   

3. 输入应用程序的名称，然后选择“仅限此组织目录中的帐户”作为支持的帐户类型。

   

4. 点击“注册”。

注册应用程序后，您将被重定向到应用程序的仪表板。记下“应用程序（客户端）ID”和“目录（租户）ID”，因为我们稍后会需要它们。

授予应用程序权限

要访问 Graph API，您的应用程序必须具有适当的权限。要向应用程序授予权限，请执行以下步骤：

1. 在您创建的应用程序的左侧菜单中单击“API 权限”>> 单击“添加权限”。

   

2. 选择“Microsoft Graph”作为 API。

   

3. 搜索并选择所需的权限（例如，“Sites.FullControl.All”用于获得对所有 SharePoint Online 网站的完全控制）。

   

4. 单击“添加权限”。

5. 单击“授予>单击“证书和秘密”>>单击“证书”选项卡。

6. 点击“上传证书”。

7. 浏览到生成的 CER 文件，然后单击“添加”按钮。

   

8. 记下“指纹”。这是与证书关联的安全密钥，用于对应用程序进行身份验证。

将客户端密钥添加到应用程序

同样，要将客户端密钥添加到应用程序，请执行以下操作：

1. 单击“证书和机密”>>单击“客户端机密”选项卡，然后单击“新客户端机密”。

2. 设置“描述”和“过期”有效期。完成后，单击“添加”。

   

3. 记下客户端密钥，我们将使用它来连接到 Graph API。

   

使用证书从 PowerShell 连接到具有 App ID 的 Graph API

现在我们已经注册了一个应用程序并授予了权限，并向其添加了客户端密钥和证书。我们已准备好从 PowerShell 连接到 Graph API。以下是使用证书指纹连接到 Microsoft Graph API 的方法：

#Parameters for Tenant ID and Client ID
$TenantID = "c1c2b173-4240-4775-a49a-6351b30cd2f6"
$ClientID = "3c1540f7-9565-4aae-b398-f47ac91cfc06" #App ID
$CertThumbPrint = "63FDD807AE01C1EB34CE5647D164E3C153C0FA7"

#Connect to Microsoft Graph using App
Connect-MgGraph -ClientID $ClientID -TenantId $TenantID -CertificateThumbprint $CertThumbPrint

使用客户端密钥连接到 Graph API

如果您想使用客户端密钥，这里是适合您的 PowerShell 脚本！

#App Registration details
$TenantID = "c1c2b173-4240-4775-a49a-6351b30cd2f6"
$ClientID = "3c1540f7-9565-4aae-b398-f47ac91cfc06"
$ClientSecret = "9Ad2Q~DA-yLotNvvaplkchnnf__6D5zdFJi1mb4l"

$Body =  @{
    Grant_Type    = "client_credentials"
    Scope         = "https://graph.microsoft.com/.default"
    Client_Id     = $ClientID
    Client_Secret = $ClientSecret
}

$Connection = Invoke-RestMethod `
    -Uri https://login.microsoftonline.com/$TenantID/oauth2/v2.0/token `
    -Method POST `
    -Body $body

#Get the Access Token 
$Token = $Connection.access_token

#Connect to Microsoft Graph 
Connect-MgGraph -AccessToken $Token

Microsoft Graph cmdlet 是 Rest API 调用的包装器。您还可以调用 Invoke-Webrequests 方法来与任何底层 REST API 方法进行交互。

#App Registration details
$TenantID = "c1c2b173-4240-4775-a49a-6351b30cd2f6"
$ClientID = "3c1540f7-9565-4aae-b398-f47ac91cfc06"
$ClientSecret = "9dd8Q~DA-yLotavvabkchnnf__6c5VdFJi0mb1l"
$Domain = "Crescent"

$Body =  @{
    Grant_Type    = "client_credentials"
    Scope         = "https://graph.microsoft.com/.default"
    Client_Id     = $ClientID
    Client_Secret = $ClientSecret
}

$Connection = Invoke-RestMethod `
    -Uri https://login.microsoftonline.com/$TenantID/oauth2/v2.0/token `
    -Method POST `
    -Body $body

#Get the Access Token 
$AuthHeader = @{
'Authorization'="Bearer $($Connection.access_token)"
}

#Get all sites
$URI = "https://graph.microsoft.com/v1.0/sites"
$WebRequest = Invoke-WebRequest -Headers $AuthHeader -Uri $URI
$Result = ($WebRequest.Content | ConvertFrom-Json).Value

#Get all site collections of the domain
$Result | Where {$_.siteCollection.Hostname -eq "$Domain.sharepoint.com"} | select name,webUrl,id

图形浏览器

对于初学者来说，为任务找到正确的 API 方法可能具有挑战性。您可以使用 Graph Explore 或 Rest API Reference 作为起点。

常见错误和故障排除提示

虽然通过 PowerShell 使用 Azure AD Graph API 和 Microsoft Graph API 通常很简单，但您可能会遇到一些常见错误。一种常见错误是“远程服务器返回错误：(401) 未经授权。”您还可能会收到“没有足够的权限来完成操作”。这通常意味着您的凭据不正确，或者您没有访问 Graph API 的适当权限。仔细检查您的凭据和权限以确保它们正确。

另一个常见错误是“术语‘cmdlet 名称’未被识别为 cmdlet 的名称。”这通常意味着未安装或加载适当的 PowerShell 模块。确保您已为您尝试使用的 cmdlet 安装并加载了适当的模块。

结论

在本初学者指南中，我们介绍了使用 PowerShell 连接到 Microsoft Graph API 的基本知识，从设置环境和身份验证到进行 API 调用。我们还了解了如何在 Azure AD 中注册应用程序、向其授予权限以及向应用程序添加客户端密钥。借助本指南中获得的知识，您可以开始自动化任务并更有效地管理 Microsoft 365 环境。

接下来的步骤可能是探索 Microsoft Graph API PowerShell 模块提供的更多 cmdlet，或者开始构建自己的 PowerShell 脚本来自动执行常见任务。可能性是无限的，所以今天就开始吧！

经常问的问题：

Microsoft Graph 的用途是什么？

Microsoft Graph API 是一个统一的 RESTful API 端点，使开发人员能够访问 Microsoft 云中提供的数据、情报和服务并与之交互。它充当跨多个 Microsoft 服务（如 Office 365、Azure Active Directory、企业移动性和安全、Windows 等等。

如何在 PowerShell 中安装 Microsoft Graph？

要安装 Microsoft Graph PowerShell SDK，请在 PowerShell 会话中运行以下命令：

Install-Module -Name Microsoft.Graph

此命令安装 Microsoft.Graph 模块，提供用于与 PowerShell 中的 Microsoft Graph API 交互的 cmdlet。

Microsoft Graph PowerShell 需要哪些权限？

这取决于您要访问的具体 API 端点和资源！一般来说，Microsoft Graph 中有两种类型的权限：
1.委派权限：代表登录用户进行操作。
2.应用程序权限：这些权限授予无需用户交互即可运行的应用程序，例如后台服务。
您需要在 Azure 门户中注册应用程序，为应用程序分配权限，授予管理员同意，然后使用注册的应用程序的权限PowerShell 脚本中的凭据。

为什么我们应该转向 Microsoft Graph API PowerShell SDK？

因为 AzureAD、MSOnline 和 AzureADPreview PowerShell 模块已计划弃用。为了做好准备，管理员应该开始使用新的 Microsoft Graph PowerShell SDK 模块。