快速入门：使用 PowerShell 和 Visual Studio Code 的 Web API

了解如何在 Visual Studio Code 中将 PowerShell 与 Dataverse Web API 配合使用。 PowerShell 是一种功能强大的脚本语言，可以自动执行重复任务并简化工作流，使其成为与 Dataverse 集成的理想工具。本快速入门帮助你开始在 Visual Studio Code 中将 PowerShell 与 Dataverse Web API 配合使用。使用 PowerShell 的 Visual Studio Code 提供了使用 Postman 或 Insomnia 等 API 客户端的替代方法。

在此快速入门中，您将学习如何：

在 PowerShell 中使用 Visual Studio Code 以交互方式通过 Dataverse 进行身份验证，而无需注册应用程序。
使用 PowerShell Invoke-RestMethod cmdlet 编写对 Dataverse Web API 的请求。

注释

本快速入门仅介绍基本概念。此简介足以用于基本测试。完成本文中的步骤后，请转到将 PowerShell 和 Visual Studio Code 与 Dataverse Web API 配合使用，了解有关提高工作效率的更高级功能，例如如何：

本文中的说明适用于 Windows、Linux 和 macOS，但这些步骤仅在 Windows 上进行测试。如果需要更改，请使用本文底部的 “反馈 ”部分告知我们。

先决条件

如果不确认满足以下每个先决条件，请不要继续操作。

安装或验证是否已安装以下内容

安装 Visual Studio Code。请参阅 Download Visual Studio Code
安装适用于 Visual Studio Code 的 PowerShell 扩展。请参阅 PowerShell for Visual Studio Code
安装 PowerShell 7.4 或更高版本。请参阅在 Windows、Linux 和 macOS 上安装 PowerShell
安装 Az PowerShell 模块版本 11.1.0 或更高版本。请参阅如何安装 Azure PowerShell

若要将现有安装更新到最新版本，请使用 Update-Module -Name Az -Force

验证安装

打开Visual Studio代码。
在“终端”菜单中，选择“新终端”。
在 Visual Studio Code 导航窗格中，选择 PowerShell 扩展的图标。

在Visual Studio Code终端窗口中复制并粘贴以下脚本：

Write-Host 'PowerShell Version:'$PSVersionTable.PSVersion.ToString()
Write-Host 'PowerShell Az version:'(Get-InstalledModule Az).Version

按 Enter。输出应如下所示：

PowerShell Version: 7.4.0
PowerShell Az version: 11.1.0

如果未看到如下所示的结果，请安装或更新必备组件。

还需要

Dataverse 环境的有效用户帐户
要连接到的 Dataverse 环境的 URL。请参阅 “查看开发人员资源 ”，了解如何查找它。它看起来如下所示：https://yourorg.crm.dynamics.com/，其中 yourorg.crm 不同。
基本了解 PowerShell 脚本语言

试用

在 Visual Studio Code 中，选择“ 文件>新建文本文件”，或按 Ctrl+N 打开新文件。

无需保存文件。

将以下脚本复制并粘贴到新文件中。

$environmentUrl = 'https://yourorg.crm.dynamics.com/' # change this
## Login if not already logged in
if ($null -eq (Get-AzTenant -ErrorAction SilentlyContinue)) {
   Connect-AzAccount | Out-Null
}

# Get an access token
$secureToken = (Get-AzAccessToken `
   -ResourceUrl $environmentUrl `
   -AsSecureString).Token

# Convert the secure token to a string
$token = ConvertFrom-SecureString `
   -SecureString $secureToken `
   -AsPlainText


# Common headers
$baseHeaders = @{
   'Authorization'    = 'Bearer ' + $token
   'Accept'           = 'application/json'
   'OData-MaxVersion' = '4.0'
   'OData-Version'    = '4.0'
}
# Invoke WhoAmI Function
Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Method Get -Headers $baseHeaders
| ConvertTo-Json

Visual Studio Code 应自动检测它是 PowerShell 脚本。

