Partilhar via

Invoke-WebRequest

Módulo:
Microsoft.PowerShell.Utility Module

Obtém conteúdo de uma página da Web na internet.

Sintaxe

StandardMethod (Predefinição) 

Invoke-WebRequest
    [-Uri] <Uri>
    [-UseBasicParsing]
    [-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>]
    [-Method <WebRequestMethod>]
    [-Proxy <Uri>]
    [-ProxyCredential <PSCredential>]
    [-ProxyUseDefaultCredentials]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [-PreserveAuthorizationOnRedirect]
    [-SkipHeaderValidation]
    [<CommonParameters>]

StandardMethodNoProxy 

Invoke-WebRequest
    [-Uri] <Uri>
    -NoProxy
    [-UseBasicParsing]
    [-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>]
    [-Method <WebRequestMethod>]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [-PreserveAuthorizationOnRedirect]
    [-SkipHeaderValidation]
    [<CommonParameters>]

CustomMethod 

Invoke-WebRequest
    [-Uri] <Uri>
    -CustomMethod <String>
    [-UseBasicParsing]
    [-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>]

CustomMethodNoProxy 

Invoke-WebRequest
    [-Uri] <Uri>
    -CustomMethod <String>
    -NoProxy
    [-UseBasicParsing]
    [-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>]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [-PreserveAuthorizationOnRedirect]
    [-SkipHeaderValidation]
    [<CommonParameters>]

Description

O cmdlet Invoke-WebRequest envia solicitações HTTP e HTTPS para uma página ou serviço Web. Ele analisa a resposta e retorna coleções de links, imagens e outros elementos HTML significativos.

Este cmdlet foi introduzido no PowerShell 3.0.

A partir do PowerShell 7.0, Invoke-WebRequest oferece suporte à configuração de proxy definida por variáveis de ambiente. Consulte a seção Notas de deste artigo.

Importante

Os exemplos neste artigo fazem referência a hosts no domínio contoso.com. Este é um domínio fictício usado pela Microsoft para exemplos. Os exemplos são projetados para mostrar como usar os cmdlets. No entanto, como os contoso.com sites não existem, os exemplos não funcionam. Adapte os exemplos aos anfitriões no seu ambiente.

Exemplos

Exemplo 1: Enviar um pedido Web

Este exemplo usa o cmdlet Invoke-WebRequest para enviar uma solicitação da Web para o site Bing.com.

$Response = Invoke-WebRequest -URI https://www.bing.com/search?q=how+many+feet+in+a+mile
$Response.InputFields | Where-Object {
    $_.name -like "* Value*"
} | Select-Object Name, Value

name       value
----       -----
From Value 1
To Value   5280

O primeiro comando emite a solicitação e salva a resposta na variável $Response.

O segundo comando obtém qualquer InputField onde a propriedade Name é como "* Value". Os resultados filtrados são canalizados para Select-Object selecionar o Nome e valor propriedades.

Exemplo 2: Usar um serviço Web com monitoração de estado

Este exemplo mostra como usar o cmdlet Invoke-WebRequest com um serviço Web com monitoração de estado.

$Body = @{
    User = 'jdoe'
    password = 'P@S$w0rd!'
}
$LoginResponse = Invoke-WebRequest 'https://www.contoso.com/login/' -SessionVariable 'Session' -Body $Body -Method 'POST'

$Session

$ProfileResponse = Invoke-WebRequest 'https://www.contoso.com/profile/' -WebSession $Session

$ProfileResponse

A primeira chamada para Invoke-WebRequest envia uma solicitação de entrada. O comando especifica um valor de "Session" para o valor do parâmetro -SessionVariable e salva o $LoginResponse resultado na variável. Quando o comando é concluído, a $LoginResponse variável contém um BasicHtmlWebResponseObject e a $Session variável contém um WebRequestSession objeto. Isso registra o usuário no site.

A chamada para $Session por si só mostra o WebRequestSession objeto na variável.

