Invoke-RestMethod

Referência

Módulo:: Microsoft.PowerShell.Utility

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

Syntax

Invoke-RestMethod
      [-Method <WebRequestMethod>]
      [-FollowRelLink]
      [-MaximumFollowRelLink <Int32>]
      [-ResponseHeadersVariable <String>]
      [-StatusCodeVariable <String>]
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-RetryIntervalSec <Int32>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [-PreserveAuthorizationOnRedirect]
      [-SkipHeaderValidation]
      [<CommonParameters>]

Invoke-RestMethod
      [-Method <WebRequestMethod>]
      [-FollowRelLink]
      [-MaximumFollowRelLink <Int32>]
      [-ResponseHeadersVariable <String>]
      [-StatusCodeVariable <String>]
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-RetryIntervalSec <Int32>]
      -NoProxy
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [-PreserveAuthorizationOnRedirect]
      [-SkipHeaderValidation]
      [<CommonParameters>]

Invoke-RestMethod
      -CustomMethod <String>
      [-FollowRelLink]
      [-MaximumFollowRelLink <Int32>]
      [-ResponseHeadersVariable <String>]
      [-StatusCodeVariable <String>]
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-RetryIntervalSec <Int32>]
      -NoProxy
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [-PreserveAuthorizationOnRedirect]
      [-SkipHeaderValidation]
      [<CommonParameters>]

Invoke-RestMethod
      -CustomMethod <String>
      [-FollowRelLink]
      [-MaximumFollowRelLink <Int32>]
      [-ResponseHeadersVariable <String>]
      [-StatusCodeVariable <String>]
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-RetryIntervalSec <Int32>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [-PreserveAuthorizationOnRedirect]
      [-SkipHeaderValidation]
      [<CommonParameters>]

Description

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

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

Observação

Quando o ponto de extremidade REST retorna vários objetos, os objetos são recebidos como uma matriz. Se você redirecionar a saída de Invoke-RestMethod para outro comando, ela será enviada como um único [Object[]] objeto. O conteúdo dessa matriz não é enumerado para o próximo comando no pipeline.

Este cmdlet é introduzido no Windows PowerShell 3.0.

A partir do PowerShell 7.0, Invoke-RestMethod o dá suporte à configuração de proxy definida por variáveis de ambiente. Consulte a seção Anotações deste artigo.

Exemplos

Exemplo 1: Obter o RSS feed do PowerShell

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

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

Exemplo 2: executar uma solicitação POST

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

$Cred = Get-Credential
$Url = "https://server.contoso.com:8089/services/search/jobs/export"
$Body = @{
    search = "search index=_internal | reverse | table index,host,source,sourcetype,_raw"
    output_mode = "csv"
    earliest_time = "-2d@d"
    latest_time = "-1d@d"
}
Invoke-RestMethod -Method 'Post' -Uri $url -Credential $Cred -Body $body -OutFile output.csv

As credenciais são solicitadas e armazenadas no $Cred e a URL que será acessada é definida em $Url.

A $Body variável descreve os critérios de pesquisa, especifica CSV como o modo de saída e especifica um período de tempo para dados retornados que começa há dois dias e termina há um dia. A variável body especifica valores para parâmetros que se aplicam à API REST específica com a qual Invoke-RestMethod está se comunicando.

O Invoke-RestMethod comando é executado com todas as variáveis em vigor, especificando um caminho e um nome de arquivo para o arquivo de saída CSV resultante.

Exemplo 3: Seguir links de relação

Algumas APIs REST dão suporte à paginação por meio de Links de Relação por RFC5988. Em vez de analisar o cabeçalho para obter a URL da próxima página, você pode fazer com que o cmdlet faça isso para você. Este exemplo retorna as duas primeiras páginas de problemas do repositório GitHub do PowerShell.

$url = 'https://api.github.com/repos/powershell/powershell/issues'
Invoke-RestMethod $url -FollowRelLink -MaximumFollowRelLink 2

Exemplo 4: Envio simplificado de dados de várias partes/formulários

Algumas APIs exigem multipart/form-data envios para carregar arquivos e conteúdo misto. Este exemplo demonstra como atualizar o perfil de um usuário.

$Uri = 'https://api.contoso.com/v2/profile'
$Form = @{
    firstName  = 'John'
    lastName   = 'Doe'
    email      = 'john.doe@contoso.com'
    avatar     = Get-Item -Path 'c:\Pictures\jdoe.png'
    birthday   = '1980-10-15'
    hobbies    = 'Hiking','Fishing','Jogging'
}
$Result = Invoke-RestMethod -Uri $Uri -Method Post -Form $Form

