Invoke-RestMethod

Módulo:

Microsoft.PowerShell.Utility Module

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

Sintaxe

StandardMethod (Padrão)

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

StandardMethodNoProxy

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

CustomMethod

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

CustomMethodNoProxy

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

Description

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

O PowerShell formata a resposta com base no tipo de dados. Para um feed RSS ou ATOM, o PowerShell retorna os XML nodes Item ou Entry. Para JSON (JavaScript Object Notation) ou XML, o PowerShell converte ou desserializa o conteúdo em objetos [pscustomobject]. Os comentários são permitidos nos dados JSON.

Observação

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

Esse cmdlet é introduzido no Windows PowerShell 3.0.

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

A partir do PowerShell 7.4, a codificação de caracteres para solicitações usa como padrão UTF-8 em vez de ASCII. Se você precisar de uma codificação diferente, deverá definir o atributo charset no cabeçalho Content-Type.

Exemplos

Exemplo 1: Obter o feed RSS do PowerShell

Este exemplo 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.

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

O cmdlet solicita credenciais e as armazena em $Cred. $Url contém a URL do endpoint REST.

A variável $Body 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 de corpo especifica valores para parâmetros que se aplicam à API REST específica com a qual Invoke-RestMethod está se comunicando.

O comando Invoke-RestMethod é 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 relacionamento

Algumas APIs REST dão suporte à paginação via Links de Relação de acordo com a 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 multiparte/dados de formulário simplificado

Algumas APIs exigem envios multipart/form-data 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 da foto do perfil do usuário seja fornecida no campo avatar. A API também aceita várias entradas de hobbies 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 do HashTable são convertidos em cadeias de caracteres. Se um valor System.IO.FileInfo estiver presente, o conteúdo do arquivo será enviado. Se uma coleção, como uma matriz ou lista estiver presente, o campo de formulário será enviado várias vezes.

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

Ao fornecer uma lista para a chave hobbies, o campo hobbies está 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 objeto [Object[]].

Para enumerar os objetos no pipeline, direcione os resultados para Write-Output ou embrulhe 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 no 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

Exemplo 7: Ignorar validação de cabeçalho

Por padrão, o cmdlet Invoke-RestMethod valida os valores de cabeçalhos conhecidos que têm um formato de valor definido por padrões. O exemplo a seguir mostra como essa validação pode gerar um erro e como você pode usar o parâmetro SkipHeaderValidation para evitar a validação de valores para pontos de extremidade que toleram valores formatados inválidos.

$Uri = 'https://httpbin.org/headers'
$InvalidHeaders = @{
    'If-Match' = '12345'
}

Invoke-RestMethod -Uri $Uri -Headers $InvalidHeaders

Invoke-RestMethod -Uri $Uri -Headers $InvalidHeaders -SkipHeaderValidation |
    Format-List

Invoke-RestMethod: The format of value '12345' is invalid.

headers : @{Host=httpbin.org; If-Match=12345; User-Agent=Mozilla/5.0 (Windows NT 10.0; Microsoft Windows
          10.0.19044; en-US) PowerShell/7.2.5;  X-Amzn-Trace-Id=Root=1-62f150a6-27754fd4226f31b43a3d2874}

httpbin.org é um serviço que retorna informações sobre solicitações da Web e respostas para solução de problemas. A variável $Uri é atribuída ao endpoint /headers do serviço, que retorna os cabeçalhos de uma solicitação como conteúdo em sua resposta.

O cabeçalho de solicitação If-Match é definido na RFC-7232 seção 3.1 e requer que o valor desse cabeçalho seja definido entre aspas. A variável $InvalidHeaders recebe uma tabela de hash em que o valor de If-Match é inválido porque é definido como 12345 em vez de "12345".

Chamar Invoke-RestMethod com os cabeçalhos inválidos retorna um relatório de erro informando que o valor formatado é inválido. A solicitação não é enviada para o endpoint.

Chamar Invoke-RestMethod com o parâmetro SkipHeaderValidation ignora a falha de validação e envia a solicitação para o endpoint. Como o ponto de extremidade tolera valores de cabeçalho não compatíveis, o cmdlet retorna o objeto de resposta sem erro.

Exemplo 8: Enviar uma solicitação usando HTTP 2.0

Este exemplo consulta o problema do GitHub usando o protocolo HTTP 2.0.

$uri = 'https://api.github.com/repos/microsoftdocs/powershell-docs/issues'
Invoke-RestMethod -Uri $uri -HttpVersion 2.0 -SkipCertificateCheck

Exemplo 9: Enviar uma solicitação para um aplicativo de soquete Unix