A segunda chamada para Invoke-WebRequest buscar o perfil do usuário, que requer que o usuário esteja logado no site. Os dados de $Session sessão armazenados na variável são usados para fornecer cookies de sessão ao site criado durante o login. O resultado é salvo na $ProfileResponse variável.

A chamada para $ProfileResponse por si só mostra o BasicHtmlWebResponseObject na variável.

Este exemplo obtém os links em uma página da Web. Ele usa o cmdlet Invoke-WebRequest para obter o conteúdo da página da Web. Em seguida, ele usa a propriedade Links do BasicHtmlWebResponseObject que Invoke-WebRequest retorna e a propriedade Href de cada link.

(Invoke-WebRequest -Uri "https://aka.ms/pscore6-docs").Links.Href

Exemplo 4: Grava o conteúdo da resposta em um arquivo usando a codificação definida na página solicitada.

Este exemplo usa o cmdlet Invoke-WebRequest para recuperar o conteúdo da página da Web de uma página de documentação do PowerShell.

$Response = Invoke-WebRequest -Uri "https://aka.ms/pscore6-docs"
$Stream = [System.IO.StreamWriter]::new('.\docspage.html', $false, $Response.Encoding)
try {
    $Stream.Write($Response.Content)
}
finally {
    $Stream.Dispose()
}

O primeiro comando recupera a página e salva o objeto de resposta na variável $Response.

O segundo comando cria um StreamWriter para usar para gravar o conteúdo da resposta em um arquivo. A propriedade Encoding do objeto de resposta é usada para definir a codificação para o arquivo.

Os comandos finais gravam a propriedade Content no arquivo e, em seguida, descartam o StreamWriterarquivo .

Observe que a propriedade Encoding é nula se a solicitação da Web não retornar conteúdo de texto.

Exemplo 5: Enviar um arquivo multipart/form-data

Este exemplo usa o cmdlet Invoke-WebRequest carregar um arquivo como um envio de multipart/form-data. O c:\document.txt de arquivo é enviado como o campo de formulário document com o Content-Type de text/plain.

$FilePath = 'c:\document.txt'
$FieldName = 'document'
$ContentType = 'text/plain'

$FileStream = [System.IO.FileStream]::new($filePath, [System.IO.FileMode]::Open)
$FileHeader = [System.Net.Http.Headers.ContentDispositionHeaderValue]::new('form-data')
$FileHeader.Name = $FieldName
$FileHeader.FileName = Split-Path -leaf $FilePath
$FileContent = [System.Net.Http.StreamContent]::new($FileStream)
$FileContent.Headers.ContentDisposition = $FileHeader
$FileContent.Headers.ContentType = [System.Net.Http.Headers.MediaTypeHeaderValue]::Parse($ContentType)

$MultipartContent = [System.Net.Http.MultipartFormDataContent]::new()
$MultipartContent.Add($FileContent)

$Response = Invoke-WebRequest -Body $MultipartContent -Method 'POST' -Uri 'https://api.contoso.com/upload'

Exemplo 6: Submissão simplificada de várias partes/Form-Data

Algumas APIs exigem envios de multipart/form-data para carregar arquivos e conteúdo misto. Este exemplo demonstra a atualização de um perfil de 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-WebRequest -Uri $Uri -Method Post -Form $Form

O formulário de perfil requer estes campos: firstName, lastName, email, avatar, birthdaye hobbies. A API espera que uma imagem para a foto de perfil do usuário seja fornecida no 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 de HashTable são convertidos em cadeias de caracteres. Se um valor de System.IO.FileInfo estiver presente, o conteúdo do arquivo será enviado. Se uma coleção, como matrizes ou listas, estiver presente, o campo de formulário será enviado várias vezes.

Usando Get-Item na chave avatar, o objeto FileInfo é definido como o valor. O resultado é que os dados de imagem para 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 da lista.

Exemplo 7: Capturar mensagens sem êxito de Invoke-WebRequest

Quando Invoke-WebRequest encontra uma mensagem HTTP sem êxito (404, 500, etc.), ela não retorna nenhuma saída e lança um erro de encerramento. Para detetar o erro e visualizar o StatusCode você pode incluir a execução em um bloco try/catch.

