使用 REST API 和 PowerShell 的 Invoke-RestMethod

您是否经常使用 PowerShell 访问应用程序编程接口 (API)？也许您想要但不知道从哪里开始？无论您是 PowerShell 专业人士还是刚刚入门，本教程都会向您介绍一个内置的 PowerShell cmdlet，该 cmdlet 与名为 Invoke-RestMethod 的 API 进行交互。

在本文中，您将通过使用 GET 和 POST 请求了解使用表述性状态传输 (REST) API 的多种不同方法，包括身份验证、如何下载文件等等！

简而言之，调用 RestMethod

当您需要检索数据或将数据发送到 REST API 时，您需要一个客户端。在 PowerShell 世界中，该客户端是 Invoke-RestMethod cmdlet。此 cmdlet 使用各种 HTTP 方法向 REST API 端点发送 HTTP 请求。

然后，HTTP 方法指示 REST API 对资源执行各种操作。

官方 HTTP 方法是 GET、HEAD、POST、PUT、DELETE、CONNECT、OPTIONS、TRACE 和 PATCH，尽管某些 API 可能实现自定义方法。

Invoke-RestMethod cmdlet 支持所有 HTTP 方法，包括身份验证、发送不同的 HTTP 标头、HTTP 正文，并且还会自动将 JSON 和 XML 响应转换为 PowerShell 对象。 Invoke-RestMethod cmdlet 是用于与 REST API 交互的 PowerShell cmdlet！

先决条件

如果您想学习本教程中的许多演示，请确保您拥有：

• 安装了 PowerShell 7.0 或更高版本。本教程使用 Windows 10 计算机和 PowerShell 7.1。

话不多说，打开 PowerShell 控制台和/或代码编辑器，让我们开始吧！

通过简单的 GET 请求检索数据

让我们从最简单的例子开始；使用 GET 请求查询 REST API。 Invoke-RestMethod 可以做很多事情，但您需要首先了解基础知识。

要向 REST API 端点发送简单的 GET 请求，您只需要一个参数，Uri。 Uri 参数告诉 Invoke-RestMethod 端点的位置。

例如，运行以下命令。此命令查询 JSONPlaceholder API posts 端点并返回 post 资源列表。

JSONPlaceholder 网站提供了一个免费的假 API 进行测试，用于演示使用 Invoke-RestMethod 命令进行查询的真实示例。

Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/posts"

当 REST 端点 https://jsonplaceholder.typicode.com/posts 返回数据时，它不会在漂亮的 PowerShell 对象中返回数据，如上所示。相反，它以 JSON 格式返回数据。 Invoke-RestMethod 自动为您将 JSON 转换为 PowerShell 对象。

您可以在下面看到，PowerShell 通过查看 PowerShell 数组中的单个项目并对其运行 GetType() 方法，将输出转换为 PSCustomObject 类型。

# Store the API GET response in a variable ($Posts).
$Posts = Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/posts"

# Run the GetType() method against the first item in the array, identified by its index of 0.
$Posts[0].GetType()

向 API 进行身份验证

在上一部分中，您使用 GET 方法查询公共 REST API。 API 不需要任何身份验证。但大多数时候，您必须以某种方式向 REST API 进行身份验证。

对 REST API 进行身份验证的两种最常见方法是使用基本（用户名/密码）或承载（令牌）身份验证。为了区分这两种截然不同的身份验证方案，需要在发送请求时使用授权 HTTP 标头。

现在让我们介绍如何使用 Invoke-RestMethod 将 HTTP 标头（尤其是授权 HTTP 标头）发送到 REST 端点。

Invoke-RestMethod 消除了发送 HTTP 请求的大量繁琐工作。尽管您必须在 HTTP 请求中提供授权标头，但在此示例中您不会看到对“标头”的引用。抽象出这样的概念对于 Invoke-RestMethod cmdlet 来说很常见。

使用用户名和密码进行基本身份验证

对 REST 端点进行身份验证的最简单方法是使用用户名和密码。要捕获该用户名和密码，您必须将 PSCredential 对象传递到包含用户名和密码的端点。

首先，创建包含用户名和密码的 PSCredential 对象。

# This will prompt for credentials and store them in a PSCredential object.
$Cred = Get-Credential

将 PSCredential 对象存储在变量中后，将所需的 URI 传递给命令，但这次添加 Authentication 和 Credential 参数。

设置 Authentication 参数会发送一个授权 HTTP 标头，其中包含单词 Basic，后跟 base64 编码的 username:password类似于 Authorization: Basic ZGVtbzpwQDU1dzByZA== 的字符串。