Alguns aplicativos, como o Docker, expõem um soquete Unix para comunicação. Este exemplo consulta uma lista de imagens do Docker usando a API do Docker. O cmdlet se conecta ao daemon do Docker usando o soquete Unix.

Invoke-RestMethod -Uri "http://localhost/v1.40/images/json/" -UnixSocket "/var/run/docker.sock"

Parâmetros

-AllowInsecureRedirect

Permite redirecionamento de HTTPS para HTTP. Por padrão, qualquer solicitação redirecionada de HTTPS para HTTP resulta em um erro e a solicitação é anulada para impedir a comunicação sem querer em texto sem formatação por conexões não criptografadas. Para substituir esse comportamento por sua conta e risco, use o parâmetro AllowInsecureRedirect.

Esse parâmetro foi adicionado no PowerShell 7.4.

Propriedades do parâmetro

Tipo:	SwitchParameter
Valor padrão:	False
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

-AllowUnencryptedAuthentication

Permite o envio de credenciais e segredos em conexões não criptografadas. Por padrão, fornecer uma Credencial ou qualquer opção de Autenticação com um Uri que não começa com https:// resulta em um erro, e a solicitação é cancelada para impedir a comunicação não intencional de segredos em texto em claro por 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.

Propriedades do parâmetro

Tipo:	SwitchParameter
Valor padrão:	False
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

-Authentication

Especifica o tipo de autenticação explícita a ser usado para a solicitação. O padrão é None. O parâmetro de Autenticação 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 é usada.
• Basic: requer Credencial . As credenciais são usadas para enviar um cabeçalho Authorization: Basic de Autenticação Básica RFC 7617 no formato de 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 quaisquer cabeçalhos Authorization fornecidos para Headers ou incluídos em WebSession.

Esse recurso foi adicionado ao PowerShell 6.0.0.

Propriedades do parâmetro

Tipo:	WebAuthenticationType
Valor padrão:	None
Valores aceitos:	None, Basic, Bearer, OAuth
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

-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 solicitação. Para parâmetros de consulta, o cmdlet usa o método System.Net.WebUtility.UrlEncode para codificar os pares chave-valor. Para obter mais informações sobre a codificação de cadeias de caracteres para URLs, consulte a referência do método UrlEncode().

Quando a entrada é uma solicitação POST e o corpo é um String, o valor à esquerda do primeiro sinal igual (=) é definido como uma chave nos dados do formulário e o texto restante é definido como o valor. Para especificar várias chaves, use um objeto IDictionary, como uma tabela de hash, para Body.

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 PATCH), o corpo é definido como o valor do corpo da solicitação no formato de name=value padrão com os valores codificados em URL.

Quando a entrada é um objeto System.Xml.XmlNode e a declaração XML especifica uma codificação, essa codificação é usada para os dados na solicitação, a menos que seja substituída pelo parâmetro ContentType.

Quando o corpo é um formulário ou é a saída de outra chamada Invoke-WebRequest, 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, o que facilita solicitações multipart/form-data. Quando um objeto MultipartFormDataContent é fornecido para Body, todos os cabeçalhos relacionados ao conteúdo fornecidos aos parâmetros ContentType, Headersou WebSession são substituídos pelos cabeçalhos de conteúdo do objeto MultipartFormDataContent. Esse recurso foi adicionado ao PowerShell 6.0.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. Os certificados só podem ser mapeados apenas para contas de usuário locais, não para contas de domínio.

Para ver a impressão digital do certificado, use o comando Get-Item ou Get-ChildItem para localizar o certificado no Cert:\CurrentUser\My.

Observação

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

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

-ConnectionTimeoutSeconds

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 atingir o tempo limite. Se sua solicitação contiver um nome de host que exija resolução e você definir ConnectionTimeoutSeconds com um valor maior que zero, mas menor que 15 segundos, poderá levar 15 segundos ou mais até uma WebException ser emitida e a solicitação exceder o tempo limite.

Esse parâmetro substituiu o parâmetro TimeoutSec no PowerShell 7.4. Você pode usar TimeoutSec como alias para ConnectionTimeoutSeconds.

Propriedades do parâmetro

Tipo:	Int32
Valor padrão:	0
Dá suporte a curingas:	False
DontShow:	False
Aliases:	TimeoutSec

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 o valor de ContentType contiver o formato de codificação (como charset), o cmdlet usará esse formato para codificar o corpo da solicitação da Web. Se o ContentType não especificar um formato de codificação, o formato de codificação padrão será usado. Um exemplo de contentType com um formato de codificação é text/plain; charset=iso-8859-5, que especifica o alfabeto latino/cirílico.