try
{
    $Response = Invoke-WebRequest -Uri "www.microsoft.com/unkownhost"
    # This will only execute if the Invoke-WebRequest is successful.
    $StatusCode = $Response.StatusCode
}
catch
{
    $StatusCode = $_.Exception.Response.StatusCode.value__
}
$StatusCode

404

O erro de encerramento é detetado pelo bloco catch, que recupera o StatusCode do objeto Exception.

Parâmetros

-AllowUnencryptedAuthentication

Permite o envio de credenciais e segredos através de ligações não encriptadas. Por padrão, o fornecimento de 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 é abortada para evitar a comunicação involuntária de segredos em texto sem formatação em conexões não criptografadas. Para substituir este comportamento, por sua conta e risco, forneça o parâmetro AllowUnencryptedAuthentication.

Advertência

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 no PowerShell 6.0.0.

Propriedades dos parâmetros

Tipo:SwitchParameter
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-Authentication

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

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

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

A disponibilização de Autenticação substitui quaisquer cabeçalhos Authorization fornecidos a Cabeçalhos ou incluídos no WebSession .

Esse recurso foi adicionado no PowerShell 6.0.0.

Propriedades dos parâmetros

Tipo:WebAuthenticationType
Default value:None
Valores aceites:None, Basic, Bearer, OAuth
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-Body

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

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

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

O parâmetro Body também pode aceitar um System.Net.Http.MultipartFormDataContent objeto. Isso facilita multipart/form-data solicitações. Quando um objeto de MultipartFormDataContent é fornecido para Body , todos os cabeçalhos relacionados a Conteúdo fornecidos aos parâmetros ContentType, Headersou WebSession são substituídos pelos cabeçalhos Content do objeto MultipartFormDataContent. Esse recurso foi adicionado no PowerShell 6.0.0.

Propriedades dos parâmetros

Tipo:Object
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:True
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-Certificate

Especifica o certificado de cliente 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

