Invoke-RestMethod

Sintaxe

Default (Predefinição)

Invoke-RestMethod
    [-Method <WebRequestMethod>]
    [-UseBasicParsing]
    [-Uri] <Uri>
    [-WebSession <WebRequestSession>]
    [-SessionVariable <String>]
    [-Credential <PSCredential>]
    [-UseDefaultCredentials]
    [-CertificateThumbprint <String>]
    [-Certificate <X509Certificate>]
    [-UserAgent <String>]
    [-DisableKeepAlive]
    [-TimeoutSec <Int32>]
    [-Headers <IDictionary>]
    [-MaximumRedirection <Int32>]
    [-Proxy <Uri>]
    [-ProxyCredential <PSCredential>]
    [-ProxyUseDefaultCredentials]
    [-Body <Object>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [<CommonParameters>]

Description

Parâmetros

-Body

Especifica o corpo da solicitação. O corpo é o conteúdo da solicitação que segue os cabeçalhos. Você também pode encaminhar um valor do corpo para Invoke-RestMethod.

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

Quando a entrada é uma solicitação GET e o corpo é um IDiccionário (normalmente, uma tabela de hash), o corpo é adicionado ao URI como parâmetros de consulta. Para outros tipos de solicitação (como POST), o corpo é definido como o valor do corpo da solicitação no formato padrão name=value.

Aviso: A saída detalhada de um corpo POST terminará com with -1-byte payload, mesmo que o tamanho do corpo seja conhecido e enviado no cabeçalho HTTP Content-Length.

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

Por exemplo:

$R = Invoke-WebRequest https://website.com/login.aspx
$R.Forms[0].Name = "MyName"
$R.Forms[0].Password = "MyPassword"
Invoke-RestMethod https://website.com/service.aspx -Body $R.Forms[0]

Propriedades dos parâmetros

Conjuntos de parâmetros

-Certificate

Especifica o certificado de cliente que é usado para uma solicitação da Web segura. Insira uma variável que contenha um certificado ou um comando ou expressão que obtenha o certificado.

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

Propriedades dos parâmetros

Conjuntos de parâmetros

-CertificateThumbprint

Especifica o certificado de chave pública digital (X509) de uma conta de usuário que tem permissão para enviar a solicitação. Insira a impressão digital (thumbprint) do certificado.

Os certificados são usados na autenticação baseada em certificado de cliente. Eles podem ser mapeados apenas para contas de usuário locais; eles não funcionam com contas de domínio.

Para obter uma impressão digital de certificado, use o comando Get-Item ou Get-ChildItem na unidade Windows PowerShell (Cert:).

Propriedades dos parâmetros

Conjuntos de parâmetros

-ContentType

Especifica o tipo de conteúdo da solicitação da Web.

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

Propriedades dos parâmetros

Conjuntos de parâmetros

-Credential

Especifica uma conta de usuário que tem permissão para enviar a solicitação. O padrão é o usuário atual.

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

Propriedades dos parâmetros

Conjuntos de parâmetros

-DisableKeepAlive

Define o valor de KeepAlive no cabeçalho HTTP como False. Por padrão, KeepAlive é True. KeepAlive estabelece uma conexão persistente com o servidor para facilitar solicitações subsequentes.

Propriedades dos parâmetros

Conjuntos de parâmetros

-Headers

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

Para definir cabeçalhos UserAgent, use o parâmetro -UserAgent. Não é possível usar esse parâmetro para especificar UserAgent ou cabeçalhos de cookies.

Propriedades dos parâmetros

Conjuntos de parâmetros

-InFile

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

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

Propriedades dos parâmetros

Conjuntos de parâmetros

-MaximumRedirection

Determina quantas vezes o Windows PowerShell redireciona uma conexão para um URI (Uniform Resource Identifier) alternativo antes que a conexão falhe. O valor padrão é 5. Um valor de 0 (zero) impede todo o redirecionamento.

Propriedades dos parâmetros

Conjuntos de parâmetros

-Method

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

• Predefinido
• Suprimir
• Obter
• Cabeça
• Unir
• Opções
• Correção
• Publicar
• Put
• Rastreio

Propriedades dos parâmetros

Conjuntos de parâmetros

-OutFile

Salva o corpo da resposta no arquivo de saída especificado. Insira um caminho e um nome de arquivo. Se você omitir o caminho, o padrão será o local atual.

Por padrão, Invoke-RestMethod retorna os resultados para o pipeline. Para enviar os resultados para um arquivo e para o pipeline, use o parâmetro -Passthru.

Propriedades dos parâmetros

Conjuntos de parâmetros

-PassThru

Retorna os resultados, além de gravá-los em um arquivo. Esse parâmetro é válido somente quando o parâmetro -OutFile também é usado no comando.

Propriedades dos parâmetros

Conjuntos de parâmetros

-Proxy

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

Propriedades dos parâmetros

Conjuntos de parâmetros

-ProxyCredential

Especifica uma conta de usuário que tem permissão para usar o servidor proxy especificado pelo parâmetro -Proxy. O padrão é o usuário atual.

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

Esse parâmetro é válido somente quando o parâmetro -Proxy também é usado no comando. Não é possível usar os parâmetros -ProxyCredential e -ProxyUseDefaultCredentials no mesmo comando.

Propriedades dos parâmetros

Conjuntos de parâmetros

-ProxyUseDefaultCredentials

Usa as credenciais do usuário atual para acessar o servidor proxy especificado pelo parâmetro -Proxy.

Esse parâmetro é válido somente quando o parâmetro -Proxy também é usado no comando. Não é possível usar os parâmetros -ProxyCredential e -ProxyUseDefaultCredentials no mesmo comando.

Propriedades dos parâmetros

Conjuntos de parâmetros

-SessionVariable

Cria uma sessão de solicitação da Web e a salva no valor da variável especificada. Insira um nome de variável sem o símbolo cifrão ($).

Quando você especifica uma variável de sessão, Invoke-RestMethod cria um objeto de sessão de solicitação da Web e o atribui a uma variável com o nome especificado em sua sessão do Windows PowerShell. Você pode usar a variável em sua sessão assim que o comando for concluído.

Ao contrário de uma sessão remota, a sessão de solicitação da Web não é uma conexão persistente. É um objeto que contém informações sobre a conexão e a solicitação, incluindo cookies, credenciais, o valor máximo de redirecionamento e a cadeia de caracteres do agente do usuário. Você pode usá-lo para compartilhar estado e dados entre solicitações da Web.

Para usar a sessão de solicitação da Web em solicitações da Web subsequentes, especifique a variável de sessão no valor do parâmetro -WebSession. O Windows PowerShell usa os dados no objeto de sessão de solicitação da Web ao estabelecer a nova conexão. Para substituir um valor na sessão de solicitação da Web, use um parâmetro de cmdlet, como -UserAgent ou -Credential. Os valores dos parâmetros têm precedência sobre os valores na sessão de solicitação da Web.

Não é possível usar os parâmetros -SessionVariable e -WebSession no mesmo comando.

Propriedades dos parâmetros

Conjuntos de parâmetros

-TimeoutSec

Especifica por quanto tempo a solicitação pode ficar pendente antes de atingir o tempo limite. Insira um valor em segundos. O valor padrão, 0, especifica um tempo limite indefinido.

Uma consulta DNS (Sistema de Nomes de Domínio) pode levar até 15 segundos para retornar ou atingir o tempo limite. Se sua solicitação contiver um nome de host que exija resolução e você definir TimeoutSec para um valor maior que zero, mas inferior a 15 segundos, pode levar 15 segundos ou mais antes que uma WebException seja lançada e sua solicitação atinja o tempo limite.

Propriedades dos parâmetros

Conjuntos de parâmetros

-TransferEncoding

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

• Segmentado
• Comprimir
• Desinflar
• GZip
• Identidade

Propriedades dos parâmetros

Conjuntos de parâmetros

-Uri

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

Este parâmetro é obrigatório. O nome do parâmetro (-Uri) é opcional.

Propriedades dos parâmetros

Conjuntos de parâmetros

-UseBasicParsing

Indica que o cmdlet usa análise básica. O cmdlet retorna o HTML bruto num String objeto.

Propriedades dos parâmetros

Conjuntos de parâmetros

-UseDefaultCredentials

Usa as credenciais do usuário atual para enviar a solicitação da Web.

Propriedades dos parâmetros

Conjuntos de parâmetros

-UserAgent

Especifica uma string de agente do usuário para a solicitação da web.

O agente de usuário padrão é semelhante a "Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US) WindowsPowerShell/3.0" com pequenas variações para cada sistema operacional e plataforma.

Para testar um site com a cadeia de caracteres padrão do agente do usuário usada pela maioria dos navegadores da Internet, use as propriedades da classe PSUserAgent do , como Chrome, FireFox, Internet Explorer, Opera e Safari.

Por exemplo, o comando a seguir usa a cadeia de caracteres do agente do usuário para a Internet

Invoke-WebRequest -Uri https://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)

Propriedades dos parâmetros

Conjuntos de parâmetros

-WebSession

Especifica uma sessão de solicitação da Web. Insira o nome da variável, incluindo o cifrão ($).

Para substituir um valor na sessão de solicitação da Web, use um parâmetro de cmdlet, como -UserAgent ou -Credential. Os valores dos parâmetros têm precedência sobre os valores na sessão de solicitação da Web.

Ao contrário de uma sessão remota, a sessão de solicitação da Web não é uma conexão persistente. É um objeto que contém informações sobre a conexão e a solicitação, incluindo cookies, credenciais, o valor máximo de redirecionamento e a cadeia de caracteres do agente do usuário. Você pode usá-lo para compartilhar estado e dados entre solicitações da Web.

Para criar uma sessão de solicitação da Web, insira um nome de variável (sem cifrão) no valor do parâmetro -SessionVariable de um comando Invoke-RestMethod. Invoke-RestMethod cria a sessão e a salva na variável. Em comandos subsequentes, use a variável como o valor do parâmetro -WebSession.

Não é possível usar os parâmetros -SessionVariable e -WebSession no mesmo comando.

Propriedades dos parâmetros

Conjuntos de parâmetros

CommonParameters

Entradas

Object

Saídas

System.Xml.XmlDocument, Microsoft.PowerShell.Commands.HtmlWebResponseObject, System.String

PSObject

Ligações Relacionadas

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