Invoke-RestMethod 和 Invoke-WebRequest 最关键的输出差异是什么？

Invoke-RestMethod 返回反序列化后的对象，没有状态码/响应头；Invoke-WebRequest 返回完整响应对象。

为什么把哈希表直接传给 -Body 调用 JSON API 会失败？

哈希表默认按表单编码发送，Content-Type 也不是 JSON；应 ConvertTo-Json 并设置 application/json。

5.1 中怎样拿到 401 响应的响应体？

用 try/catch 捕获，读 $.ErrorDetails.Message 和 $.Exception.Response。

系统学习 Windows 学习路径：从 CMD 到 PowerShell、系统网络，再到 WSL 与 Server

Invoke-RestMethod

调用 REST API，把 JSON 响应自动反序列化成对象。

补充说明

Invoke-RestMethod 发送 HTTP 请求后直接返回反序列化结果：JSON 变成 PSCustomObject/数组，XML 变成结构化对象；别名是 irm。它不返回状态码和响应头，这是与 Invoke-WebRequest 的关键差异。-Body 可按值接收管道输入，地址、方法和内容类型仍需显式指定。

权限：普通用户即可访问网络资源，受代理、防火墙、TLS 和认证限制。认证常用 -Headers @{ Authorization = "Bearer $env:TOKEN" } 或 -Credential；不要把长期令牌写进脚本或命令历史。边界：它只负责请求和反序列化，不处理分页、重试和限流；这些要按 API 约定自行实现。

版本：5.1 在 4xx/5xx 时抛错，错误响应体可从 $_.ErrorDetails.Message 读取；7.x 差异：新增 -ResponseHeadersVariable、-StatusCodeVariable、-SkipHttpErrorCheck、-FollowRelLink 等参数，5.1 没有。两版都受默认 TLS 和编码设置影响。

常用示例

# 1. 调用公开 API，直接按属性取值
PS C:\> $repo = Invoke-RestMethod -Uri 'https://api.github.com/repos/PowerShell/PowerShell' -Headers @{ 'User-Agent'='cmd-hub' }; $repo.stargazers_count

# 2. 提交 JSON 请求体，创建资源
PS C:\> $body = @{ title='demo'; body='test' } | ConvertTo-Json; Invoke-RestMethod -Uri 'https://api.example.com/issues' -Method Post -Body $body -ContentType 'application/json'

# 3. 取回列表并只保留前 3 条
PS C:\> $items = Invoke-RestMethod -Uri 'https://api.example.com/items?limit=10'; $items | Select-Object -First 3

# 4. 捕获 HTTP 错误并读取状态码和响应体
PS C:\> try { Invoke-RestMethod -Uri 'https://api.example.com/private' -ErrorAction Stop } catch { $_.Exception.Response.StatusCode.value__; $_.ErrorDetails.Message }

# 5. 用环境变量传递令牌，避免把密钥写死在脚本里
PS C:\> $h = @{ Authorization = "Bearer $env:API_TOKEN" }; Invoke-RestMethod -Uri 'https://api.example.com/me' -Headers $h

# 6. 把 API 结果再序列化，检查完整结构
PS C:\> Invoke-RestMethod -Uri 'https://api.example.com/items' | ConvertTo-Json -Depth 4

易错点与排错

返回对象没有 StatusCode/Headers，需要这些信息时改用 Invoke-WebRequest；7.x 可用 -StatusCodeVariable/-ResponseHeadersVariable 捕获。
4xx/5xx 默认抛错，脚本要 try/catch；5.1 的响应体常在 $_.ErrorDetails.Message，7.x 还可看异常响应内容。
-Body 传哈希表是表单编码，不是 JSON；JSON API 必须先 ConvertTo-Json 并设置 ContentType。
5.1 不会自动翻页；需要按 Link 头或游标循环请求，7.x 可用 -FollowRelLink（受 API 的 Link 头支持情况限制）。
单元素 JSON 数组会被展开成单个对象，Count 和索引结果异常；用 @(...) 包住结果。
旧系统可能未启用 TLS 1.2，报连接被关闭；检查并启用 TLS 1.2，不要用关闭证书验证的方式“修复”。
令牌写在命令行会进入历史记录和进程列表；优先读环境变量、凭据管理器或受限权限的配置文件。
7.x 差异：跨平台可用，但认证方式、代理和证书存储与 Windows 不同；-SkipHttpErrorCheck 等参数只存在于 7.x。

参考链接

读完自测

合上页面，先回答，再展开对照。

Invoke-RestMethod 和 Invoke-WebRequest 最关键的输出差异是什么？
为什么把哈希表直接传给 -Body 调用 JSON API 会失败？
5.1 中怎样拿到 401 响应的响应体？

答案

Invoke-RestMethod 返回反序列化后的对象，没有状态码/响应头；Invoke-WebRequest 返回完整响应对象。
哈希表默认按表单编码发送，Content-Type 也不是 JSON；应 ConvertTo-Json 并设置 application/json。
用 try/catch 捕获，读 $_.ErrorDetails.Message 和 $_.Exception.Response。