Se você omitir o parâmetro, o tipo de conteúdo poderá ser diferente com base no método HTTP que você usa:

• Para um método POST, o tipo de conteúdo é application/x-www-form-urlencoded
• Para um método PUT, o tipo de conteúdo é application/json
• Para outros métodos, o tipo de conteúdo não é especificado na solicitação

Se você estiver usando o parâmetro InFile para carregar um arquivo, defina o tipo de conteúdo. Normalmente, o tipo deve ser application/octet-stream. No entanto, você precisa definir o tipo de conteúdo com base nos requisitos do ponto de extremidade.

ContentType é substituído quando o Body é um objeto MultipartFormDataContent.

A partir do PowerShell 7.4, se você usar esse parâmetro e o parâmetro Headers para definir o cabeçalho Content-Type, o valor especificado no parâmetro ContentType será usado.

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 gerado pelo cmdlet Get-Credential.

Você pode usar a Credencial sozinha ou em conjunto com algumas opções de parâmetro de Autenticação . Quando usado sozinho, ele só fornece credenciais para o servidor remoto se o servidor remoto envia uma solicitação de desafio de autenticação. Quando usada com as opções de Autenticação , as credenciais sã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 do SecureString, consulte Quão seguro é o SecureString?.

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

-CustomMethod

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

Exemplo:

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

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

Esse recurso foi adicionado ao PowerShell 6.0.0.

Propriedades do parâmetro

Tipo:	String
Valor padrão:	None
Dá suporte a curingas:	False
DontShow:	False
Aliases:	CENTÍMETRO

Conjuntos de parâmetros

CustomMethod

Cargo:	Named
Obrigatório:	True
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	False

CustomMethodNoProxy

Cargo:	Named
Obrigatório:	True
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:	False
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

-FollowRelLink

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

Algumas APIs REST dão suporte à paginação via Links de Relação de acordo com a 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.

Propriedades do parâmetro

Tipo:	SwitchParameter
Valor padrão:	False
Dá suporte a curingas:	False
DontShow:	False
Aliases:	FL

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

-Form

Converte um dicionário em um envio multipart/form-data. Form pode não ser usado com Body. O ContentType é ignorado.

As chaves do dicionário são utilizadas como nomes dos campos do formulário. Por padrão, os valores de formulário sã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 é enviado como o filename. O tipo MIME é 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 matriz ou lista, o campo de formulário será enviado várias vezes. Os valores da lista sã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 = @{
    tags     = 'Vacation', 'Italy', '2017'
    pictures = Get-ChildItem 'C:\Users\jdoe\Pictures\2017-Italy\'
}

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

Esse recurso foi adicionado ao PowerShell 6.1.0.

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

-Headers

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

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

A partir do PowerShell 7.4, se você usar este parâmetro para definir o cabeçalho Content-Type e usar o parâmetro ContentType, o valor especificado no parâmetro ContentType será utilizado.

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

-HttpVersion

Especifica a versão HTTP usada para a solicitação. O padrão é 1.1.

Os valores válidos são:

• 1,0
• 1.1
• 2.0
• 3.0

Propriedades do parâmetro

Tipo:	Version
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 do corpo 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.

Você também precisa definir o tipo de conteúdo da solicitação. Por exemplo, para carregar um arquivo, você deve definir o tipo de conteúdo. Normalmente, o tipo deve ser application/octet-stream. No entanto, você precisa definir o tipo de conteúdo com base nos requisitos do ponto de extremidade.

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

-MaximumFollowRelLink

Especifica quantas vezes seguir os links de relação se FollowRelLink for usado. Um valor menor pode ser necessário se a API REST faz limitações devido ao excesso de solicitações. O valor padrão é [int32]::MaxValue. Um valor de 0 (zero) impede que os links de relação sejam seguidos.

Propriedades do parâmetro

Tipo:	Int32
Valor padrão:	Int32.MaxValue
Dá suporte a curingas:	False
DontShow:	False
Aliases:	ML

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

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 todo o redirecionamento.

Propriedades do parâmetro

Tipo:	Int32
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

-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. Veja também o parâmetro RetryIntervalSec para especificar o intervalo entre novas tentativas.

Propriedades do parâmetro

Tipo:	Int32
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

-Method

Especifica o método usado para a solicitação da Web. Os valores aceitáveis para este 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.

Propriedades do parâmetro

Tipo:	WebRequestMethod
Valor padrão:	None
Valores aceitos:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

StandardMethod

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	False

StandardMethodNoProxy

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	False

-NoProxy

Indica que o cmdlet não usará um proxy para chegar ao destino. Use isso para ignorar o proxy configurado em suas configurações da Internet ou especificado no ambiente.