Credential 参数接受您之前创建的 PSCredential。

下面的示例以及本教程中的更多示例使用称为 PowerShell splatting 的概念，它允许您在哈希表中定义参数，然后传递给命令。了解有关 splatting 的更多信息，请参阅 ATA post PowerShell Splatting：它是什么以及它如何工作？

# Send a GET request including Basic authentication.
$Params = @{
	Uri = "https://jsonplaceholder.typicode.com/posts"
	Authentication = "Basic"
	Credential = $Cred
}

Invoke-RestMethod @Params

如果您使用 Credential 或 Authentication 参数选项以及不以 https:// 开头的 Uri，Invoke -RestMethod 出于安全原因将返回错误。要覆盖此默认行为，请使用 AllowUnencryptedAuthentication 参数，风险自负。

使用 API/OAuth 令牌进行承载身份验证

基本的用户名和密码验证还可以，但还不够好。凭证只是简单地编码为 base64（未加密），这会带来安全问题。为了解决这个问题，API 通常会实现令牌身份验证系统或 Bearer/OAuth 身份验证。

要使用 OAuth 令牌对 REST API 进行身份验证：

1. 从您的 API 获取 OAuth 令牌。如何获取此令牌将取决于您的 API 提供商。

2. 接下来，使用 ConvertTo-SecureString cmdlet 将令牌字符串转换为安全字符串，如下所示。 Invoke-RestMethod 要求令牌是安全字符串。

$Token = "123h1v23yt2egv1e1e1b2ei1ube2iu12be" | ConvertTo-SecureString -AsPlainText -Force

3. 最后，定义 Uri、Authentication 类型和 Token 并将其传递给 Invoke-RestMethod cmdlet。然后，Invoke-RestMethod 将调用提供的 URI 并将令牌添加到授权 HTTP 标头。

Authentication 参数参数 OAuth 是 Bearer 的别名。您可以互换使用这两个参数值。

# Send a GET request including bearer authentication.
 $Params = @{
     Uri = "https://jsonplaceholder.typicode.com/posts"
     Authentication = "Bearer"
     Token = $Token
 }
 Invoke-RestMethod @Params

使用查询参数检索数据

通常，向 REST API 发送 GET 请求比向端点发送简单的通用请求更为复杂。相反，您需要传递参数来准确指定 API 中您需要的内容；您需要传递 HTTP 查询参数。

要使用 Invoke-RestMethod 发送查询参数，您有两种选择。您可以直接将参数附加到 URI，如下所示，它传递 1 的 userId 和 8 的 id 。

https://jsonplaceholder.typicode.com/posts?userId=1&id=8

或者，您可以使用 Body 参数作为哈希表来定义 HTTP 正文中的参数。让我们介绍如何使用 Body 参数将参数传递到端点。

创建一个包含查询参数键/值对的哈希表，如下所示。

$Body = @{
    userId = 1
    id = 8
}

最后，将 $Body 变量提供给 Body 参数，如下所示。

您可以使用 GET 值指定 Method 参数，或排除 Method 参数或 Invoke-RestMethod > 默认为该值。

$Params = @{
	Method = "Get"
	Uri = "https://jsonplaceholder.typicode.com/posts"
	Body = $Body
}

Invoke-RestMethod @Params

您现在可以在下面看到端点仅返回您正在查找的帖子项目。

使用 POST HTTP 方法将数据发送到 API

在前面的示例中，您从 REST API 或使用 HTTP GET 请求查询数据。您正在读取它发回的数据，但对于许多 REST API，读取只是故事的一半。 REST API 必须支持完整的 CRUD 模型，以便您可以与服务交互。

当您需要对提供 API 的服务进行更改时，您不会使用 GET HTTP 请求；您将使用“可写”请求，例如 POST。

在使用任何“可写”HTTP 方法（如 PUT 或 PATCH）时，您通常还需要传递带有请求的 HTTP 主体。

在 POST 请求中发送 JSON 数据

使用之前的 REST API 端点，现在让我们创建一个新的帖子项，而不仅仅是阅读它们。

1. 首先，创建一个包含 posts API 端点的所有属性的哈希表。您将在下面看到教程的特定端点允许您使用 title、body 和 userId 创建新的帖子项。

$Body = @{
     title = "foo"
     body = "bar"
     userId = 1
 }

2. 接下来，将 $Body 变量中表示的哈希表转换为 JSON 字符串，并将其存储在新变量 $JsonBody 中。