编辑 $environmentUrl 变量值 (https://yourorg.crm.dynamics.com/)，使其与您的 Dataverse 环境 URL 匹配。
按 F5，或使用 Visual Studio Code 运行>“开始调试 ”菜单命令。

此时会打开浏览器窗口。在浏览器窗口中，输入或选择要用于进行身份验证的凭据。

验证 Visual Studio Code 终端窗口中的输出。

在终端底部，找到 WhoAmI 函数所需的 WhoAmIResponse 复杂类型值。结果应如下所示：

{
"@odata.context": "https://yourorg.crm.dynamics.com/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",
"BusinessUnitId": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff",
"UserId": "22cc22cc-dd33-ee44-ff55-66aa66aa66aa",
"OrganizationId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
}

在终端窗口中，键入 cls 以清除终端内容。
按 F5，或使用 Visual Studio Code 运行>“开始调试 ”菜单命令再次运行脚本。

由于已进行身份验证，浏览器窗口不会打开。可以继续编辑并运行脚本以尝试不同的请求。

工作原理

本部分介绍 “试用”部分中包含的 PowerShell 脚本的详细信息。

身份验证

该脚本使用 Az PowerShell 模块 Get-AzTenant 命令获取为当前用户授权的租户。如果未登录，此命令将返回错误。该脚本使用 -ErrorAction SilentlyContinue 参数忽略错误并不返回任何内容。

Get-AzTenant当命令不返回任何内容时，脚本使用 Connect-AzAccount 命令打开交互式浏览器窗口，可在其中输入或选择要登录的凭据。了解如何交互式或通过服务主体非交互式登录 Azure PowerShell。

最后，该脚本使用带有参数的 Get-AzAccessToken 命令 -ResourceUrl $environmentUrl 来获取 PSAccessToken 实例，该实例包含一个 SecureString Token 属性，可以转换为可用于向 Dataverse 进行身份验证的访问令牌。

如果要使用不同的凭据集进行连接，请使用 Disconnect-AzAccount 命令。

将 `Invoke-RestMethod` 与 WhoAmI 函数配合使用

将访问令牌设置为 $token 变量后，将请求撰写到 Dataverse Web API，并使用 Invoke-RestMethod cmdlet 发送该请求。

设置标头

所有 Dataverse Web API 请求都必须包含一组常见的 HTTP 请求标头，包括 Authorization 包含访问令牌值的标头。某些操作需要更多标头。详细了解 Dataverse Web API 请求标头。

# Common headers
$baseHeaders = @{
   'Authorization'    = 'Bearer ' + $token
   'Accept'           = 'application/json'
   'OData-MaxVersion' = '4.0'
   'OData-Version'    = '4.0'
}

发送请求

WhoAmI 函数是可执行的最简单 Dataverse 操作之一。因为它是 OData 函数而不是操作，因此需要 GET HTTP 方法。详细了解 Web API 函数。

使用 Invoke-RestMethod cmdletUriMethod 和Headers参数发送此请求。

# Invoke WhoAmI Function
Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Method Get -Headers $baseHeaders
| ConvertTo-Json

对于使用 POST 或 PATCH HTTP 方法的操作，请设置 Body 参数以发送 JSON 有效负载。

ConvertTo-Json cmdlet 将返回的对象转换为 JSON 格式的字符串，该字符串在终端中易于查看。

如果只想捕获响应的某个属性 UserId，请使用以下脚本：

# Get UserId
$userId = (
   Invoke-RestMethod `
   -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') `
   -Method 'Get' `
   -Headers $baseHeaders
   ).UserId
Write-Host $userId

故障排除

请确保验证已安装所有必需的程序，如 “验证安装”中所述。

以下情况可能导致本快速入门中的说明失败：

按 `F5` 时不会发生任何操作

通过按 F-Lock、 Fn Lock 或 函数锁定 键，确保键盘已启用功能键。

还可以改用 Visual Studio Code 运行>“开始调试” 菜单命令。

未找到此主机

如果在运行脚本后看到此错误：

Invoke-RestMethod: untitled:Untitled-1:14:1
Line |
14 |  Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Me …
   |  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   | No such host is known.

检查$environmentUrl是否表示你有权访问的环境。请确保已将其从默认值 (https://yourorg.crm.dynamics.com/) 更改。

用户不是组织的成员

如果在运行脚本后看到此错误：

Invoke-RestMethod: untitled:Untitled-1:14:1                                                                             
Line |
14 |  Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Me …
   |  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   |  {   "error": {     "code": "0x80072560",     "message": "The user is not a member of the organization."   } }

请确保在浏览器窗口中选择的帐户是有权访问参数指定的 $environmentUrl Dataverse 环境的帐户。

如果使用的凭据集不同于以前使用的凭据集，请使用终端窗口中的 Disconnect-AzAccount 命令。

警告：TenantId ‘<您的租户 ID>’ 包含多个活动订阅

首次运行脚本并使用浏览器登录时，可能会收到以下警告：

WARNING: TenantId '<your tenant id>' contains more than one active subscription. First one will be selected for further use. 
To select another subscription, use Set-AzContext. 
To override which subscription Connect-AzAccount selects by default, use `Update-AzConfig -DefaultSubscriptionForLogin 00000000-0000-0000-0000-000000000000`. 
Go to https://go.microsoft.com/fwlink/?linkid=2200610 for more information.

可以忽略此警告。这些请求不需要订阅。

后续步骤

通过 Dataverse Web API 了解使用 PowerShell 和 Visual Studio Code 提高工作效率的更多高级功能，例如如何：

将 PowerShell 和 Visual Studio Code 与 Dataverse Web API 配合使用

现在，可以使用 PowerShell 对 Dataverse Web API 请求进行身份验证和发送，请尝试其他 Web API 操作。

通过了解服务文档详细了解 Dataverse Web API 功能。

Web API 类型和操作

反馈

此页面是否有帮助？

Last updated on 2026-03-28