Invoke-RestMethod

Referência

Módulo:: Microsoft.PowerShell.Utility

Envia uma solicitação HTTP ou HTTPS para um serviço Web RESTful.

Sintaxe

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>]

Description

O cmdlet Invoke-RestMethod envia solicitações HTTP e HTTPS para serviços Web REST (Transferência de Estado Representacional) que retorna dados altamente estruturados.

O Windows PowerShell formata a resposta com base no tipo de dados. Para um RSS ou feed ATOM, o Windows PowerShell retorna os nós XML de item ou de entrada. Para JSON (JavaScript Object Notation) ou XML, o Windows PowerShell converte (ou desserializa) o conteúdo em objetos.

Esse cmdlet é introduzido no Windows PowerShell 3.0.

Nota

Por padrão, o código de script na página da Web pode ser executado quando a página está sendo analisada para preencher a propriedade ParsedHtml. Use a opção -UseBasicParsing para suprimir isso.

Exemplos

Exemplo 1: Obter o feed RSS do PowerShell

Invoke-RestMethod -Uri https://blogs.msdn.microsoft.com/powershell/feed/ |
  Format-Table -Property Title, pubDate

Title                                                                pubDate
-----                                                                -------
Join the PowerShell 10th Anniversary Celebration!                    Tue, 08 Nov 2016 23:00:04 +0000
DSC Resource Kit November 2016 Release                               Thu, 03 Nov 2016 00:19:07 +0000
PSScriptAnalyzer Community Call - Oct 18, 2016                       Thu, 13 Oct 2016 17:52:35 +0000
New Home for In-Box DSC Resources                                    Sat, 08 Oct 2016 07:13:10 +0000
New Social Features on Gallery                                       Fri, 30 Sep 2016 23:04:34 +0000
PowerShellGet and PackageManagement in PowerShell Gallery and GitHub Thu, 29 Sep 2016 22:21:42 +0000
PowerShell Security at DerbyCon                                      Wed, 28 Sep 2016 01:13:19 +0000
DSC Resource Kit September Release                                   Thu, 22 Sep 2016 00:25:37 +0000
PowerShell DSC and implicit remoting broken in KB3176934             Tue, 23 Aug 2016 15:07:50 +0000
PowerShell on Linux and Open Source!                                 Thu, 18 Aug 2016 15:32:02 +0000

Esse comando usa o cmdlet Invoke-RestMethod para obter informações do feed RSS do Blog do PowerShell. O comando usa o cmdlet Format-Table para exibir os valores das propriedades Title e pubDate de cada blog em uma tabela.

Exemplo 2

No exemplo a seguir, um usuário executa Invoke-RestMethod para executar uma solicitação POST em um site da intranet na organização do usuário.

$Cred = Get-Credential

# Next, allow the use of self-signed SSL certificates.

[System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $True }

# Create variables to store the values consumed by the Invoke-RestMethod command.
# The search variable contents are later embedded in the body variable.

$Server = 'server.contoso.com'
$Url = "https://${server}:8089/services/search/jobs/export"
$Search = "search index=_internal | reverse | table index,host,source,sourcetype,_raw"

# The cmdlet handles URL encoding. The body variable describes the search criteria, specifies CSV as the output mode, and specifies a time period for returned data that starts two days ago and ends one day ago. The body variable specifies values for parameters that apply to the particular REST API with which Invoke-RestMethod is communicating.

$Body = @{
    search = $Search
    output_mode = "csv"
    earliest_time = "-2d@d"
    latest_time = "-1d@d"
}

# Now, run the Invoke-RestMethod command with all variables in place, specifying a path and file name for the resulting CSV output file.

Invoke-RestMethod -Method Post -Uri $url -Credential $Cred -Body $body -OutFile output.csv

{"preview":true,"offset":0,"result":{"sourcetype":"contoso1","count":"9624"}}

{"preview":true,"offset":1,"result":{"sourcetype":"contoso2","count":"152"}}