REST 端点不知道 PowerShell 哈希表是什么，您必须将对象转换为 REST API 可以理解的语言。首先创建哈希表是可选的。如果您愿意，可以直接输入 JSON 并跳过此步骤。

$JsonBody = $Body | ConvertTo-Json

3. 最后，设置所需的参数并运行 Invoke-RestMethod。请注意，您现在必须使用值为 Post 的 Method 参数。如果不使用 Method 参数，Invoke-RestMethod 默认发送 GET 请求。

此外，许多 REST API 要求您指定 ContentType 来指示存储 Body 的 HTTP Content-Type 标头。在此示例中，您必须使用 application/ json.

# The ContentType will automatically be set to application/x-www-form-urlencoded for
# all POST requests, unless specified otherwise.
 $Params = @{
     Method = "Post"
     Uri = "https://jsonplaceholder.typicode.com/posts"
     Body = $JsonBody
     ContentType = "application/json"
 }
 Invoke-RestMethod @Params

请注意，下面的 API 返回一个帖子项以及该新帖子的 id。

使用 Invoke-RestMethod 发送表单数据

某些 REST API 端点可能要求您通过 multipart/form-data HTTP 内容类型提交数据。使用 Invoke-RestMethod 发送不同的内容类型比使用 JSON 更容易一些。从 PowerShell 6.1.0 开始，您现在可以使用 Form 参数。

Form 参数提供了一种将 multipart/form-data 对象添加到请求的便捷方法，而无需使用 .NET System.Net.Http.MultipartFormDataContent直接类。

要使用 Invoke-RestMethod 发送表单数据，首先，像以前一样创建包含每个项目的哈希表。

$Form = @{
    title = "foo"
    body = "bar"
    userId = 1
}

注意使用 Form 参数；您不需要使用 Body 参数。此外，如果您尝试同时指定 ContentType 和 Form 参数，Invoke-RestMethod 将忽略 ContentType参数。

最后，只需将哈希表传递给 Form 参数，如下所示。

$Params = @{
	Method = "Post"
	Uri = "https://jsonplaceholder.typicode.com/posts"
	Form = $Form
}

Invoke-RestMethod @Params

以下关系链接

API 通常不是一次性返回大量数据集，而是返回“一页”数据。例如，GitHub Issues API 默认情况下每页返回 30 个问题。某些 API 包含指向下一页（或上一页、最后一页等）数据响应的链接，以帮助导航数据集（称为关系链接）。

要查找 API 返回的关系链接，您必须检查 HTTP 响应标头。一种简单的方法是使用 ResponseHeadersVariable 参数。此参数自动创建一个变量并将标头存储在哈希表中。

让我们使用 PowerShell GitHub 存储库的问题作为示例。

1. 向 PowerShell GitHub 存储库的问题端点发出 GET 请求，如下所示。请务必使用 ResponseHeadersVariable 创建变量。以下示例使用 $Headers 变量。

# Issue GET request to GitHub issues API for the PowerShell project repo and store
# the response headers in a variable ($Headers).
 Invoke-RestMethod -Uri "https://api.github.com/repos/powershell/powershell/issues" -ResponseHeadersVariable "Headers"
# Print the $Headers variable to the console.
 $Headers

请注意，下面的 $Headers 变量内部的哈希表有一个名为 Links 的键。该键包含响应的关系链接，指示数据集大于这一响应。

2. 接下来，使用 FollowRelLink 参数跟踪关系链接。此参数自动读取每个关系链接并为每个关系链接发出 GET 请求。

下面的代码片段位于每个最多三个关系链接之后。在此示例中，一旦达到 90（每个请求 30 个项目），Invoke-RestMethod cmdlet 将停止查询问题，使用

$Params = @{
   Uri = "https://api.github.com/repos/powershell/powershell/issues"
     FollowRelLink = $true
     MaximumFollowRelLink = 3
 }
 Invoke-RestMethod @Params

使用 FollowRelLink 参数时，Invoke-RestMethod 返回对象数组 (Object[])。数组中的每一项都包含来自其中一个关系链接的响应，该链接可能是另一个对象数组本身！

3. 重新运行前面的示例，但这次检查初始查询返回的结果。您将看到的计数仅为 3，即三“页”。但您会看到第一页项目 ($Results[0]) 包含 30 个项目。

$Params = @{
   Uri = "https://api.github.com/repos/powershell/powershell/issues"
     FollowRelLink = $true
     MaximumFollowRelLink = 3
 }
 # Store the three pages of results in the $Results variable.
 $Results = Invoke-RestMethod @Params
 # Check that $Results contains three items (pages of issues from the GitHub issues API).
 $Results.Count
 # Check that the first item in the $Results array contains the first page of thirty issues.
 $Results[0].Count