O formulário de perfil requer estes campos: firstName, lastName, email, avatar, birthdaye hobbies. A API espera que uma imagem para a foto de perfil do usuário seja fornecida no avatar campo. A API também aceitará várias hobbies entradas a serem enviadas no mesmo formulário.

Ao criar o $Form HashTable, os nomes de chave são usados como nomes de campo de formulário. Por padrão, os valores da HashTable serão convertidos em cadeias de caracteres. Se um System.IO.FileInfo valor estiver presente, o conteúdo do arquivo será enviado. Se uma coleção como matrizes ou listas estiver presente, o campo de formulário será enviado várias vezes.

Get-Item Usando na avatar chave , o FileInfo objeto será definido como o valor . O resultado é que os dados de imagem para jdoe.png serão enviados.

Ao fornecer uma lista para a hobbies chave, o hobbies campo estará presente nos envios uma vez para cada item de lista.

Exemplo 5: passar vários cabeçalhos

As APIs geralmente exigem cabeçalhos passados para autenticação ou validação. Este exemplo demonstra como passar vários cabeçalhos de um hash-table para uma API REST.

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

Exemplo 6: enumerar itens retornados no pipeline

O GitHub retorna vários objetos de uma matriz. Se você redirecionar a saída para outro comando, ela será enviada como um único [Object[]]objeto.

Para enumerar os objetos no pipeline, redirecione os resultados para Write-Output ou encapsule o cmdlet entre parênteses. O exemplo a seguir conta o número de objetos retornados pelo GitHub. Em seguida, conta o número de objetos enumerados para o pipeline.

$uri = 'https://api.github.com/repos/microsoftdocs/powershell-docs/issues'
$x = 0
Invoke-RestMethod -Uri $uri | ForEach-Object { $x++ }
$x
1

$x = 0
(Invoke-RestMethod -Uri $uri) | ForEach-Object { $x++ }
$x
30

$x = 0
Invoke-RestMethod -Uri $uri | Write-Output | ForEach-Object { $x++ }
$x
30

Parâmetros

-AllowUnencryptedAuthentication

Permite o envio de credenciais e segredos por conexões não criptografadas. Por padrão, fornecer credencial ou qualquer opção de autenticação com um Uri que não comece com https:// resultará em um erro e a solicitação será anulada para evitar a comunicação acidental de segredos em texto sem formatação em conexões não criptografadas. Para substituir esse comportamento por sua conta e risco, forneça o parâmetro AllowUnencryptedAuthentication .

Aviso

O uso desse parâmetro não é seguro e não é recomendado. Ele é fornecido apenas para compatibilidade com sistemas herdados que não podem fornecer conexões criptografadas. Use por sua conta e risco.

Esse recurso foi adicionado ao PowerShell 6.0.0.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Authentication

Especifica o tipo de autenticação explícita a ser usado para a solicitação. O padrão é Nenhum. O parâmetro Authentication não pode ser usado com o parâmetro UseDefaultCredentials .

Opções de autenticação disponíveis:

None: essa é a opção padrão quando a Autenticação não é fornecida. Nenhuma autenticação explícita será usada.
Basic: requer Credencial. As credenciais serão usadas para enviar um cabeçalho de Autenticação Authorization: Basic Básica RFC 7617 no formato .base64(user:password)
Bearer: requer o parâmetro Token . Envia um cabeçalho RFC 6750 Authorization: Bearer com o token fornecido.
OAuth: requer o parâmetro Token . Envia um cabeçalho RFC 6750 Authorization: Bearer com o token fornecido.

Fornecer Autenticação substitui todos Authorization os cabeçalhos fornecidos para Cabeçalhos ou incluídos na WebSession.

Esse recurso foi adicionado ao PowerShell 6.0.0.

Type:	WebAuthenticationType
Accepted values:	None, Basic, Bearer, OAuth
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Body

Especifica o corpo da solicitação. O corpo é o conteúdo da solicitação 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 (Uniform Resource Identifier) 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.

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

O parâmetro Body também pode aceitar um objeto System.Net.Http.MultipartFormDataContent . Isso facilitará multipart/form-data as solicitações. Quando um objeto MultipartFormDataContent é fornecido para Body, todos os cabeçalhos relacionados ao conteúdo fornecidos aos parâmetros ContentType, Headers ou WebSession serão substituídos pelos cabeçalhos de conteúdo do MultipartFormDataContent objeto. Esse recurso foi adicionado ao PowerShell 6.0.0.