{"preview":true,"offset":2,"result":{"sourcetype":"contoso3","count":"88494"}}

{"preview":true,"offset":3,"result":{"sourcetype":"contoso4","count":"15277"}}

Exemplo 3: Passar vários cabeçalhos

$headers = @{
    'userId' = 'UserIDValue'
    'token' = 'TokenValue'
}
Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $body

As APIs geralmente exigem cabeçalhos passados para autenticação, validação etc.

Este exemplo demonstra como passar vários cabeçalhos de um hash-table para uma API REST.

Parâmetros

-Body

Especifica o corpo da solicitação. O corpo é o conteúdo da solicitação que segue os cabeçalhos. Você também pode canalizar um valor de corpo para Invoke-RestMethod.

O parâmetro -Body pode ser usado para especificar uma lista de parâmetros de consulta ou especificar o conteúdo da resposta.

Quando a entrada é uma solicitação GET e o corpo é um IDictionary (normalmente, uma tabela de hash), o corpo é adicionado ao URI como parâmetros de consulta. Para outros tipos de solicitação (como POST), o corpo é definido como o valor do corpo da solicitação no formato name=value padrão.

Aviso: A saída detalhada de um corpo POST terminará com with -1-byte payload, mesmo que o tamanho do corpo seja conhecido e enviado no cabeçalho HTTP Content-Length.

Quando o corpo é um formulário ou é a saída de outra chamada Invoke-WebRequest, o Windows PowerShell define o conteúdo da solicitação para os campos de formulário.

Por exemplo:

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

Tipo:	Object
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	True
Aceitar caracteres curinga:	False

-Certificate

Especifica o certificado do cliente usado para uma solicitação da Web segura. Insira uma variável que contenha um certificado ou um comando ou expressão que obtém o certificado.

Para localizar um certificado, use Get-PfxCertificate ou use o cmdlet Get-ChildItem na unidade Certificado (Cert:). Se o certificado não for válido ou não tiver autoridade suficiente, o comando falhará.

Tipo:	X509Certificate
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-CertificateThumbprint

Especifica o certificado de chave pública digital (X509) de uma conta de usuário que tem permissão para enviar a solicitação. Insira a impressão digital do certificado.

Os certificados são usados na autenticação baseada em certificado do cliente. Eles podem ser mapeados apenas para contas de usuário local; eles não funcionam com contas de domínio.

Para obter uma impressão digital do certificado, use o comando Get-Item ou Get-ChildItem na unidade do Windows PowerShell (Cert:).

Tipo:	String
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-ContentType

Especifica o tipo de conteúdo da solicitação da Web.

Se esse parâmetro for omitido e o método de solicitação for POST, Invoke-RestMethod definirá o tipo de conteúdo como "application/x-www-form-urlencoded". Caso contrário, o tipo de conteúdo não será especificado na chamada.

Tipo:	String
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-Credential

Especifica uma conta de usuário que tem permissão para enviar a solicitação. O padrão é o usuário atual.

Digite um nome de usuário, como "User01" ou "Domain01\User01", ou insira um objeto PSCredential, como um gerado pelo cmdlet Get-Credential.

Tipo:	PSCredential
Cargo:	Named
Valor padrão:	Current user
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-DisableKeepAlive

Define o valor KeepAlive no cabeçalho HTTP como False. Por padrão, KeepAlive é True. KeepAlive estabelece uma conexão persistente com o servidor para facilitar as solicitações subsequentes.

Tipo:	SwitchParameter
Cargo:	Named
Valor padrão:	KeepAlive
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-Headers

Especifica os cabeçalhos da solicitação da Web. Insira uma tabela ou dicionário de hash.

Para definir cabeçalhos UserAgent, use o parâmetro -UserAgent. Você não pode usar esse parâmetro para especificar useragent ou cabeçalhos de cookie.

Tipo:	IDictionary
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-InFile

Obtém o conteúdo da solicitação da Web de um arquivo.

