Invoke-RestMethod
Envia uma solicitação HTTP ou HTTPS para um serviço Web RESTful.
Sintaxe
Default (Predefinição)
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 (Representational State Transfer) que retornam dados ricamente estruturados.
O Windows PowerShell formata a resposta com base no tipo de dados. Para um feed RSS ou ATOM, o Windows PowerShell retorna os nós XML de Item ou Entrada. Para JavaScript Object Notation (JSON) ou XML, o Windows PowerShell converte (ou desserializa) o conteúdo em objetos.
Este cmdlet é introduzido no Windows PowerShell 3.0.
Observação
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.
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 encaminhar um valor do 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 IDiccionário (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 padrão name=value.
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 de 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].Name = "MyName"
$R.Forms[0].Password = "MyPassword"
Invoke-RestMethod https://website.com/service.aspx -Body $R.Forms[0]
Propriedades dos parâmetros
| Tipo: | Object |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | True |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Certificate
Especifica o certificado de cliente que é usado para uma solicitação da Web segura. Insira uma variável que contenha um certificado ou um comando ou expressão que obtenha o certificado.
Para localizar um certificado, use Get-PfxCertificate ou use o cmdlet Get-ChildItem na unidade Certificate (Cert:).
Se o certificado não for válido ou não tiver autoridade suficiente, o comando falhará.
Propriedades dos parâmetros
| Tipo: | X509Certificate |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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 (thumbprint) do certificado.
Os certificados são usados na autenticação baseada em certificado de cliente. Eles podem ser mapeados apenas para contas de usuário locais; eles não funcionam com contas de domínio.
Para obter uma impressão digital de certificado, use o comando Get-Item ou Get-ChildItem na unidade Windows PowerShell (Cert:).
Propriedades dos parâmetros
| Tipo: | String |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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.
Propriedades dos parâmetros
| Tipo: | String |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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.
Propriedades dos parâmetros
| Tipo: | PSCredential |
| Default value: | Current user |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-DisableKeepAlive
Define o valor de KeepAlive no cabeçalho HTTP como False. Por padrão, KeepAlive é True. KeepAlive estabelece uma conexão persistente com o servidor para facilitar solicitações subsequentes.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | KeepAlive |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Headers
Especifica os cabeçalhos da solicitação da Web. Insira uma tabela de hash ou dicionário.
Para definir cabeçalhos UserAgent, use o parâmetro -UserAgent.
Não é possível usar esse parâmetro para especificar UserAgent ou cabeçalhos de cookies.
Propriedades dos parâmetros
| Tipo: | IDictionary |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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.
Propriedades dos parâmetros
| Tipo: | String |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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.
Propriedades dos parâmetros
| Tipo: | Int32 |
| Default value: | 5 |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Method
Especifica o método usado para a solicitação da Web. Os valores aceitáveis para este parâmetro são:
- Predefinido
- Suprimir
- Obter
- Cabeça
- Unir
- Opções
- Correção
- Publicar
- Put
- Rastreio
Propriedades dos parâmetros
| Tipo: | WebRequestMethod |
| Default value: | Default |
| Valores aceites: | Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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.
Propriedades dos parâmetros
| Tipo: | String |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-PassThru
Retorna os resultados, além de gravá-los em um arquivo.
Esse parâmetro é válido somente quando o parâmetro -OutFile também é usado no comando.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | No output |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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.
Propriedades dos parâmetros
| Tipo: | Uri |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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.
Propriedades dos parâmetros
| Tipo: | PSCredential |
| Default value: | Current user |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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 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 em sua 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 estado e dados entre solicitações da Web.
Para usar a sessão de solicitação da Web em solicitações da 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 de cmdlet, como -UserAgent ou -Credential.
Os valores dos parâmetros têm precedência sobre os valores na sessão de solicitação da Web.
Não é possível usar os parâmetros -SessionVariable e -WebSession no mesmo comando.
Propriedades dos parâmetros
| Tipo: | String |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
| Aliases: | SV |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-TimeoutSec
Especifica por 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 atingir o tempo limite. Se sua solicitação contiver um nome de host que exija resolução e você definir TimeoutSec para um valor maior que zero, mas inferior a 15 segundos, pode levar 15 segundos ou mais antes que uma WebException seja lançada e sua solicitação atinja o tempo limite.
Propriedades dos parâmetros
| Tipo: | Int32 |
| Default value: | 0 |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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:
- Segmentado
- Comprimir
- Desinflar
- GZip
- Identidade
Propriedades dos parâmetros
| Tipo: | String |
| Default value: | None |
| Valores aceites: | chunked, compress, deflate, gzip, identity |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Uri
Especifica o URI (Uniform Resource Identifier) do recurso da Internet para o qual a solicitação da Web é enviada. Este parâmetro suporta valores HTTP, HTTPS, FTP e FILE.
Este parâmetro é obrigatório.
O nome do parâmetro (-Uri) é opcional.
Propriedades dos parâmetros
| Tipo: | Uri |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | 0 |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-UseBasicParsing
Indica que o cmdlet usa análise básica. O cmdlet retorna o HTML bruto num String objeto.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-UseDefaultCredentials
Usa as credenciais do usuário atual para enviar a solicitação da Web.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-UserAgent
Especifica uma string de agente do 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 padrão do agente do usuário usada pela maioria dos navegadores da Internet, use as propriedades da classe PSUserAgent do
Por exemplo, o comando a seguir usa a cadeia de caracteres do agente do usuário para a Internet
Invoke-WebRequest -Uri https://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)
Propriedades dos parâmetros
| Tipo: | String |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-WebSession
Especifica uma sessão de solicitação da Web.
Insira o nome da variável, incluindo o cifrão ($).
Para substituir um valor na sessão de solicitação da Web, use um parâmetro de cmdlet, como -UserAgent ou -Credential.
Os valores dos parâmetros têm precedência sobre os valores na sessão de solicitação da Web.
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 estado e dados entre solicitações da Web.
Para criar uma sessão de solicitação da Web, insira um nome de variável (sem cifrão) no valor do parâmetro -SessionVariable de um comando Invoke-RestMethod.
Invoke-RestMethod cria a sessão e a salva na variável.
Em 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.
Propriedades dos parâmetros
| Tipo: | WebRequestSession |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
CommonParameters
Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.
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.