Type:	Object
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-Certificate

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

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

Type:	X509Certificate
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-CertificateThumbprint

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

Os certificados são utilizados na autenticação baseada em certificado do cliente. Eles podem ser mapeados somente 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 Get-Item comando ou Get-ChildItem na unidade do PowerShell Cert: .

Observação

Atualmente, esse recurso só tem suporte em plataformas do sistema operacional Windows.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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.

ContentType será substituído quando um MultipartFormDataContent objeto for fornecido para Body.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Credential

Especifica uma conta de usuário com 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 gerado pelo Get-Credential cmdlet .

A credencial pode ser usada sozinha ou em conjunto com determinadas opções de parâmetro de autenticação . Quando usado sozinho, ele só fornecerá credenciais para o servidor remoto se o servidor remoto enviar uma solicitação de desafio de autenticação. Quando usadas com opções de autenticação , as credenciais serão enviadas explicitamente.

As credenciais são armazenadas em um objeto PSCredential e a senha é armazenada como um SecureString.

Observação

Para obter mais informações sobre a proteção de dados SecureString , consulte Quão seguro é SecureString?.

Type:	PSCredential
Position:	Named
Default value:	Current user
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-CustomMethod

Especifica o método personalizado usado para a solicitação da Web. Isso pode ser usado com o Método de Solicitação exigido pelo ponto de extremidade não é uma opção disponível no Método . O método e o CustomMethod não podem ser usados juntos.

Exemplo:

Invoke-RestMethod -uri 'https://api.contoso.com/widget/' -CustomMethod 'TEST'

Isso faz uma solicitação TEST HTTP para a API.

Esse recurso foi adicionado ao PowerShell 6.0.0.

Type:	String
Aliases:	CM
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-DisableKeepAlive

Indica que o cmdlet define o valor KeepAlive no cabeçalho HTTP como False. Por padrão, KeepAlive é Verdadeiro. KeepAliveestabelece uma conexão persistente com o servidor para facilitar as solicitações posteriores.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-FollowRelLink

Indica que o cmdlet deve seguir links de relação.

Algumas APIs REST dão suporte à paginação por meio de Links de Relação por RFC5988. Em vez de analisar o cabeçalho para obter a URL da próxima página, você pode fazer com que o cmdlet faça isso para você. Para definir quantas vezes seguir links de relação, use o parâmetro MaximumFollowRelLink .

Ao usar essa opção, o cmdlet retorna uma coleção de páginas de resultados. Cada página de resultados pode conter vários itens de resultado.

Esse recurso foi adicionado ao PowerShell 6.0.0.

Type:	SwitchParameter
Aliases:	FL
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Form

Converte um dicionário em um multipart/form-data envio. O formulário não pode ser usado com Corpo. Se ContentType for ignorado.

As chaves do dicionário serão usadas como nomes de campo de formulário. Por padrão, os valores de formulário serão convertidos em valores de cadeia de caracteres.

Se o valor for um objeto System.IO.FileInfo , o conteúdo do arquivo binário será enviado. O nome do arquivo será enviado como o filename. O MIME será definido como application/octet-stream. Get-Item pode ser usado para simplificar o fornecimento do objeto System.IO.FileInfo .

$Form = @{ resume = Get-Item 'c:\Users\jdoe\Documents\John Doe.pdf' }

Se o valor for um tipo de coleção, como uma Matriz ou Uma Lista, o campo for será enviado várias vezes. Os valores da lista serão tratados como cadeias de caracteres por padrão. Se o valor for um objeto System.IO.FileInfo , o conteúdo do arquivo binário será enviado. Não há suporte para coleções aninhadas.

$Form = marcas @{ = 'Vacation', 'Italy', '2017' pictures = Get-ChildItem 'c:\Users\jdoe\Pictures\2017-Italy' }

No exemplo acima, o tags campo será fornecido três vezes no formulário, uma vez para cada um dos Vacation, Italye 2017. O pictures campo também será enviado uma vez para cada arquivo na 2017-Italy pasta. O conteúdo binário dos arquivos nessa pasta será enviado como os valores.

Esse recurso foi adicionado ao PowerShell 6.1.0.

Type:	IDictionary
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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 User-Agent ou cabeçalhos de cookie.