4. 最后，使用 foreach 循环迭代 $Results 变量中的每一项。您将在下面看到，您必须使用 foreach 循环遍历每个页面。然后，对于每个页面，迭代该页面中需要嵌套循环的所有项目。

# This might be different depending on the data structure of the API you are using.
# 1) $Results.ForEach({}) - this loops through each page in the $Results array.
# 2) $_.ForEach({}) - this loops through each item in the current page.
# 3) $_ - this simply returns each item to the pipeline.
 $AllResults = @( $Results.ForEach({ $_.ForEach({ $_ }) }) )
# Check that the $AllResults variable contains all ninety items.
 $AllResults.Count

维护会话信息

使用 API 时，存储与先前请求相关的信息（例如标头、凭据、代理详细信息和 cookie）通常很有用，以便在后续请求中重复使用。所有这些信息都存储在会话中。

Invoke-RestMethod 可以通过使用 SessionVariable 参数存储会话，然后使用 WebSession 参数引用该会话来利用会话。

为了进行演示，请再次调用 posts 端点，这次使用 SessionVariable 参数，如下所示。在此示例中，Invoke-RestMethod 将创建一个名为 MySession 的变量。

请记住，会话对象不是持久连接。会话只是一个包含请求信息的对象。

# Invoke the request storing the session as MySession.
# The SessionVariable value shouldn't include a dollar sign ($).
Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/posts" -SessionVariable "MySession"

# Print the session object to the console.
$MySession

现在，通过使用 WebSession 参数调用 Invoke-RestMethod 来重新使用会话信息。正如您在以下示例中看到的，所有先前的会话值都通过新请求中的 $MySession 变量传递。

# Invoke the request using the session information stored in the $MySession variable.
Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/posts" -WebSession $MySession

覆盖会话值

会话包含有关请求的各种信息。如果您想重新使用会话但更改值，则可以覆盖它。

也许，您想重新使用之前创建的会话，但现在使用用户名和密码进行身份验证。我们先来看看之前的情况是什么样的。

请注意，下面的 $MySession 对象不包含 Credentials 属性的任何值。但是，在使用 Credential 参数再次调用 Invoke-RestMethod 后，REST 端点会收到凭证，即使它不在会话中。

# Print the $MySession variable to the console to demonstrate that the Credentials
# property is empty.
$MySession

# Override the session value by specifying the Credential parameter.
# In this example you will be prompted for the username and password.
$Params = @{
	Uri = "https://jsonplaceholder.typicode.com/posts"
	WebSession = $MySession
	Credential = (Get-Credential)
}

Invoke-RestMethod @Params

保存的会话中的属性名为Credentials，但参数名称为Credential。名称并不总是匹配。

将响应正文保存到文件

有时需要将请求的响应保存到文件中。为此，请使用 OutFile 参数。

再次运行 Invoke-RestMethod 以查询教程的测试端点，但这次使用 OutFile 参数并提供文件路径。

您将在下面看到 Invoke-RestMethod 查询端点，以 JSON 格式返回响应，然后将原始 JSON 保存到 .\my-posts.json 文件中。

您还可以使用 PassThru 参数将响应返回到控制台，并立即将响应保存到文件中。

# Save post items to my-posts.json in the current directory.
Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/posts" -OutFile "my-posts.json"

# Print the contents of the JSON file to the console.
# ".\" in this command refers to the current working directory in your terminal session.
Get-Content -Path ".\my-posts.json"

将响应以 JSON 形式保存在文件中后，您可以根据需要解析它以获取信息。下面您将找到一个查找具有特定 ID 的帖子的好示例。

# Save the response to "my-posts.json" and also in the $Posts variable using PassThru.
$Posts = Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/posts" -OutFile "my-posts.json" -PassThru

# Filter posts with 1 as the userId into a new variable ($User1Posts).
$User1Posts = $Posts.Where({$_.userId -eq 1})

# Import all posts from the "my-posts.json" file and store them in the $AllUserPosts variable.
$AllUserPosts = Get-Content -Path ".\my-posts.json" | ConvertFrom-Json

# Print the count of both variables to the console to demonstrate that they are different.
$User1Posts.Count
$AllUserPosts.Count

使用 SSL 和证书

在本教程中，您只使用过 HTTP。 HTTPS 和 SSL 尚未出现。但这并不意味着 Invoke-RestMethod 无法与 SSL 配合使用。事实上，它几乎可以管理您需要的任何内容。

跳过证书验证

