Invoke-RestMethod
Envia uma solicitação HTTP ou HTTPS para um serviço Web RESTful.
Sintaxe
Default (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>]
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.
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 da solicitação é o conteúdo que segue os cabeçalhos.
Você também pode redirecionar 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].Name = "MyName"
$R.Forms[0].Password = "MyPassword"
Invoke-RestMethod https://website.com/service.aspx -Body $R.Forms[0]
Propriedades do parâmetro
| Tipo: | Object |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | True |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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á.
Propriedades do parâmetro
| Tipo: | X509Certificate |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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:).
Propriedades do parâmetro
| Tipo: | String |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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 do parâmetro
| Tipo: | String |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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 do parâmetro
| Tipo: | PSCredential |
| Valor padrão: | Current user |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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.
Propriedades do parâmetro
| Tipo: | SwitchParameter |
| Valor padrão: | KeepAlive |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-Headers
Especifica os cabeçalhos da solicitação da Web. Insira uma tabela hash ou um dicionário.
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.
Propriedades do parâmetro
| Tipo: | IDictionary |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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 do parâmetro
| Tipo: | String |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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 do parâmetro
| Tipo: | Int32 |
| Valor padrão: | 5 |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-Method
Especifica o método usado para a solicitação da Web. Os valores aceitáveis para este parâmetro são:
- Padrão
- Excluir
- Obter
- Head
- Mesclar
- Opções
- Patch
- Postar
- Put
- Traço
Propriedades do parâmetro
| Tipo: | WebRequestMethod |
| Valor padrão: | Default |
| Valores aceitos: | Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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 do parâmetro
| Tipo: | String |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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.
Propriedades do parâmetro
| Tipo: | SwitchParameter |
| Valor padrão: | No output |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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 do parâmetro
| Tipo: | Uri |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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 do parâmetro
| Tipo: | PSCredential |
| Valor padrão: | Current user |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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 do parâmetro
| Tipo: | SwitchParameter |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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.
Propriedades do parâmetro
| Tipo: | String |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
| Aliases: | SV |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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 expirar. 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, podem se passar 15 segundos ou mais antes que uma WebException seja gerada e sua solicitação expire devido ao tempo limite.
Propriedades do parâmetro
| Tipo: | Int32 |
| Valor padrão: | 0 |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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:
- Em partes
- Comprimir
- Deflate
- GZip
- Identidade
Propriedades do parâmetro
| Tipo: | String |
| Valor padrão: | None |
| Valores aceitos: | chunked, compress, deflate, gzip, identity |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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.
Este parâmetro é obrigatório.
O nome do parâmetro (-Uri) é opcional.
Propriedades do parâmetro
| Tipo: | Uri |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | 0 |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-UseBasicParsing
Indica que o cmdlet usa análise básica. O cmdlet retorna o HTML bruto em um objeto String.
Propriedades do parâmetro
| Tipo: | SwitchParameter |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-UseDefaultCredentials
Usa as credenciais do usuário atual para enviar a solicitação da Web.
Propriedades do parâmetro
| Tipo: | SwitchParameter |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-UserAgent
Especifica um string de agente de usuário para a requisição 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)
Propriedades do parâmetro
| Tipo: | String |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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.
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 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.
Propriedades do parâmetro
| Tipo: | WebRequestSession |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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.