Cabeçalhos relacionados ao conteúdo, como Content-Type , serão substituídos quando um MultipartFormDataContent objeto for fornecido para Corpo.

Type:	IDictionary
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-InFile

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

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

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MaximumFollowRelLink

Especifica quantas vezes seguir links de relação se FollowRelLink for usado. Um valor menor poderá ser necessário se a API REST for limitada devido a muitas solicitações. O valor padrão é [Int32]::MaxValue. Um valor de 0 (zero) impede os links de relação a seguir.

Type:	Int32
Aliases:	ML
Position:	Named
Default value:	Int32.MaxValue
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MaximumRedirection

Especifica quantas vezes o 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 qualquer redirecionamento.

Type:	Int32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MaximumRetryCount

Especifica quantas vezes o PowerShell tenta novamente uma conexão quando um código de falha entre 400 e 599, inclusive ou 304 é recebido. Consulte também o parâmetro RetryIntervalSec para especificar o número de repetições.

Type:	Int32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Method

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

Default
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace

O parâmetro CustomMethod pode ser usado para métodos de solicitação não listados acima.

Type:	WebRequestMethod
Accepted values:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-NoProxy

Indica que o cmdlet não usará um proxy para chegar ao destino.

Quando precisar ignorar o proxy configurado no Explorer da Internet ou um proxy especificado no ambiente, use essa opção.

Esse parâmetro foi introduzido no PowerShell 6.0.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-OutFile