默认情况下，Invoke-RestMethod 验证任何 SSL 站点的证书，以确保其未过期、未撤销或信任链完好无损。尽管此行为是您应该保留的安全功能，但有时（例如在测试时）您需要禁用它。

要跳过证书验证，请使用 SkipCertificateCheck 参数。此参数会删除通常运行的所有证书验证Invoke-RestMethod。

为请求指定客户端证书

如果您需要为特定请求指定客户端证书，请使用 Invoke-RestMethod 的 Certificate 参数。此参数采用 X509Certificate 对象作为其值，您可以使用 Get-PfxCertificate 命令或 Get-ChildItem 命令从 证书： PSDrive。

例如，以下命令使用 Cert: 驱动器中的证书向 JSONPlaceholder API posts 端点发出请求。

# Change location into your personal certificate store.
Set-Location "Cert:\CurrentUser\My\"

# Store the certificate with the thumbprint DDE2EC6DBFF56EE9C375A6073C97188ABAA4F5E4 in a variable ($Cert).
$Cert = Get-ChildItem | Where-Object {$_.Thumbprint -eq "DDE2EC6DBFF56EE9C375A6073C97188ABAA4F5E4"}

# Invoke the command using the client certificate.
Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/posts" -Certificate $Cert

限制 SSL/TLS 协议

默认情况下，允许您的系统支持的所有 SSL/TLS 协议。但是，如果您需要将请求限制为特定协议版本，请使用 SslProtocol 参数。

使用 SslProtocol，您可以专门以数组形式调用具有 v1、1.1、1.2 和 1.3 版本的 TLS 的 URI。

# Restrict the request to only allow SSL/TLS 1.2 and 1.3 protocol versions.
Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/posts" -SslProtocol @("Tls12", "Tls13")

在非 Windows 平台上，您可能没有 Tls 或 Tls12 作为选项。并非所有操作系统都支持 Tls13，需要根据每个操作系统进行验证。 Tls13 仅在 PowerShell 7.1+ 中可用。

其他有趣的功能

为了结束本教程，让我们以一些有用的参数结束，但不一定需要说明部分。

使用代理服务器

企业环境通常使用代理服务器来管理互联网访问。要强制 Invoke-RestMethod 通过代理代理其请求，请使用 Proxy 参数。

如果您需要对代理进行身份验证，请向 ProxyCredential 参数提供 PSCredential 对象，或使用开关参数 ProxyUseDefaultCredentials 以使用当前记录的-关于用户的凭据。

# Invoke request using proxy server <http://10.0.10.1:8080> and the current user's credentials.
Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/posts" -Proxy "http://10.0.10.1:8080" -ProxyUseDefaultCredentials

跳过检查和验证

使用这些参数可能会让您面临潜在的安全风险。您已收到警告！

Invoke-RestMethod cmdlet 在底层执行许多不同的检查。如果您出于某种原因希望禁用这些检查，您可以使用一些参数来完成。

• SkipHeaderValidation - 禁用对传递给 ContentType、Headers 和 UserAgent 参数的值进行验证。
• SkipHttpErrorCheck - 任何错误都将被忽略。在继续处理之前，错误将被写入管道。
• StatusCodeVariable - 使用 SkipHttpErrorCheck 时，您可能需要检查 HTTP 响应状态代码以识别成功或失败消息。为此，StatusCodeVariable 参数会将状态代码整数值分配给变量。

禁用保持活动状态

TCP Keep Alive 是一项方便的网络级功能，允许您创建到远程服务器的持久连接（如果服务器支持）。默认情况下，Invoke-RestMethod 不使用 Keep Alive。

如果您想使用 Keep Alive，可能会减少远程服务器的 CPU 和内存使用量，请将 DisableKeepAlive 参数设置为 $false。

Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/posts" -DisableKeepAlive $false

更改编码类型

每当 Invoke-RestMethod 向远程端点发送请求时，它都会使用传输编码标头对请求进行编码。默认情况下，Invoke-RestMethod 和服务器协商此编码方法，但您可以使用 TransferEncoding 参数显式定义编码类型。

如果您想更改编码类型，可以使用：

• 分块
• 压缩
• 放气
• 压缩包
• 身份

结论

在本教程中，您了解了 Invoke-RestMethod 如何使与 REST API 的交互比与标准 Web 请求的交互更加容易。您已经了解了身份验证参数、在请求正文中发送数据、维护会话状态、下载文件等等。

现在您已经掌握了 Invoke-RestMethod 并使用了 REST API，您将在什么 REST API 上尝试这个方便的 cmdlet？