Esse parâmetro foi introduzido no PowerShell 6.0.

Propriedades do parâmetro

Tipo:	SwitchParameter
Valor padrão:	False
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

StandardMethodNoProxy

Cargo:	Named
Obrigatório:	True
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	False

CustomMethodNoProxy

Cargo:	Named
Obrigatório:	True
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	False

-OperationTimeoutSeconds

Esse tempo limite se aplica a leituras de dados dentro de um fluxo, não ao tempo de fluxo como um todo. O valor padrão, 0, especifica um tempo limite indefinido.

Definir o valor como 30 segundos significa que qualquer atraso de mais de 30 segundos entre os dados no fluxo encerra a solicitação. Um arquivo grande que leva vários minutos para ser baixado não será encerrado, a menos que o fluxo fique parado por mais de 30 segundos.

Propriedades do parâmetro

Tipo:	Int32
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

-OutFile

Por padrão, Invoke-RestMethod retorna os resultados para o pipeline. Quando você usa o parâmetro OutFile, os resultados são salvos no arquivo especificado e não retornados ao pipeline. Insira um caminho e um nome de arquivo. Para enviar os resultados para um arquivo e para o pipeline, adicione o parâmetro PassThru.

Se você omitir o caminho, o padrão será o local atual. O nome é tratado como um caminho de literal. Os nomes que contêm colchetes ([]) devem ser colocados entre aspas simples (').

A partir do PowerShell 7.4, você pode especificar um caminho de pasta sem o nome do arquivo. Quando você faz isso, o comando usa o nome do arquivo do último segmento do URI resolvido após quaisquer redirecionamentos. Quando você especifica um caminho de pasta para OutFile, não é possível usar o parâmetro Resume.

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

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

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

-PreserveAuthorizationOnRedirect

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

Por padrão, o cmdlet remove o cabeçalho Authorization 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.

Propriedades do parâmetro

Tipo:	SwitchParameter
Valor padrão:	False
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

-PreserveHttpMethodOnRedirect

Indica que o cmdlet deve manter o método da solicitação durante os redirecionamentos.

Por padrão, o cmdlet altera o método para GET quando redirecionado. Especificar esse parâmetro desabilita essa lógica para garantir que o método pretendido possa ser usado com redirecionamento.

Esse recurso foi adicionado ao PowerShell 7.4.

Propriedades do parâmetro

Tipo:	SwitchParameter
Valor padrão:	False
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 (Uniform Resource Identifier) de um servidor proxy de rede.

Esse recurso foi adicionado ao PowerShell 6.0.0.

Propriedades do parâmetro

Tipo:	Uri
Valor padrão:	None
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

StandardMethod

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	False

CustomMethod

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. Você não pode usar os parâmetros ProxyCredential e ProxyUseDefaultCredentials no mesmo comando.

Propriedades do parâmetro

Tipo:	PSCredential
Valor padrão:	None
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

StandardMethod

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	False

CustomMethod

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. Você não pode usar os parâmetros ProxyCredential e ProxyUseDefaultCredentials no mesmo comando.

Propriedades do parâmetro

Tipo:	SwitchParameter
Valor padrão:	False
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

StandardMethod

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	False

CustomMethod

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	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.

Propriedades do parâmetro

Tipo:	String
Valor padrão:	None
Dá suporte a curingas:	False
DontShow:	False
Aliases:	RHV

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

-Resume

Executa uma tentativa máxima de retomar o download de um arquivo parcial. O parâmetro Resume requer o parâmetro OutFile.

Resume opera apenas com base no tamanho do arquivo local e do arquivo remoto e não executa nenhuma outra verificação para garantir 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á executada 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á baixado novamente. 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á baixado novamente. 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á baixado. Esse comportamento é o mesmo que usar OutFile sem Resume.

Esse recurso foi adicionado ao PowerShell 6.1.0.

Propriedades do parâmetro

Tipo:	SwitchParameter
Valor padrão:	False
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

-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. O valor deve estar entre 1 e [int]::MaxValue. Quando o código de falha é 429 e a resposta inclui a propriedade Retry-After em seus cabeçalhos, o cmdlet usa esse valor para o intervalo de repetição, mesmo se esse parâmetro for especificado.

Além disso, consulte o parâmetro MaximumRetryCount para especificar o número de repetições.

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

-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 na sessão do PowerShell. Você pode usar a variável em sua sessão assim que o comando for concluído.

Antes do PowerShell 7.4, 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.

A partir do PowerShell 7.4, a sessão de solicitação da Web é persistente, desde que as propriedades da sessão não sejam substituídas em uma solicitação subsequente. Quando essas condições forem atendidas, o cmdlet recriará a sessão com os novos valores. As sessões persistentes reduzem a sobrecarga para solicitações repetidas, tornando-as muito mais rápidas.

Para usar a sessão de solicitação web em solicitações web subsequentes, 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 Credencial. Os valores de parâmetro têm precedência sobre valores na sessão de solicitação da Web.

Você não pode 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

-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 para uso em hosts conhecidos que usam um certificado autoassinado para fins de teste. Use por sua conta e risco.

Esse recurso foi adicionado ao PowerShell 6.0.0.

Propriedades do parâmetro

Tipo:	SwitchParameter
Valor padrão:	False
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

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

Essa opção desabilita a validação dos valores passados para os parâmetros ContentType, Headerse UserAgent.

Esse recurso foi adicionado ao PowerShell 6.0.0.

Propriedades do parâmetro

Tipo:	SwitchParameter
Valor padrão:	False
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

-SkipHttpErrorCheck

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

Esse parâmetro foi introduzido no PowerShell 7.

Propriedades do parâmetro

Tipo:	SwitchParameter
Valor padrão:	False
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

-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. SslProtocol permite limitar a 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 combina os valores usando uma operação binária-OR. Passar valores como uma matriz é a opção mais simples e também permite usar o preenchimento com Tab nos valores. Talvez você não possa fornecer vários valores em todas as plataformas.

Esse recurso foi adicionado ao PowerShell 6.0.0. O suporte para Tls13 foi adicionado no PowerShell 7.1.

Propriedades do parâmetro

Tipo:	WebSslProtocol
Valor padrão:	None
Valores aceitos:	Default, Tls, Tls11, Tls12, Tls13
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

-StatusCodeVariable

Cria uma variável que contém um resultado de código de status HTTP 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.

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

-Token

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

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.

Propriedades do parâmetro

Tipo:	SecureString
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

-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

-UnixSocket

Especifica o nome do soquete Unix ao qual se conectar. Esse parâmetro tem suporte em sistemas baseados em Unix e no Windows versão 1803 e posterior. Para obter mais informações sobre o suporte do Windows a soquetes Unix, consulte a postagem no blog Interoperabilidade do Windows/WSL com AF_UNIX.

Esse parâmetro foi adicionado no PowerShell 7.4.

Propriedades do parâmetro

Tipo:	UnixDomainSocketEndPoint
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

-Uri

Especifica o URI (Uniform Resource Identifier) do recurso de 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

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 é incluído apenas para compatibilidade com versões anteriores. Quando usado, ele não tem efeito sobre a operação do cmdlet.

Propriedades do parâmetro

Tipo:	SwitchParameter
Valor padrão:	False
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

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 Authentication ou Credential e pode não ser aceito em todas as plataformas.

Propriedades do parâmetro

Tipo:	SwitchParameter
Valor padrão:	False
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 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.

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 de cmdlet, como UserAgent ou Credencial. Os valores de parâmetro têm precedência sobre valores na sessão de solicitação da Web. Cabeçalhos relacionados ao conteúdo, como Content-Type, são substituídos quando um objeto MultipartFormDataContent é fornecido para Body.

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 requisição 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.

Você não pode 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 este cmdlet.

Saídas

Int64

Quando a solicitação retorna um inteiro, esse cmdlet retorna esse inteiro.

String

Quando a solicitação retorna uma cadeia de caracteres, esse cmdlet retorna essa cadeia de caracteres.

XmlDocument

Quando a solicitação retorna XML válido, esse cmdlet o retorna como um XmlDocument.

PSObject

Quando a solicitação retorna cadeias de caracteres JSON, esse cmdlet retorna um PSObject que representa os dados.

Observações

O PowerShell inclui os seguintes aliases para Invoke-RestMethod:

• Todas as plataformas:
  • irm

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 é diferente dependendo da plataforma:

• Para Windows: lê a configuração de proxy de variáveis de ambiente ou, se não estiverem definidas, das configurações de proxy do usuário.
• Para macOS: lê a configuração de proxy a partir de variáveis de ambiente ou, se estas 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 estejam definidas, essa propriedade inicializa uma instância não configurada que ignora todos os endereços.

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

• HTTP_PROXY: o nome do host ou o endereço IP do servidor proxy usado em solicitações HTTP.
• HTTPS_PROXY: o nome do host ou o 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 sejam definidos.
• NO_PROXY: uma lista separada por vírgulas de nomes de host que devem ser excluídos do proxying.

O PowerShell 7.4 adicionou suporte para o algoritmo de compactação Brotli.

Links Relacionados

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