Invoke-RestMethod

语法

Default （默认值）

Invoke-RestMethod
    [-Method <WebRequestMethod>]
    [-UseBasicParsing]
    [-Uri] <Uri>
    [-WebSession <WebRequestSession>]
    [-SessionVariable <String>]
    [-Credential <PSCredential>]
    [-UseDefaultCredentials]
    [-CertificateThumbprint <String>]
    [-Certificate <X509Certificate>]
    [-UserAgent <String>]
    [-DisableKeepAlive]
    [-TimeoutSec <Int32>]
    [-Headers <IDictionary>]
    [-MaximumRedirection <Int32>]
    [-Proxy <Uri>]
    [-ProxyCredential <PSCredential>]
    [-ProxyUseDefaultCredentials]
    [-Body <Object>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [<CommonParameters>]

说明

参数

-Body

指定请求的正文。 正文是请求的内容，位于标头之后。 还可以通过管道将正文值传递给 Invoke-RestMethod。

-Body 参数可用于指定查询参数列表或指定响应的内容。

当输入是 GET 请求，正文是 IDictionary（通常为哈希表）时，正文将作为查询参数添加到 URI。 对于其他请求类型（如 POST），将正文按标准的“名称=值”格式设置为请求正文的值。

警告：POST 正文的详细输出将以 with -1-byte payload结束，即使正文的大小都是已知的，并在 Content-Length HTTP 标头中发送。

当正文是窗体，或者它是另一个 Invoke-WebRequest 调用的输出时，Windows PowerShell 会将请求内容设置为窗体字段。

例如：

$R = Invoke-WebRequest https://website.com/login.aspx
$R.Forms[0].Name = "MyName"
$R.Forms[0].Password = "MyPassword"
Invoke-RestMethod https://website.com/service.aspx -Body $R.Forms[0]

参数属性

参数集

-Certificate

指定用于安全 Web 请求的客户端证书。 输入包含证书的变量或获取证书的命令或表达式。

若要查找证书，请使用 Get-PfxCertificate 或使用 Certificate （Get-ChildItem） 驱动器中的 Cert: cmdlet。 如果证书无效或没有足够的颁发机构，命令将失败。

参数属性

参数集

-CertificateThumbprint

指定有权发送请求的用户帐户的数字公钥证书（X509）。 输入证书的证书指纹。

证书用于基于客户端证书的身份验证。 它们只能映射到本地用户帐户;它们不适用于域帐户。

若要获取证书指纹，请使用 Windows PowerShell（Get-Item）驱动器中的 Get-ChildItem 或 Cert: 命令。

参数属性

参数集

-ContentType

指定 Web 请求的内容类型。

如果省略此参数并且请求方法是 POST，Invoke-RestMethod 将内容类型设置为“application/x-www-form-urlencoded”。 否则，在调用中未指定内容类型。

参数属性

参数集

-Credential

指定有权发送请求的用户帐户。 默认值为当前用户。

键入用户名（如“User01”或“Domain01\User01”），或输入 PSCredential 对象，例如由 Get-Credential cmdlet 生成的用户名。

参数属性

参数集

-DisableKeepAlive

将 HTTP 标头中的 KeepAlive 值设置为 False。 默认情况下，KeepAlive 为 True。 KeepAlive 建立与服务器的持久连接，以促进后续请求。

参数属性

参数集

-Headers

指定 Web 请求的标头。 输入哈希表或字典。

若要设置 UserAgent 标头，请使用 -UserAgent 参数。 不能使用此参数指定 UserAgent 或 Cookie 标头。

参数属性

参数集

-InFile

从文件获取 Web 请求的内容。

输入路径和文件名。 如果省略路径，则默认值为当前位置。

参数属性

参数集

-MaximumRedirection

确定在连接失败之前，Windows PowerShell 将连接重定向到备用统一资源标识符（URI）的次数。 默认值为 5。 值为 0（零）会阻止所有重定向。

参数属性

参数集

-Method

指定用于 Web 请求的方法。 此参数的可接受值为：

• 违约
• 删除
• 获取
• 头
• 合并
• 选项
• 补丁
• 发布
• Put
• 跟踪

参数属性

参数集

-OutFile

将响应正文保存在指定的输出文件中。 输入路径和文件名。 如果省略路径，则默认值为当前位置。

默认情况下，Invoke-RestMethod 将结果返回到管道。 若要将结果发送到文件和管道，请使用 -Passthru 参数。

参数属性

参数集

-PassThru

除了将结果写入文件之外，还返回结果。 仅当命令中也使用 -OutFile 参数时，此参数才有效。

参数属性

参数集

-Proxy

对请求使用代理服务器，而不是直接连接到 Internet 资源。 输入网络代理服务器的 URI。

参数属性

参数集

-ProxyCredential

指定有权使用由 -Proxy 参数指定的代理服务器的用户帐户。 默认值为当前用户。

键入用户名（如“User01”或“Domain01\User01”），或输入 PSCredential 对象，例如由 Get-Credential cmdlet 生成的用户名。

仅当命令中也使用 -Proxy 参数时，此参数才有效。 不能在同一命令中使用 -ProxyCredential 和 -ProxyUseDefaultCredentials 参数。

参数属性

参数集

-ProxyUseDefaultCredentials

使用当前用户的凭据访问由 -Proxy 参数指定的代理服务器。

仅当命令中也使用 -Proxy 参数时，此参数才有效。 不能在同一命令中使用 -ProxyCredential 和 -ProxyUseDefaultCredentials 参数。

参数属性

参数集

-SessionVariable

创建 Web 请求会话并将其保存在指定变量的值中。 输入没有美元符号（$）符号的变量名称。

指定会话变量时，Invoke-RestMethod 创建 Web 请求会话对象，并将其分配给 Windows PowerShell 会话中具有指定名称的变量。 命令完成后，即可在会话中使用变量。

与远程会话不同，Web 请求会话不是永久性连接。 它是一个对象，其中包含有关连接和请求的信息，包括 Cookie、凭据、最大重定向值和用户代理字符串。 可以使用它在 Web 请求之间共享状态和数据。

若要在后续 Web 请求中使用 Web 请求会话，请在 -WebSession 参数的值中指定会话变量。 Windows PowerShell 在建立新连接时使用 Web 请求会话对象中的数据。 若要重写 Web 请求会话中的值，请使用 cmdlet 参数，例如 -UserAgent 或 -Credential。 参数值优先于 Web 请求会话中的值。

不能在同一命令中使用 -SessionVariable 和 -WebSession 参数。

参数属性

参数集

-TimeoutSec

指定请求在超时之前可以等待多长时间。以秒为单位输入值。 默认值为0，指定无限期超时。

域名系统（DNS）查询最多可能需要 15 秒才能返回或超时。如果请求包含需要解析的主机名，并且将 TimeoutSec 设置为大于零的值，但小于 15 秒，则引发 WebException 前可能需要 15 秒或更多秒，并且请求超时。

参数属性

参数集

-TransferEncoding

指定传输编码 HTTP 响应标头的值。 此参数的可接受值为：

• Chunked
• 压缩
• Deflate
• GZip
• 身份

参数属性

参数集

-Uri

指定 Web 请求发送到的 Internet 资源的统一资源标识符（URI）。 此参数支持 HTTP、HTTPS、FTP 和 FILE 值。

此参数是必需的。 参数名称（-Uri）是可选的。

参数属性

参数集

-UseBasicParsing

指示 cmdlet 使用基本分析。 该 cmdlet 返回 String 对象中的原始 HTML。

参数属性

参数集

-UseDefaultCredentials

使用当前用户的凭据发送 Web 请求。

参数属性

参数集

-UserAgent

指定 Web 请求的用户代理字符串。

默认用户代理类似于“Mozilla/5.0（Windows NT;Windows NT 6.1;en-US） WindowsPowerShell/3.0“，每个操作系统和平台稍有变化。

若要使用大多数 Internet 浏览器使用的标准用户代理字符串测试网站，请使用 PSUserAgent 类的属性，例如 Chrome、FireFox、Internet Explorer、Opera 和 Safari。

例如，以下命令使用 Internet 的用户代理字符串

Invoke-WebRequest -Uri https://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)

参数属性

参数集

-WebSession

指定 Web 请求会话。 输入变量名称，包括美元符号（$）。

若要重写 Web 请求会话中的值，请使用 cmdlet 参数，例如 -UserAgent 或 -Credential。 参数值优先于 Web 请求会话中的值。

与远程会话不同，Web 请求会话不是永久性连接。 它是一个对象，其中包含有关连接和请求的信息，包括 Cookie、凭据、最大重定向值和用户代理字符串。 可以使用它在 Web 请求之间共享状态和数据。

若要创建 Web 请求会话，请在 -SessionVariable 命令的 Invoke-RestMethod 参数的值中输入变量名称（不含美元符号）。 Invoke-RestMethod 创建会话并将其保存在变量中。 在后续命令中，使用变量作为 -WebSession 参数的值。

不能在同一命令中使用 -SessionVariable 和 -WebSession 参数。

参数属性

参数集

CommonParameters

输入

Object

输出

System.Xml.XmlDocument, Microsoft.PowerShell.Commands.HtmlWebResponseObject, System.String

PSObject

相关链接

• ConvertTo-Json
• ConvertFrom-Json
• Invoke-WebRequest