Invoke-RestMethod

  • Referência
Módulo:
Microsoft.PowerShell.Utility

Envia um pedido HTTP ou HTTPS para um serviço Web RESTful.

Syntax

Invoke-RestMethod
      [-Method <WebRequestMethod>]
      [-FollowRelLink]
      [-MaximumFollowRelLink <Int32>]
      [-ResponseHeadersVariable <String>]
      [-StatusCodeVariable <String>]
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-HttpVersion <Version>]
      [-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>
      [-HttpVersion <Version>]
      [-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>
      [-HttpVersion <Version>]
      [-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
      -CustomMethod <String>
      [-FollowRelLink]
      [-MaximumFollowRelLink <Int32>]
      [-ResponseHeadersVariable <String>]
      [-StatusCodeVariable <String>]
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-HttpVersion <Version>]
      [-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>]

Description

O Invoke-RestMethod cmdlet envia pedidos HTTP e HTTPS para serviços Web de Transferência de Estado Representacional (REST) que devolvem dados estruturados de forma avançada.

O PowerShell formatará a resposta com base no tipo de dados. Para um feed RSS ou ATOM, o PowerShell devolve os nós XML de Item ou Entrada. Para JavaScript Object Notation (JSON) ou XML, o PowerShell converte ou anula a serialização do conteúdo em [PSCustomObject] objetos.

Nota

Quando o ponto final REST devolve vários objetos, os objetos são recebidos como uma matriz. Se encaminhar a saída de Invoke-RestMethod para outro comando, esta será enviada como um único [Object[]] objeto. Os conteúdos dessa matriz não são enumerados para o comando seguinte no pipeline.

Este cmdlet é introduzido no Windows PowerShell 3.0.

A partir do PowerShell 7.0, Invoke-RestMethod suporta a configuração de proxy definida por variáveis de ambiente. Veja a secção Notas deste artigo.

Exemplos

Exemplo 1: Obter o feed RSS do PowerShell

Este exemplo utiliza o Invoke-RestMethod cmdlet para obter informações do feed RSS do Blogue do PowerShell. O comando utiliza o Format-Table cmdlet para apresentar os valores das propriedades Título e pubDate de cada blogue numa 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 um pedido POST

Neste exemplo, um utilizador é executado Invoke-RestMethod para fazer um pedido POST num site da intranet na organização do utilizador.

$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 pedidas e, em seguida, armazenadas no $Cred e o URL que será acedido é definido 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 os dados devolvidos 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á a comunicar.

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

Exemplo 3: seguir ligações de relação

Algumas APIs REST suportam a paginação através de Ligações relacionais por RFC5988. Em vez de analisar o cabeçalho para obter o URL para a página seguinte, pode pedir ao cmdlet para o fazer por si. Este exemplo devolve as duas primeiras páginas de problemas do repositório do GitHub do PowerShell.

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

Exemplo 4: Submissão simplificada de Multipart/Form-Data

Algumas APIs requerem multipart/form-data submissões para carregar ficheiros e conteúdos mistos. Este exemplo demonstra como atualizar o perfil de um utilizador.

$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, , avataremail, birthdaye hobbies. A API espera que seja fornecida uma imagem para a imagem do perfil de utilizador no avatar campo. A API também aceitará várias hobbies entradas para serem submetidas no mesmo formulário.

Ao criar a $Form Tabela Hash, os nomes das chaves são utilizados como nomes de campos de formulário. Por predefinição, os valores da Tabela Hash serão convertidos em cadeias. Se estiver presente um System.IO.FileInfo valor, o conteúdo do ficheiro será submetido. Se estiver presente uma coleção, como matrizes ou listas, o campo de formulário será submetido várias vezes.

Ao utilizar Get-Item a avatar chave, o FileInfo objeto será definido como o valor. O resultado é que os dados da imagem para jdoe.png serão submetidos.

Ao fornecer uma lista à hobbies chave, o hobbies campo estará presente nas submissões uma vez para cada item de lista.

Exemplo 5: Passar vários cabeçalhos

Muitas vezes, as APIs requerem cabeçalhos transmitidos para autenticação ou validação. Este exemplo demonstra como transmitir vários cabeçalhos de uma 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 devolvidos no pipeline

O GitHub devolve vários objetos a uma matriz. Se encaminhar a saída para outro comando, este será enviado como um único [Object[]]objeto.

Para enumerar os objetos no pipeline, encaminhe os resultados para Write-Output ou embrulhe o cmdlet em parênteses. O exemplo seguinte conta o número de objetos devolvidos 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

Exemplo 7: Ignorar Validação de Cabeçalho

Por predefinição, o Invoke-RestMethod cmdlet valida os valores de cabeçalhos conhecidos que têm um formato de valor definido por standardards. O exemplo seguinte mostra como esta validação pode gerar um erro e como pode utilizar o parâmetro SkipHeaderValidation para evitar validar valores para pontos finais 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 devolve informações sobre pedidos Web e respostas para resolução de problemas. A $Uri variável é atribuída ao /headers ponto final do serviço, que devolve os cabeçalhos de um pedido como o conteúdo na respetiva resposta.

O If-Match cabeçalho do pedido é definido na secção RFC-7232 3.1 e requer que o valor desse cabeçalho seja definido com aspas adjacentes. A $InvalidHeaders variável é atribuída a uma tabela hash onde o valor de If-Match é inválido porque está definido como 12345 em vez de "12345".

Chamar Invoke-RestMethod com os cabeçalhos inválidos devolve um erro ao informar que o valor formatado é inválido. O pedido não é enviado para o ponto final.

Chamar Invoke-RestMethod com o parâmetro SkipHeaderValidation ignora a falha de validação e envia o pedido para o ponto final. Uma vez que o ponto final tolera valores de cabeçalho não conformes, o cmdlet devolve o objeto de resposta sem erros.

Exemplo 8: Enviar um pedido com HTTP 2.0

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

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

Parâmetros

-AllowUnencryptedAuthentication

Permite o envio de credenciais e segredos através de ligações não encriptadas. Por predefinição, fornecer credenciais ou qualquer opção de Autenticação com um Uri que não comece por https:// resultará num erro e o pedido irá abortar para impedir a comunicação não intencional de segredos em texto simples através de ligações não encriptadas. Para substituir este comportamento por sua conta e risco, forneça o parâmetro AllowUnencryptedAuthentication .

Aviso

A utilização deste parâmetro não é segura e não é recomendada. É fornecido apenas para compatibilidade com sistemas legados que não podem fornecer ligações encriptadas. Utilize por sua conta e risco.

Esta funcionalidade foi adicionada no PowerShell 6.0.0.

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

-Authentication

Especifica o tipo de autenticação explícita a utilizar para o pedido. A predefinição é Nenhuma. O parâmetro Autenticação não pode ser utilizado com o parâmetro UseDefaultCredentials .

Opções de Autenticação Disponíveis:

  • None: esta é a opção predefinida quando a Autenticação não é fornecida. Não será utilizada autenticação explícita.
  • Basic: requer credenciais. As credenciais serão utilizadas para enviar um cabeçalho rfc 7617 Basic Authentication Authorization: Basic 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 Authorization cabeçalhos fornecidos a Cabeçalhos ou incluídos na WebSession.

Esta funcionalidade foi adicionada no PowerShell 6.0.0.

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

-Body

Especifica o corpo do pedido. O corpo é o conteúdo do pedido que segue os cabeçalhos. Também pode encaminhar um valor do corpo para Invoke-RestMethod.

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

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

Quando a entrada é um pedido GET e o corpo é um IDictionary (normalmente, uma tabela hash), o corpo é adicionado ao URI como parâmetros de consulta. Para outros tipos de pedido (como PATCH), o corpo é definido como o valor do corpo do pedido no formato padrão name=value com os valores codificados por URL.

Quando a entrada é uma System.Xml. O objeto XmlNode e a declaração XML especificam uma codificação, que a codificação é utilizada para os dados no pedido, a menos que seja substituída pelo parâmetro ContentType .

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

O parâmetro Body também pode aceitar um objeto System.Net.Http.MultipartFormDataContent . Isto irá facilitar os multipart/form-data pedidos. Quando um objeto MultipartFormDataContent é fornecido para o Corpo, todos os cabeçalhos relacionados com conteúdo fornecidos aos parâmetrosContentType, Headers ou WebSession serão substituídos pelos cabeçalhos de conteúdo do MultipartFormDataContent objeto. Esta funcionalidade foi adicionada no PowerShell 6.0.0.

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

-Certificate

Especifica o certificado de cliente utilizado para um pedido Web seguro. Introduza uma variável que contenha um certificado ou um comando ou expressão que obtenha o certificado.

Para localizar um certificado, utilize Get-PfxCertificate ou utilize 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
Accept pipeline input:False
Accept wildcard characters:False

-CertificateThumbprint

Especifica o certificado de chave pública digital (X509) de uma conta de utilizador que tem permissão para enviar o pedido. Introduza o thumbprint do certificado.

Os certificados são utilizados na autenticação baseada em certificados de cliente. Só podem ser mapeadas para contas de utilizador locais; não funcionam com contas de domínio.

Para obter um thumbprint de certificado, utilize o Get-Item comando ou Get-ChildItem na unidade do PowerShell Cert: .

Nota

Atualmente, esta funcionalidade só é suportada em plataformas de SO Windows.

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

-ContentType

Especifica o tipo de conteúdo do pedido Web.

Se o valor de ContentType contiver o formato de codificação (como charset), o cmdlet utiliza esse formato para codificar o corpo do pedido Web. Se o ContentType não especificar um formato de codificação, é utilizado o formato de codificação predefinido. Um exemplo de um ContentType com um formato de codificação é text/plain; charset=iso-8859-5, que especifica o alfabeto latino/cirílico .

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

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

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

-Credential

Especifica uma conta de utilizador que tem permissão para enviar o pedido. A predefinição é o utilizador atual.

Escreva um nome de utilizador, como User01 ou Domain01\User01, ou introduza um objeto PSCredential gerado pelo Get-Credential cmdlet .

As credenciais podem ser utilizadas individualmente ou em conjunto com determinadas opções de parâmetros de Autenticação . Quando utilizado apenas, só fornecerá credenciais para o servidor remoto se o servidor remoto enviar um pedido de desafio de autenticação. Quando utilizadas com as opções de Autenticação , as credenciais serão enviadas explicitamente.

As credenciais são armazenadas num objeto PSCredential e a palavra-passe é armazenada como secureString.

Nota

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
Accept pipeline input:False
Accept wildcard characters:False

-CustomMethod

Especifica o método personalizado utilizado para o pedido Web. Isto pode ser utilizado com o Método de Pedido exigido pelo ponto final não é uma opção disponível no Método. O método e o CustomMethod não podem ser utilizados em conjunto.

Exemplo:

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

Isto faz um TEST pedido HTTP à API.

Esta funcionalidade foi adicionada no PowerShell 6.0.0.

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

-DisableKeepAlive

Indica que o cmdlet define o valor KeepAlive no cabeçalho HTTP como Falso. Por predefinição, KeepAlive é Verdadeiro. KeepAlive estabelece uma ligação persistente ao servidor para facilitar os pedidos subsequentes.

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

-FollowRelLink

Indica que o cmdlet deve seguir as ligações de relação.

Algumas APIs REST suportam a paginação através de Ligações de Relação por RFC5988. Em vez de analisar o cabeçalho para obter o URL para a página seguinte, pode fazer com que o cmdlet o faça por si. Para definir quantas vezes deve seguir as ligações de relação, utilize o parâmetro MaximumFollowRelLink .

Ao utilizar este parâmetro, o cmdlet devolve uma coleção de páginas de resultados. Cada página de resultados pode conter vários itens de resultado.

Esta funcionalidade foi adicionada no PowerShell 6.0.0.

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

-Form

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

As chaves do dicionário serão utilizadas como os nomes dos campos de formulário. Por predefinição, os valores de formulário serão convertidos em valores de cadeia.

Se o valor for um objeto System.IO.FileInfo , os conteúdos do ficheiro binário serão submetidos. O nome do ficheiro será submetido como .filename O MIME será definido como application/octet-stream. Get-Item pode ser utilizado 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 para será submetido várias vezes. Os valores da lista serão tratados como cadeias por predefinição. Se o valor for um objeto System.IO.FileInfo , os conteúdos do ficheiro binário serão submetidos. As coleções aninhadas não são suportadas.

$Form = @{ tags = '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 de Vacation, Italye 2017. O pictures campo também será submetido uma vez para cada ficheiro na 2017-Italy pasta. Os conteúdos binários dos ficheiros nessa pasta serão submetidos como valores.

Esta funcionalidade foi adicionada no PowerShell 6.1.0.

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

-Headers

Especifica os cabeçalhos do pedido Web. Introduza uma tabela hash ou um dicionário.

Os cabeçalhos relacionados com conteúdo, como Content-Type , por exemplo, são substituídos quando um MultipartFormDataContent objeto é fornecido para o Corpo.

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

-HttpVersion

Especifica a versão HTTP utilizada para o pedido. A predefinição é 1.1.

Os valores válidos são:

  • 1.0
  • 1.1
  • 2.0
  • 3.0
Type:Version
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-InFile

Obtém o conteúdo do pedido Web a partir de um ficheiro.

Introduza um caminho e um nome de ficheiro. Se omitir o caminho, a predefinição é a localização atual.

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

-MaximumFollowRelLink

Especifica o número de vezes que deve seguir as ligações de relação se a opção FollowRelLink for utilizada. Poderá ser necessário um valor mais pequeno se a API REST limitar devido a demasiados pedidos. O valor predefinido é [Int32]::MaxValue. Um valor de 0 (zero) impede as seguintes ligações relacionais.

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

-MaximumRedirection

Especifica quantas vezes o PowerShell redireciona uma ligação para um URI (Uniform Resource Identifier) alternativo antes de a ligação falhar. O valor predefinido é 5. Um valor de 0 (zero) impede todo o redirecionamento.

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

-MaximumRetryCount

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

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

-Method

Especifica o método utilizado para o pedido 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 utilizado para Métodos de Pedido não listados acima.

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

-NoProxy

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

Quando precisar de ignorar o proxy configurado no Internet Explorer ou um proxy especificado no ambiente, utilize este comutador.

Este parâmetro foi introduzido no PowerShell 6.0.

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

-OutFile

Guarda o corpo da resposta no ficheiro de saída especificado. Introduza um caminho e um nome de ficheiro. Se omitir o caminho, a predefinição é a localização atual. O nome é tratado como um caminho literal. Os nomes que contêm parênteses retos ([]) têm de estar entre plicas (').

Por predefinição, Invoke-RestMethod devolve os resultados ao pipeline.

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

-PassThru

Este parâmetro só é válido quando o parâmetro OutFile também é utilizado no comando . A intenção é que os resultados sejam escritos no ficheiro e no pipeline.

Nota

Quando utiliza o parâmetro PassThru , o resultado é escrito no pipeline, mas o ficheiro não é criado. Para obter mais informações, veja Problema do PowerShell #15409.

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

-PreserveAuthorizationOnRedirect

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

Por predefinição, o cmdlet retira o Authorization cabeçalho antes de redirecionar. Especificar este parâmetro desativa esta lógica para os casos em que o cabeçalho tem de ser enviado para a localização de redirecionamento.

Esta funcionalidade foi adicionada no PowerShell 6.0.0.

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

-Proxy

Utiliza um servidor proxy para o pedido, em vez de ligar diretamente ao recurso da Internet. Introduza o Uniform Resource Identifier (URI) de um servidor proxy de rede.

Esta funcionalidade foi adicionada no PowerShell 6.0.0.

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

-ProxyCredential

Especifica uma conta de utilizador que tem permissão para utilizar o servidor proxy especificado pelo parâmetro Proxy . A predefinição é o utilizador atual.

Escreva um nome de utilizador, como User01 ou Domain01\User01, User@Domain.Comou introduza um PSCredential objeto, como um gerado pelo Get-Credential cmdlet.

Este parâmetro só é válido quando o parâmetro Proxy também é utilizado no comando . Não pode utilizar os parâmetros ProxyCredential e ProxyUseDefaultCredentials no mesmo comando.

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

-ProxyUseDefaultCredentials

Indica que o cmdlet utiliza as credenciais do utilizador atual para aceder ao servidor proxy especificado pelo parâmetro Proxy .

Este parâmetro só é válido quando o parâmetro Proxy também é utilizado no comando . Não pode utilizar os parâmetros ProxyCredential e ProxyUseDefaultCredentials no mesmo comando.

Type:SwitchParameter
Position:Named
Default value: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. Introduza 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 devolvidos pelo servidor Web.

Esta funcionalidade foi adicionada no PowerShell 6.0.0.

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

-Resume

Efetua uma melhor tentativa de retomar a transferência de um ficheiro parcial. O parâmetro Resume requer o parâmetro OutFile .

O currículo só funciona com o tamanho do ficheiro local e do ficheiro remoto e não efetua qualquer outra validação de que o ficheiro local e o ficheiro remoto são os mesmos.

Se o tamanho do ficheiro local for inferior ao tamanho do ficheiro remoto, o cmdlet tentará retomar a transferência do ficheiro e acrescentar os restantes bytes ao final do ficheiro.

Se o tamanho do ficheiro local for o mesmo que o tamanho do ficheiro remoto, não é tomada nenhuma ação e o cmdlet assume que a transferência já foi concluída.

Se o tamanho do ficheiro local for superior ao tamanho do ficheiro remoto, o ficheiro local será substituído e todo o ficheiro remoto será completamente transferido. Este comportamento é o mesmo que utilizar OutFile sem Currículo.

Se o servidor remoto não suportar a retoma da transferência, o ficheiro local será substituído e todo o ficheiro remoto será completamente transferido. Este comportamento é o mesmo que utilizar OutFile sem Currículo.

Se o ficheiro local não existir, o ficheiro local será criado e todo o ficheiro remoto será completamente transferido. Este comportamento é o mesmo que utilizar OutFile sem Currículo.

Esta funcionalidade foi adicionada no PowerShell 6.1.0.

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

-RetryIntervalSec

Especifica o intervalo entre repetições para a ligação quando é recebido um código de falha entre 400 e 599, inclusive ou 304. Veja também o parâmetro MaximumRetryCount para especificar o número de repetições. O valor tem de ser entre 1 e [int]::MaxValue.

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

-SessionVariable

Cria uma variável que contém a sessão de pedido Web. Introduza um nome de variável sem o símbolo de cifrão ($).

Quando especifica uma variável de sessão, Invoke-RestMethod cria um objeto de sessão de pedido Web e atribui-o a uma variável com o nome especificado na sua sessão do PowerShell. Pode utilizar a variável na sua sessão assim que o comando for concluído.

Antes do PowerShell 7.4, a sessão de pedido Web não é uma ligação persistente. É um objeto que contém informações sobre a ligação e o pedido, incluindo cookies, credenciais, o valor máximo de redirecionamento e a cadeia de agente do utilizador. Pode utilizá-lo para partilhar estados e dados entre pedidos Web.

A partir do PowerShell 7.4, a sessão de pedido Web é persistente, desde que as propriedades da sessão não sejam substituídas num pedido subsequente. Quando estiverem, o cmdlet recria a sessão com os novos valores. As sessões persistentes reduzem a sobrecarga dos pedidos repetidos, tornando-os muito mais rápidos.

Para utilizar a sessão de pedido Web em pedidos Web subsequentes, especifique a variável de sessão no valor do parâmetro WebSession . O PowerShell utiliza os dados no objeto de sessão de pedido Web ao estabelecer a nova ligação. Para substituir um valor na sessão de pedido Web, utilize um parâmetro de cmdlet, como UserAgent ou Credential. Os valores dos parâmetros têm precedência sobre os valores na sessão de pedido Web.

Não pode utilizar os parâmetros SessionVariable e WebSession no mesmo comando.

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

-SkipCertificateCheck

Ignora as verificações de validação de certificados que incluem todas as validações, como expiração, revogação, autoridade de raiz fidedigna, etc.

Aviso

A utilização deste parâmetro não é segura e não é recomendada. Este comutador destina-se apenas a ser utilizado em anfitriões conhecidos com um certificado autoassinado para fins de teste. Utilize por sua conta e risco.

Esta funcionalidade foi adicionada no PowerShell 6.0.0.

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

-SkipHeaderValidation

Indica que o cmdlet deve adicionar cabeçalhos ao pedido sem validação.

Este comutador deve ser utilizado para sites que requerem valores de cabeçalho que não estejam em conformidade com as normas. Especificar este comutador desativa a validação para permitir que o valor seja transmitido desmarcado. Quando especificado, todos os cabeçalhos são adicionados sem validação.

Esta ação irá desativar a validação dos valores transmitidos para os parâmetros ContentType, Headers e UserAgent .

Esta funcionalidade foi adicionada no PowerShell 6.0.0.

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

-SkipHttpErrorCheck

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

Este parâmetro foi introduzido no PowerShell 7.

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

-SslProtocol

Define os protocolos SSL/TLS que são permitidos para o pedido Web. Por predefinição, são permitidos protocolos SSL/TLS suportados pelo sistema. O SslProtocol permite limitar protocolos específicos para fins de conformidade.

Estes valores são definidos como uma enumeração baseada em sinalizador. Pode combinar múltiplos valores para definir vários sinalizadores com este parâmetro. Os valores podem ser transmitidos para o parâmetro SslProtocol como uma matriz de valores ou como uma cadeia separada por vírgulas desses valores. O cmdlet irá combinar os valores com uma operação binary-OR. Transmitir valores como uma matriz é a opção mais simples e também lhe permite utilizar a conclusão de separadores nos valores. Poderá não conseguir fornecer vários valores em todas as plataformas.

Nota

Em plataformas não Windows, poderá não ser possível fornecer Tls ou Tls12 como opção. O suporte para Tls13 não está disponível em todos os sistemas operativos e terá de ser verificado por sistema operativo.

Esta funcionalidade foi adicionada no 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
Accept pipeline input:False
Accept wildcard characters:False

-StatusCodeVariable

Cria uma variável que contém um resultado de código de estado HTTP do pedido. Introduza 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 utilizado com o parâmetro SkipHttpErrorCheck .

Introduza o nome da variável do parâmetro como uma cadeia, como -StatusCodeVariable "scv".

Este parâmetro foi introduzido no PowerShell 7.

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

-TimeoutSec

Especifica quanto tempo o pedido pode estar pendente antes de exceder o limite de tempo. Introduza um valor em segundos. O valor predefinido, 0, especifica um tempo limite indefinido.

Uma consulta DNS (Domain Name System) pode demorar até 15 segundos a devolver ou exceder o tempo limite. Se o seu pedido contiver um nome de anfitrião que necessite de resolução e definir TimeoutSec para um valor superior a zero, mas inferior a 15 segundos, pode demorar 15 segundos ou mais até que seja emitida uma WebException e o seu pedido excede o limite de tempo.

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

-Token

O token OAuth ou Bearer a incluir no pedido. O token é obrigatório por determinadas opções de Autenticação . Não pode ser utilizado de forma independente.

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

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

Este parâmetro foi introduzido no PowerShell 6.0.

Type:SecureString
Position:Named
Default value:None
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 este parâmetro são:

  • Segmentado
  • Comprimir
  • Esvaziar
  • GZip
  • Identidade
Type:String
Accepted values:chunked, compress, deflate, gzip, identity
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Uri

Especifica o Uniform Resource Identifier (URI) do recurso da Internet para o qual o pedido Web é enviado. Este parâmetro suporta valores HTTP, HTTPS, FTP e FILE.

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

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

-UseBasicParsing

Este parâmetro foi preterido. A partir do PowerShell 6.0.0, todos os pedidos Web utilizam apenas análise básica. Este parâmetro está incluído apenas para retrocompatibilidade e qualquer utilização do mesmo não terá qualquer efeito na operação do cmdlet.

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

-UseDefaultCredentials

Indica que o cmdlet utiliza as credenciais do utilizador atual para enviar o pedido Web. Isto não pode ser utilizado com Autenticação ou Credencial e pode não ser suportado em todas as plataformas.

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

-UserAgent

Especifica uma cadeia de agente de utilizador para o pedido Web.

O agente de utilizador predefinido é semelhante a Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0 com ligeiras variações para cada sistema operativo e plataforma.

Para testar um site com a cadeia de agente de utilizador padrão que é utilizada pela maioria dos browsers de Internet, utilize as propriedades da classe PSUserAgent , como Chrome, FireFox, InternetExplorer, Opera e Safari.

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

-WebSession

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

Para substituir um valor na sessão de pedido Web, utilize um parâmetro de cmdlet, como UserAgent ou Credential. Os valores dos parâmetros têm precedência sobre os valores na sessão do pedido Web. Os cabeçalhos relacionados com conteúdo, como Content-Type, também serão substituídos quando for fornecido um objeto MultipartFormDataContent para Body.

Ao contrário de uma sessão remota, a sessão de pedido Web não é uma ligação persistente. É um objeto que contém informações sobre a ligação e o pedido, incluindo cookies, credenciais, o valor máximo de redirecionamento e a cadeia de agente do utilizador. Pode utilizá-lo para partilhar o estado e os dados entre pedidos Web.

Para criar uma sessão de pedido Web, introduza 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 guarda-a na variável. Nos comandos subsequentes, utilize a variável como o valor do parâmetro WebSession .

Não pode utilizar os parâmetros SessionVariable e WebSession no mesmo comando.

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

Entradas

Object

Pode encaminhar o corpo de um pedido Web para este cmdlet.

Saídas

Int64

Quando o pedido devolve um número inteiro, este cmdlet devolve esse número inteiro.

String

Quando o pedido devolve uma cadeia, este cmdlet devolve essa cadeia.

XmlDocument

Quando o pedido devolve XML válido, este cmdlet devolve-o como um XmlDocument.

PSObject

Quando o pedido devolve cadeias JSON, este cmdlet devolve um PSObject que representa os dados.

Notas

O PowerShell inclui os seguintes aliases para Invoke-RestMethod:

  • Todas as plataformas:
    • irm

Algumas funcionalidades podem não estar disponíveis em todas as plataformas.

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

O valor desta propriedade é regras diferentes consoante a sua plataforma:

  • Para Windows: lê a configuração do proxy a partir de variáveis de ambiente ou, se estas não estiverem definidas, a partir das definições de proxy do utilizador.
  • Para macOS: lê a configuração do proxy a partir de variáveis de ambiente ou, se estas não estiverem definidas, a partir das definições de proxy do sistema.
  • Para Linux: lê a configuração do proxy a partir de variáveis de ambiente ou, caso não estejam definidas, esta propriedade inicializa uma instância não configurada que ignora todos os endereços.

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

  • HTTP_PROXY: o nome do anfitrião ou endereço IP do servidor proxy utilizado em pedidos HTTP.
  • HTTPS_PROXY: o nome do anfitrião ou endereço IP do servidor proxy utilizado em pedidos HTTPS.
  • ALL_PROXY: o nome do anfitrião ou endereço IP do servidor proxy utilizado nos pedidos HTTP e HTTPS no caso HTTP_PROXY de ou HTTPS_PROXY não estarem definidos.
  • NO_PROXY: uma lista separada por vírgulas de nomes de anfitrião que devem ser excluídos do proxying.