如何在 PowerShell 中使用调用 RestMethod

---

当您需要与 PowerShell 中的 REST API 交互时，您将需要使用 Invoke RestMethod cmdlet。此 cmdlet 允许您从命令行或 PowerShell 脚本向 REST Web 服务发送 HTTP(S) 请求。

REST API 可用于管理各种服务或从中提取数据。但请记住，通常有可用于流行服务的 PowerShell 模块，例如 Azure、Graph、GitHub 等。因此，请务必在开始之前进行检查！

在本文中，我们将了解如何使用 Invoke-RestMethod cmdlet 从 PowerShell 进行 REST API 调用。

PowerShell 调用 RestMethod

PowerShell Invoke-RestMethod cmdlet 允许您使用 REST API。它支持所有必需的 HTTP 方法，如 Get、Post、Put 等以及身份验证。该 cmdlet 的优点是它会自动将 JSON 或 XML 响应转换为 PowerShell 中的 pscustomobjects 对象

要进行 REST API 调用，您需要将请求发送到的 URI（可能是身份验证方法），当然还需要知道要使用哪种方法。默认情况下，cmdlet 将使用 GET 方法，但其他常用方法有：

• GET - 从特定端点检索数据。
• POST - 将数据发送到服务器以创建新资源
• PUT - 更新服务器上的现有资源。
• PATCH - 与 PUT 类似，但仅将更改的数据发送到服务器
• DELETE - 从服务器中删除资源

检索数据

我们将从基础知识开始，从 API 检索数据。要检索数据，我们需要知道要使用哪个 URI（端点）。几乎所有 API 都有文档，您可以在其中查看可以使用的不同 URI。

笔记

对于下面的示例，我们将使用这个免费的 REST API https://restful-api.dev/ 。这个API不需要任何认证，并且还允许你做put请求，这非常适合学习。

要从 API 获取所有对象，我们只需使用 Invoke-RestMethod cmdlet 以及要从中接收数据的 URI。这是一个开放的 API，因此不需要身份验证。

Invoke-RestMethod -Uri 'https://api.restful-api.dev/objects'

API 返回 JSON，该 JSON 由 Invoke-RestMethod cmdlet 自动转换为 PowerShell 对象。但是，当 API 返回多个对象时，对象将作为数组接收。

从 REST API 选择特定对象通常是通过使用查询或指定对象 ID 来完成的。例如，要从对象中选择 Google Pixel 6，我们可以指定 ID 1：

https://api.restful-api.dev/objects/1

因为现在只返回单个对象，所以我们还可以直接使用 select-object cmdlet 只返回对象的名称：

https://api.restful-api.dev/objects/1 | Select name

# Result
name
----
Google Pixel 6 Pro

使用查询参数

要从 API 选择特定对象，您需要使用查询参数。这些参数可以是 Invoke-RestMethod cmdlet 中 URI 的一部分，也可以使用 JSON 正文。您可以使用哪些参数实际上取决于 API。

您需要查看 API 文档以了解您使用的查询参数。例如，我们在本示例中使用的端点仅接受 ID 作为查询参数：

Invoke-RestMethod -uri 'https://api.restful-api.dev/objects?id=3&id=5'

# result
id name                    data
-- ----                    ----
3  Apple iPhone 12 Pro Max @{color=Cloudy White; capacity GB=512}
5  Samsung Galaxy Z Fold2  @{price=689,99; color=Brown}

再举一个例子，我们可以使用 randomuser.me API，它会生成随机用户数据。此 API 接受多个参数，允许您指定要生成哪种类型的用户数据。

例如，我们可以生成 5 个用户，其性别均为男性且国籍为荷兰：

Invoke-RestMethod -Uri 'https://randomuser.me/api/?gender=male&results=5&nat=nl' | select -ExpandProperty results | ft

使用 JSON 正文

在 URI 中指定所有参数可能会使代码更难阅读。因此，当您需要指定多个参数时，通常最好使用 JSON 正文。

JSON 正文的优点是它们更易于阅读，并允许您快速添加或更改请求中的参数。

要发出与上例相同的请求，我们可以使用简单的哈希表为 Invoke-RestMethod 创建一个主体。我还将 URI 存储在一个变量中，以使示例更具可读性：

$uri = 'https://randomuser.me/api/'
$body = @{
    gender = 'male'
    nat = 'nl'
    results = '5'
}

Invoke-RestMethod -Uri $uri -Body $body | select -ExpandProperty results | ft

我们甚至可以使用splatting技术将所有参数存储在哈希表中。在这种情况下，指定请求方法总是一个好主意。我已将主体包含在哈希表中，但如果您愿意，也可以单独创建主体。

$parameters = @{
    Method = 'GET'
    Uri = 'https://randomuser.me/api/'
    Body =  @{
            gender = 'male'
            nat = 'nl'
            results = '5'
        }
    }

Invoke-RestMethod @parameters | select -ExpandProperty results | ft

关注关系链接

某些 REST API 支持使用关系链接。关系链接通常用于分页，因此您可以在一次调用中请求 1000 个对象。关系链接在结果的标题中注明。

使用 Invoke RestMethod cmdlet 时，您可以使用 FollowRelLink 参数访问这些关系链接。参数 MaximumFollowRelLink 还允许您确定要请求的页面数量。

$url = 'https://api.github.com/repos/ruudmens/a-d/issues'
Invoke-RestMethod $url -FollowRelLink -MaximumFollowRelLink 2

发送数据