Insira um caminho e um nome de arquivo. Se você omitir o caminho, o padrão será o local atual.

Tipo:	String
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-MaximumRedirection

Determina quantas vezes o Windows PowerShell redireciona uma conexão para um URI (Uniform Resource Identifier) alternativo antes que a conexão falhe. O valor padrão é 5. Um valor de 0 (zero) impede todo o redirecionamento.

Tipo:	Int32
Cargo:	Named
Valor padrão:	5
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-Method

Especifica o método usado para a solicitação da Web. Os valores aceitáveis para este parâmetro são:

Inadimplência
Excluir
Obter
Cabeça
Fundir
Opções
Remendo
Postar
Pôr
Traço

Tipo:	WebRequestMethod
Valores aceitos:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Cargo:	Named
Valor padrão:	Default
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-OutFile

Salva o corpo da resposta no arquivo de saída especificado. Insira um caminho e um nome de arquivo. Se você omitir o caminho, o padrão será o local atual.

Por padrão, Invoke-RestMethod retorna os resultados para o pipeline. Para enviar os resultados para um arquivo e para o pipeline, use o parâmetro -Passthru.

Tipo:	String
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-PassThru

Retorna os resultados, além de escrevê-los em um arquivo. Esse parâmetro é válido somente quando o parâmetro -OutFile também é usado no comando.

Tipo:	SwitchParameter
Cargo:	Named
Valor padrão:	No output
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-Proxy

Usa um servidor proxy para a solicitação, em vez de se conectar diretamente ao recurso da Internet. Insira o URI de um servidor proxy de rede.

Tipo:	Uri
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-ProxyCredential

Especifica uma conta de usuário que tem permissão para usar o servidor proxy especificado pelo parâmetro -Proxy. O padrão é o usuário atual.

Digite um nome de usuário, como "User01" ou "Domain01\User01", ou insira um objeto PSCredential, como um gerado pelo cmdlet Get-Credential.

Esse parâmetro é válido somente quando o parâmetro -Proxy também é usado no comando. Não é possível usar os parâmetros -ProxyCredential e -ProxyUseDefaultCredentials no mesmo comando.

Tipo:	PSCredential
Cargo:	Named
Valor padrão:	Current user
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-ProxyUseDefaultCredentials

Usa as credenciais do usuário atual para acessar o servidor proxy especificado pelo parâmetro -Proxy.

Esse parâmetro é válido somente quando o parâmetro -Proxy também é usado no comando. Não é possível usar os parâmetros -ProxyCredential e -ProxyUseDefaultCredentials no mesmo comando.

Tipo:	SwitchParameter
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-SessionVariable

Cria uma sessão de solicitação da Web e a salva no valor da variável especificada. Insira um nome de variável sem o símbolo de cifrão ($).

Quando você especifica uma variável de sessão, Invoke-RestMethod cria um objeto de sessão de solicitação da Web e o atribui a uma variável com o nome especificado na sessão do Windows PowerShell. Você pode usar a variável em sua sessão assim que o comando for concluído.

Ao contrário de uma sessão remota, a sessão de solicitação da Web não é uma conexão persistente. É um objeto que contém informações sobre a conexão e a solicitação, incluindo cookies, credenciais, o valor máximo de redirecionamento e a cadeia de caracteres do agente do usuário. Você pode usá-lo para compartilhar o estado e os dados entre solicitações da Web.

Para usar a sessão de solicitação da Web em solicitações web subsequentes, especifique a variável de sessão no valor do parâmetro -WebSession. O Windows PowerShell usa os dados no objeto de sessão de solicitação da Web ao estabelecer a nova conexão. Para substituir um valor na sessão de solicitação da Web, use um parâmetro cmdlet, como -UserAgent ou -Credential. Os valores de parâmetro têm precedência sobre valores na sessão de solicitação da Web.

Não é possível usar os parâmetros -SessionVariable e -WebSession no mesmo comando.

Tipo:	String
Aliases:	SV
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-TimeoutSec