Tipo:X509Certificate
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos: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 (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 do certificado, use o comando Get-Item ou Get-ChildItem na unidade de Cert: do PowerShell.

Observação

Atualmente, esse recurso só é suportado em plataformas de sistema operacional Windows.

Propriedades dos parâmetros

Tipo:String
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-ContentType

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

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

ContentType é substituído quando um objeto MultipartFormDataContent é fornecido para Body.

Propriedades dos parâmetros

Tipo:String
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos: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.

de credenciais pode ser usado sozinho ou em conjunto com determinadas opções de Autenticação parâmetros. Quando usado sozinho, ele só fornece credenciais para o servidor remoto se o servidor remoto enviar uma solicitação de desafio de autenticação. Quando usado com opções de de autenticação, as credenciais são enviadas explicitamente.

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

Observação

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

Propriedades dos parâmetros

Tipo:PSCredential
Default value:Current user
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-CustomMethod

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

Este exemplo faz uma solicitação HTTP TEST para a API:

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

Esse recurso foi adicionado no PowerShell 6.0.0.

Propriedades dos parâmetros

Tipo:String
Default value:None
Suporta carateres universais:False
NãoMostrar:False
Aliases:CM

Conjuntos de parâmetros

CustomMethod
Position:Named
Obrigatório:True
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False
CustomMethodNoProxy
Position:Named
Obrigatório:True
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-DisableKeepAlive

Indica que o cmdlet 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 solicitações subsequentes.

Propriedades dos parâmetros

Tipo:SwitchParameter
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-Form

Converte um dicionário em uma submissão de multipart/form-data. Formulário não pode ser utilizado com Body. Se ContentType for usado, ele será ignorado.

As chaves do dicionário são usadas como os nomes dos campos de 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 nome do arquivo propriedade. 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 Matrizes ou Listas, o campo for 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 são fornecidos três vezes no formulário, uma vez para cada um dos Vacation, Italye 2017. O campo pictures também é enviado uma vez para cada arquivo na pasta 2017-Italy. O conteúdo binário dos ficheiros nesta pasta é enviado como os valores.

Esse recurso foi adicionado no PowerShell 6.1.0.

Propriedades dos parâmetros

Tipo:IDictionary
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-Headers

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

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

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

Propriedades dos parâmetros

Tipo:IDictionary
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-InFile

Obtém o conteúdo da solicitação da Web de um arquivo. Insira um caminho e um nome de arquivo. Se você omitir o caminho, o padrão será o local atual.

Propriedades dos parâmetros

Tipo:String
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos: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 dos parâmetros

Tipo:Int32
Default value:5
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-MaximumRetryCount

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

Propriedades dos parâmetros

Tipo:Int32
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos: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 dos parâmetros

Tipo:WebRequestMethod
Default value:None
Valores aceites:Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

StandardMethod
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False
StandardMethodNoProxy
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-NoProxy

Indica que o cmdlet não deve usar um proxy para chegar ao destino. Quando você precisar ignorar o proxy configurado no ambiente, use essa opção. Esse recurso foi adicionado no PowerShell 6.0.0.

Propriedades dos parâmetros

Tipo:SwitchParameter
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

StandardMethodNoProxy
Position:Named
Obrigatório:True
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False
CustomMethodNoProxy
Position:Named
Obrigatório:True
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-OutFile

Especifica o arquivo de saída para o qual esse cmdlet salva o corpo da resposta. Insira um caminho e um nome de arquivo. Se você omitir o caminho, o padrão será o local atual. O nome é tratado como um caminho literal. Os nomes que contenham parênteses ([]) devem ser colocados entre aspas simples (').

Por padrão, Invoke-WebRequest 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

Tipo:String
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-PassThru

Indica que o cmdlet 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

Tipo:SwitchParameter
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-PreserveAuthorizationOnRedirect

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

Por padrão, o cmdlet remove o cabeçalho Authorization antes de redirecionar. A especificação desse 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 no PowerShell 6.0.0.

Propriedades dos parâmetros

Tipo:SwitchParameter
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-Proxy

Especifica 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

Tipo:Uri
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

StandardMethod
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False
CustomMethod
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos: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

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

Tipo:PSCredential
Default value:Current user
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

StandardMethod
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False
CustomMethod
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-ProxyUseDefaultCredentials

Indica que o cmdlet 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

Tipo:SwitchParameter
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

StandardMethod
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False
CustomMethod
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-Resume

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

Retomar opera apenas no tamanho do ficheiro local e do ficheiro remoto e não executa nenhuma outra validação de que o ficheiro local e o ficheiro remoto são os mesmos.

Se o tamanho do arquivo local for menor do que o tamanho do arquivo remoto, o cmdlet tentará retomar o download do arquivo e anexar 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 do que o tamanho do arquivo remoto, o arquivo local será substituído e todo o arquivo remoto será baixado novamente. Este comportamento é o mesmo que usar OutFile sem Resume.

Se o servidor remoto não suportar a retomada do download, o arquivo local será substituído e todo o arquivo remoto será baixado novamente. Este 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. Este comportamento é o mesmo que usar OutFile sem Resume.

Esse recurso foi adicionado no PowerShell 6.1.0.

Propriedades dos parâmetros

Tipo:SwitchParameter
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-RetryIntervalSec

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

Propriedades dos parâmetros

Tipo:Int32
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-SessionVariable

Especifica uma variável para a qual esse cmdlet cria uma sessão de solicitação da Web e a salva no valor. Insira um nome de variável sem o símbolo cifrão ($).

Quando você especifica uma variável de sessão, Invoke-WebRequest cria um objeto de sessão de solicitação da Web e o atribui a uma variável com o nome especificado em sua sessão do PowerShell. Você pode usar a variável 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 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

Tipo:String
Default value:None
Suporta carateres universais:False
NãoMostrar:False
Aliases:SV

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-SkipCertificateCheck

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

Advertência

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

Esse recurso foi adicionado no PowerShell 6.0.0.

Propriedades dos parâmetros

Tipo:SwitchParameter
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos: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. A especificação deste interruptor desativa a validação para permitir que o valor seja passado sem validação. Quando especificado, todos os cabeçalhos são adicionados sem validação.

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

Esse recurso foi adicionado no PowerShell 6.0.0.

Propriedades dos parâmetros

Tipo:SwitchParameter
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos: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 registadas no pipeline como se tivessem sido bem-sucedidas.

Esse parâmetro foi introduzido no PowerShell 7.

Propriedades dos parâmetros

Tipo:SwitchParameter
Default value:False
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-SslProtocol

Define os protocolos SSL/TLS permitidos para a solicitação da Web. Por padrão, todos os protocolos SSL/TLS suportados pelo 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 juntos para definir vários sinalizadores usando esse parâmetro. Os valores podem ser passados para o parâmetro SslProtocol como uma matriz de valores ou como uma cadeia de caracteres separada por vírgulas desses valores. O cmdlet combinará os valores usando uma operação binary-OR. Passar valores como uma matriz é a opção mais simples e também permite que você use o preenchimento de tabulação nos valores. Talvez não seja possível definir várias opções em todas as plataformas.

Observação

Em plataformas que não sejam Windows, pode 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.

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

Propriedades dos parâmetros

Tipo:WebSslProtocol
Default value:None
Valores aceites:Default, Tls, Tls11, Tls12
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-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

Tipo:Int32
Default value:0
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-Token

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

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

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

Esse parâmetro foi introduzido no PowerShell 6.0.

Propriedades dos parâmetros

Tipo:SecureString
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos: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
  • Desinflar
  • GZip
  • Identidade

Propriedades dos parâmetros

Tipo:String
Default value:None
Valores aceites:chunked, compress, deflate, gzip, identity
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-Uri

Especifica o URI (Uniform Resource Identifier) do recurso da Internet para o qual a solicitação da Web é enviada. Insira um URI. Este parâmetro suporta apenas HTTP ou HTTPS.

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

Propriedades dos parâmetros

Tipo:Uri
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:0
Obrigatório:True
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-UseBasicParsing

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

Propriedades dos parâmetros

Tipo:SwitchParameter
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos: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 de Autenticação ou de Credenciais e pode não ser suportado em todas as plataformas.

Propriedades dos parâmetros

Tipo:SwitchParameter
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-UserAgent

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

O agente de usuário padrão é semelhante ao 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 padrão do agente do usuário usada pela maioria dos navegadores da Internet, use as propriedades da classe PSUserAgent , como Chrome, FireFox, InternetExplorer, Opera e Safari.

Por exemplo, o comando a seguir usa a cadeia de caracteres do agente do usuário para o Internet Explorer: Invoke-WebRequest -Uri https://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)

Propriedades dos parâmetros

Tipo:String
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-WebSession

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

Para substituir um valor na sessão de solicitação da Web, use um parâmetro de cmdlet, como UserAgent ou Credential. Os valores dos parâmetros têm precedência sobre os valores na sessão de solicitação da Web. Cabeçalhos relacionados ao conteúdo, como Content-Type, também 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 estado e dados entre solicitações da Web.

Para criar uma sessão de pedido da web, insira um nome de variável, sem o símbolo de dólar, no valor do parâmetro SessionVariable de um comando Invoke-WebRequest. Invoke-WebRequest 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

Tipo:WebRequestSession
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

CommonParameters

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

Entradas

Object

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

Saídas

BasicHtmlWebResponseObject

Notas

A partir do PowerShell 6.0.0, o Invoke-WebRequest oferece suporte apenas à análise básica.

Para obter mais informações, consulte BasicHtmlWebResponseObject.

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 desta propriedade é determinado pela sua plataforma:

  • Para Windows: Lê a configuração de proxy de variáveis de ambiente. Se essas variáveis não forem definidas, a propriedade será derivada das configurações de proxy do usuário.
  • Para macOS: Lê a configuração de proxy de variáveis de ambiente. Se essas variáveis não forem definidas, a propriedade será derivada das configurações de proxy do sistema.
  • Para Linux: Lê a configuração de proxy a partir de variáveis de ambiente. Se essas variáveis não forem definidas, a propriedade inicializa uma instância não configurada que ignora todos os endereços.

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

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