我们还可以使用 PowerShell Invoke-RestMethod 将数据发送到 REST API。为此，我们需要使用要发送的数据创建一个 JSON 正文。此外，您还需要知道端点 URI，并且我们需要使用正确的方法。

如果您想创建一个新的对象/资源，那么您将需要使用 POST 方法。要更新现有资源，您需要使用 PUT 或 PATH 方法。

第一步是使用要发布到 API 的项目创建正文。我们使用的示例 REST API 也要求数据属性是 JSON 对象，但通常您可以直接指定属性，而无需嵌套哈希表：

$body = @{
    name = 'LazyPhone'
    data = @{
       year = 2024
       price = 399.99
       'Screen size' = 6.2
    }
}

在 POST 新对象之前，我们需要确保主体已转换为 JSON 对象。我们可以使用 ConvertTo-JSON cmdlet 来完成此操作。我们还需要指定要发送的 ContentType，当然还有 POST 方法：

$parameters = @{
    Method = 'POST'
    Uri = 'https://api.restful-api.dev/objects'
    Body =  ConvertTo-JSON($body)
    ContentType = 'application/json'
}

Invoke-RestMethod @parameters

大多数 API 会在您成功 POST 后返回该对象。您可以将结果存储在变量中，或者如果您不希望将其输出到控制台，则可以将其重定向为 null。

Invoke-RestMethod @parameters | Out-Null

上传文件和混合内容

当您需要使用 PowerShell 将文件或图像上传到 API 时，您通常需要使用 multipart/formdata 来提交您的对象。为此，您至少需要使用 PowerShell 6，因为这允许您使用 -Form 参数。

就像使用 body 参数时一样，我们需要为 form 参数创建一个哈希表：

$form = @{
    brand = 'LazyPhone'
    model = 'Snap 2'
    released = '2024-01-22'
    image = Get-Item -Path "c:\marketing\LazyPhone\"
}

$parameters = @{
    Method = 'POST'
    Uri = 'https://api.example.dev/phones'
    Form = ConvertTo-JSON($form)
    ContentType = 'application/json'
}

Invoke-RestMethod @parameters

更新对象

更新对象的方式与创建对象的方式几乎相同。这里唯一的区别是您需要指定要更新的对象。

有两种方法可用于更新对象：PUT 和 PATCH。第一个将替换对象的所有属性，而后者仅替换您发送的属性。

$body = @{
    name = 'LazyPhone'
    data = @{
        color = 'Cloudy White'
        'capacity GB' = 512
    }
}

$parameters = @{
    Method = 'POST'
    Uri = 'https://api.restful-api.dev/objects/3'
    Body =  ConvertTo-JSON($body)
    ContentType = 'application/json'
}

验证

到目前为止，我们在示例中使用了不需要任何身份验证的 REST API。但大多数 REST API 要求您在与其交互之前进行身份验证。常用的三种认证方法：

• 基本 - 基于简单的用户名/密码的身份验证
• Bearer - 需要令牌参数
• API密钥 - 访问密钥和秘密密钥的组合

身份验证详细信息在调用的标头中提供。您可以通过 Invoke-RestMethod cmdlet 使用 -headers 参数来执行此操作。

基本认证

基本身份验证由使用 base64 编码的用户名和密码组成。如今，它们并不是最安全的选择，因此您不会经常遇到它们。要使用基本身份验证，您首先需要在 PowerShell 中创建一个凭据对象

$cred = Get-Credential

然后，我们可以将凭证对象添加到 REST API 请求的标头中。如果您使用的是 PowerShell 6 或更高版本，则可以使用 -authentication 和 -credential 参数：

Invoke-RestMethod -uri 'https://api.restful-api.dev/objects/' -Credential $cred -Authentication Basic

使用 PowerShell 5 时，您只能使用凭证对象，并且需要使用 JSON 对象创建标头：

$headers = @{
    Authorization = "Basic"
}

Invoke-RestMethod -uri 'https://api.restful-api.dev/objects/' -Headers $header -Credential $cred

承载者

不记名令牌是一种更常用的身份验证方法。它使用您通常首先需要从 REST API 请求的令牌。令牌的请求方式以及令牌的有效时间取决于 API。

要使用令牌，我们可以使用 -Token 参数（在 PowerShell 6 或更高版本中）或在标头中添加令牌。

$token = 'token-from-api'

Invoke-RestMethod -Uri $uri -Authentication Bearer -Token $token

或者使用 PowerShell 5.x 时：

$headers = @{
    'Authorization' = "Bearer $Token"
}

Invoke-RestMethod -Uri $uri -Headers $header

API 密钥 - 秘密

我想向您展示的最后一个身份验证选项是 API 密钥/秘密方法。如今，许多 API 允许您创建可用于您的应用程序的唯一密钥/秘密组合。

要使用密钥和秘密进行身份验证，我们需要使用 X-ApiKeys 标头。就像其他标头一样，您需要使用 X-ApiKeys 标头规则创建一个标头对象：

$parameters = @{
    Method = 'PUT'
    Uri = 'https://api.restful-api.dev/objects/'
    Headers = @{
        "X-ApiKeys" = "accessKey=$($accessKey); secretKey=$($secretKey)"
    }
    ContentType = 'application/json'
}

Invoke-RestMethod @parameters

总结

REST API 是与其他系统交换信息的好方法。请记住，PowerShell 模块可用于许多流行的服务。因此，请确保在开始之前先检查一下。

PowerShell Invoke RestMethod cmdlet 在 PowerShell 7.x 中更易于使用，因此我强烈建议您在使用 REST API 时使用最新版本。

我希望这篇文章对您有所帮助。如果您有任何疑问，请在下面发表评论。