Salva o corpo da resposta no arquivo de saída especificado. Digite um caminho e nome de arquivo. Se você omitir o caminho, o padrão será o local atual. O nome é tratado como um caminho literal. Os nomes que contêm colchetes ([]) devem ser colocados entre aspas simples (').

Por padrão, Invoke-RestMethod retorna os resultados para o pipeline.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-PassThru

Esse parâmetro será válido somente quando o parâmetro OutFile também for utilizado no comando. A intenção é que os resultados sejam gravados no arquivo e no pipeline.

Observação

Quando você usa o parâmetro PassThru , a saída é gravada no pipeline, mas o arquivo não é criado. Para obter mais informações, consulte Problema do PowerShell nº 15409.

Type:	SwitchParameter
Position:	Named
Default value:	No output
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-PreserveAuthorizationOnRedirect

Indica que o cmdlet deve preservar o Authorization cabeçalho, quando presente, entre redirecionamentos.

Por padrão, o cmdlet remove o Authorization cabeçalho antes de redirecionar. Especificar esse parâmetro desabilita essa lógica para casos em que o cabeçalho precisa ser enviado para o local de redirecionamento.

Esse recurso foi adicionado ao PowerShell 6.0.0.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Proxy

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

Esse recurso foi adicionado ao PowerShell 6.0.0.

Type:	Uri
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ProxyCredential

Especifica uma conta de usuário com permissão para conectar-se aos computadores especificados pelo parâmetro Proxy. O padrão é o usuário atual.

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

Esse parâmetro é válido somente quando o parâmetro Proxy também é usado no comando . Você não pode usar os parâmetros ProxyCredential e ProxyUseDefaultCredentials no mesmo comando.

Type:	PSCredential
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ProxyUseDefaultCredentials

Indica que o cmdlet usa as credenciais do usuário atual para acessar o servidor proxy especificado pelo parâmetro Proxy .

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ResponseHeadersVariable

Cria uma variável que contém um Dicionário de Cabeçalhos de Resposta. Insira um nome de variável sem o símbolo de cifrão ($). As chaves do dicionário contêm os nomes de campo e os valores do Cabeçalho de Resposta retornados pelo servidor Web.

Esse recurso foi adicionado ao PowerShell 6.0.0.

Type:	String
Aliases:	RHV
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Resume

Executa uma tentativa de melhor esforço para retomar o download de um arquivo parcial. O parâmetro Resume requer o parâmetro OutFile .

O Resume opera apenas no tamanho do arquivo local e do arquivo remoto e não executa nenhuma outra validação de que o arquivo local e o arquivo remoto sejam os mesmos.

Se o tamanho do arquivo local for menor que o tamanho do arquivo remoto, o cmdlet tentará retomar o download do arquivo e acrescentar os bytes restantes ao final do arquivo.

Se o tamanho do arquivo local for o mesmo que o tamanho do arquivo remoto, nenhuma ação será tomada e o cmdlet assumirá que o download já foi concluído.

Se o tamanho do arquivo local for maior que o tamanho do arquivo remoto, o arquivo local será substituído e todo o arquivo remoto será completamente baixado. Esse comportamento é o mesmo que usar OutFile sem Resume.

Se o servidor remoto não der suporte à retomada do download, o arquivo local será substituído e todo o arquivo remoto será completamente baixado. Esse comportamento é o mesmo que usar OutFile sem Resume.

Se o arquivo local não existir, o arquivo local será criado e todo o arquivo remoto será completamente baixado. Esse comportamento é o mesmo que usar OutFile sem Resume.

Esse recurso foi adicionado ao PowerShell 6.1.0.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-RetryIntervalSec

Especifica o intervalo entre novas tentativas para a conexão quando um código de falha entre 400 e 599, inclusive ou 304 é recebido. Consulte também o parâmetro MaximumRetryCount para especificar o número de repetições.

Type:	Int32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SessionVariable

Cria uma variável que contém a sessão de solicitação da Web. 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 em sua sessão do PowerShell. Você pode usar a variável na 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 nas solicitações da Web posteriores, especifique a variável de sessão no valor do parâmetro WebSession. O 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. Valores de parâmetro têm precedência sobre valores na seção de solicitação da Web.

Você não pode usar os parâmetros SessionVariable e WebSession no mesmo comando.

Type:	String
Aliases:	SV
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SkipCertificateCheck

Ignora verificações de validação de certificado que incluem todas as validações, como expiração, revogação, autoridade raiz confiável etc.

Aviso

O uso desse parâmetro não é seguro e não é recomendado. Essa opção destina-se apenas a ser usada em hosts conhecidos usando um certificado autoassinado para fins de teste. Use por sua conta e risco.

Esse recurso foi adicionado ao PowerShell 6.0.0.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SkipHeaderValidation

Indica que o cmdlet deve adicionar cabeçalhos à solicitação sem validação.

Essa opção deve ser usada para sites que exigem valores de cabeçalho que não estão em conformidade com os padrões. Especificar essa opção desabilita a validação para permitir que o valor seja passado desmarcado. Quando especificado, todos os cabeçalhos são adicionados sem validação.

Isso desabilitará a validação de valores passados para os parâmetrosContentType, Headers e UserAgent.

Esse recurso foi adicionado ao PowerShell 6.0.0.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SkipHttpErrorCheck

Esse parâmetro faz com que o cmdlet ignore os status de erro HTTP e continue processando respostas. As respostas de erro são gravadas no pipeline como se tivessem sido bem-sucedidas.

Esse parâmetro foi introduzido no PowerShell 7.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SslProtocol

Define os protocolos SSL/TLS que são permitidos para a solicitação da Web. Por padrão, todos os protocolos SSL/TLS compatíveis com o sistema são permitidos. O SslProtocol permite a limitação de protocolos específicos para fins de conformidade.

Esses valores são definidos como uma enumeração baseada em sinalizador. Você pode combinar vários valores para definir vários sinalizadores usando esse parâmetro. Os valores podem ser passados para o parâmetro SslProtocol como uma matriz de valores ou como uma cadeia de caracteres separada por vírgulas desses valores. O cmdlet combinará os valores usando uma operação binary-OR. Passar valores como uma matriz é a opção mais simples e também permite que você use a conclusão de tabulação nos valores. Talvez você não consiga fornecer vários valores em todas as plataformas.

Observação

Em plataformas não Windows, pode não ser possível fornecer Tls ou Tls12 como uma opção. O suporte para Tls13 não está disponível em todos os sistemas operacionais e precisará ser verificado por sistema operacional.

Esse recurso foi adicionado ao PowerShell 6.0.0 e o suporte para Tls13 foi adicionado ao PowerShell 7.1.

Type:	WebSslProtocol
Accepted values:	Default, Tls, Tls11, Tls12, Tls13
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-StatusCodeVariable

Cria uma variável que contém um http status resultado do código da solicitação. Insira um nome de variável sem o símbolo de cifrão ($).

O parâmetro pode identificar mensagens de êxito ou mensagens de falha quando usado com o parâmetro SkipHttpErrorCheck .

Insira o nome da variável do parâmetro como uma cadeia de caracteres como -StatusCodeVariable "scv".

Esse parâmetro foi introduzido no PowerShell 7.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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 lançada e sua solicitação expirar.

Type:	Int32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Token

O token OAuth ou Bearer a ser incluído na solicitação. O token é exigido por determinadas opções de autenticação . Ele não pode ser usado de forma independente.

O token usa um SecureString que contém o token. Para fornecer o token, use manualmente o seguinte:

Invoke-RestMethod -Uri $uri -Authentication OAuth -Token (Read-Host -AsSecureString)

Esse parâmetro foi introduzido no PowerShell 6.0.

Type:	SecureString
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-TransferEncoding

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

Blocos
Compactar
Desinflar
GZip
Identidade

Type:	String
Accepted values:	chunked, compress, deflate, gzip, identity
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Uri

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

Este parâmetro é necessário. O URI (nome do parâmetro) é opcional.

Type:	Uri
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-UseBasicParsing

Esse parâmetro foi preterido. A partir do PowerShell 6.0.0, todas as solicitações da Web usam somente análise básica. Esse parâmetro está incluído apenas para compatibilidade com versões anteriores e qualquer uso dele não terá efeito sobre a operação do cmdlet.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-UseDefaultCredentials

Indica que o cmdlet usa as credenciais do usuário atual para enviar a solicitação da Web. Isso não pode ser usado com Autenticação ou Credencial e pode não ter suporte em todas as plataformas.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-UserAgent

Especifica uma cadeia de caracteres 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 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.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, InternetExplorer, Opera e Safari.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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. Valores de parâmetro têm precedência sobre valores na seção de solicitação da Web. Cabeçalhos relacionados ao conteúdo, como Content-Type, também serão substituídos quando um objeto MultipartFormDataContent for fornecido para Body.

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 Invoke-RestMethod comando. Invoke-RestMethod cria a sessão e a salva na variável . Em comandos posteriores, use a variável como o valor do parâmetro WebSession.

Você não pode usar os parâmetros SessionVariable e WebSession no mesmo comando.

Type:	WebRequestSession
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

Entradas

Object

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

Saídas

System.Int64, System.String, System.Xml.XmlDocument

A saída do cmdlet depende do formato do conteúdo que é obtido.

PSObject

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

Observações

Alguns recursos podem não estar disponíveis em todas as plataformas.

Devido a alterações no .NET Core 3.1, o PowerShell 7.0 e superior usam a propriedade HttpClient.DefaultProxy para determinar a configuração do proxy.

O valor dessa propriedade é regras diferentes, dependendo da plataforma:

Para Windows: lê a configuração de proxy de variáveis de ambiente ou, se elas não estiverem definidas, das configurações de proxy do usuário.
Para macOS: lê a configuração de proxy de variáveis de ambiente ou, se elas não estiverem definidas, das configurações de proxy do sistema.
Para Linux: lê a configuração de proxy de variáveis de ambiente ou, caso elas não sejam definidas, essa propriedade inicializa uma instância não configurada que ignora todos os endereços.

As variáveis de ambiente usadas para inicialização DefaultProxy em plataformas baseadas em Windows e Unix são:

HTTP_PROXY: o nome do host ou endereço IP do servidor proxy usado em solicitações HTTP.
HTTPS_PROXY: o nome do host ou endereço IP do servidor proxy usado em solicitações HTTPS.
ALL_PROXY: o nome do host ou endereço IP do servidor proxy usado em solicitações HTTP e HTTPS caso HTTP_PROXY ou HTTPS_PROXY não estejam definidos.
NO_PROXY: uma lista separada por vírgulas de nomes de host que devem ser excluídos do proxy.

Share via

Invoke-RestMethod

Syntax

Description

Exemplos

Exemplo 1: Obter o RSS feed do PowerShell

Exemplo 2: executar uma solicitação POST

Exemplo 3: Seguir links de relação

Exemplo 4: Envio simplificado de dados de várias partes/formulários

Exemplo 5: passar vários cabeçalhos

Exemplo 6: enumerar itens retornados no pipeline

Parâmetros

-AllowUnencryptedAuthentication

-Authentication

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-CustomMethod

-DisableKeepAlive

-FollowRelLink

-Form

-Headers

-InFile

-MaximumFollowRelLink

-MaximumRedirection

-MaximumRetryCount

-Method

-NoProxy

-OutFile

-PassThru

-PreserveAuthorizationOnRedirect

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-ResponseHeadersVariable

-Resume

-RetryIntervalSec

-SessionVariable

-SkipCertificateCheck

-SkipHeaderValidation

-SkipHttpErrorCheck

-SslProtocol

-StatusCodeVariable

-TimeoutSec

-Token

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

Entradas

Saídas

Observações

Links Relacionados

Recursos adicionais