Especifica quanto tempo a solicitação pode ficar pendente antes de atingir o tempo limite. Insira um valor em segundos. O valor padrão, 0, especifica um tempo limite indefinido.

Uma consulta DNS (Sistema de Nomes de Domínio) pode levar até 15 segundos para retornar ou um tempo limite. Se sua solicitação contiver um nome de host que exija resolução e você definir TimeoutSec como um valor maior que zero, mas menor que 15 segundos, poderá levar 15 segundos ou mais antes que uma WebException seja gerada e sua solicitação atingirá o tempo limite.

Tipo:	Int32
Cargo:	Named
Valor padrão:	0
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-TransferEncoding

Especifica um valor para o cabeçalho de resposta HTTP de codificação de transferência. Os valores aceitáveis para este parâmetro são:

Blocos
Comprimir
Deflacionar
GZip
Identidade

Tipo:	String
Valores aceitos:	chunked, compress, deflate, gzip, identity
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-Uri

Especifica o URI (Uniform Resource Identifier) do recurso da Internet para o qual a solicitação da Web é enviada. Esse parâmetro dá suporte a valores HTTP, HTTPS, FTP e FILE.

Esse parâmetro é necessário. O nome do parâmetro (-Uri) é opcional.

Tipo:	Uri
Cargo:	0
Valor padrão:	None
Obrigatório:	True
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-UseBasicParsing

Indica que o cmdlet usa análise básica. O cmdlet retorna o HTML bruto em um objeto String.

Tipo:	SwitchParameter
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-UseDefaultCredentials

Usa as credenciais do usuário atual para enviar a solicitação da Web.

Tipo:	SwitchParameter
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-UserAgent

Especifica uma cadeia de caracteres de agente de usuário para a solicitação da Web.

O agente de usuário padrão é semelhante a "Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US) WindowsPowerShell/3.0" com pequenas variações para cada sistema operacional e plataforma.

Para testar um site com a cadeia de caracteres de agente de usuário padrão usada pela maioria dos navegadores da Internet, use as propriedades da classe PSUserAgent, como Chrome, FireFox, Internet Explorer, Opera e Safari.

Por exemplo, o comando a seguir usa a cadeia de caracteres do agente de usuário para a Internet

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

Tipo:	String
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-WebSession

Especifica uma sessão de solicitação da Web. Insira o nome da variável, incluindo o sinal de dólar ($).

Para substituir um valor na sessão de solicitação da Web, use um parâmetro cmdlet, como -UserAgent ou -Credential. Os valores de parâmetro têm precedência sobre valores na sessão de solicitação da Web.

Para criar uma sessão de solicitação da Web, insira um nome de variável (sem um sinal de dólar) no valor do parâmetro -SessionVariable de um comando Invoke-RestMethod. Invoke-RestMethod cria a sessão e a salva na variável. Nos comandos subsequentes, use a variável como o valor do parâmetro -WebSession.

Não é possível usar os parâmetros -SessionVariable e -WebSession no mesmo comando.

Tipo:	WebRequestSession
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

Entradas

Object

Você pode canalizar o corpo de uma solicitação da Web para Invoke-RestMethod.

Saídas

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

A saída do cmdlet depende do formato do conteúdo recuperado.

PSObject

Se a solicitação retornar cadeias de caracteres JSON, Invoke-RestMethod retornará um PSObject que representa as cadeias de caracteres.

Compartilhar via

Invoke-RestMethod

Sintaxe

Description

Exemplos

Exemplo 1: Obter o feed RSS do PowerShell

Exemplo 2

Exemplo 3: Passar vários cabeçalhos

Parâmetros

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

Entradas

Saídas

Recursos adicionais

Compartilhar via

Invoke-RestMethod

Sintaxe

Description

Exemplos

Exemplo 1: Obter o feed RSS do PowerShell

Exemplo 2

Exemplo 3: Passar vários cabeçalhos

Parâmetros

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

Entradas

Saídas

Links Relacionados

Recursos adicionais