Compartilhar via

Invoke-WebRequest

Módulo:
Microsoft.PowerShell.Utility Module

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

Sintaxe

Default (Default) 

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

Description

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

Esse cmdlet foi introduzido no Windows PowerShell 3.0.

Observação

Por padrão, o código de script na página da Web pode ser executado quando a página está sendo analisada para preencher a propriedade ParsedHtml. Use a opção -UseBasicParsing para suprimir isso.

Exemplos

Exemplo 1: Enviar uma solicitação da Web

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

$R = Invoke-WebRequest -URI https://www.bing.com?q=how+many+feet+in+a+mile
$R.AllElements | Where-Object {
    $_.name -like "* Value" -and $_.tagName -eq "INPUT"
} | 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 $R.

O segundo comando filtra os objetos na propriedade AllElements em que o nome propriedade é como "* Value" e o tagName é "INPUT". Os resultados filtrados são canalizados para Select-Object para selecionar o nome e valor propriedades.

Exemplo 2: usar um serviço Web com estado

Este exemplo mostra como usar o cmdlet Invoke-WebRequest com um serviço Web com estado, como o Facebook.

$R = Invoke-WebRequest https://www.facebook.com/login.php -SessionVariable fb
# This command stores the first form in the Forms property of the $R variable in the $Form variable.
$Form = $R.Forms[0]
# This command shows the fields available in the Form.
$Form.fields

Key                     Value
---                     -----
...
email
pass
...

# These commands populate the username and password of the respective Form fields.
$Form.Fields["email"]="User01@Fabrikam.com"
$Form.Fields["pass"]="P@ssw0rd"
# This command creates the Uri that will be used to log in to facebook.
# The value of the Uri parameter is the value of the Action property of the form.
$Uri = "https://www.facebook.com" + $Form.Action
# Now the Invoke-WebRequest cmdlet is used to sign into the Facebook web service.
# The WebRequestSession object in the $FB variable is passed as the value of the WebSession parameter.
# The value of the Body parameter is the hash table in the Fields property of the form.
# The value of the *Method* parameter is POST. The command saves the output in the $R variable.
$R = Invoke-WebRequest -Uri $Uri -WebSession $FB -Method POST -Body $Form.Fields
$R.StatusDescription

O primeiro comando usa o cmdlet Invoke-WebRequest para enviar uma solicitação de entrada. O comando especifica um valor de "FB" para o valor do parâmetro SessionVariable e salva o resultado na variável $R. Quando o comando é concluído, a variável contém um HtmlWebResponseObject e a variável contém um objeto WebRequestSession.

Depois que o cmdlet Invoke-WebRequest entrar no facebook, a propriedade StatusDescription do objeto de resposta da Web na variável $R indica que o usuário está conectado com êxito.

Esse comando obtém os links em uma página da Web.

(Invoke-WebRequest -Uri "https://devblogs.microsoft.com/powershell/").Links.Href

O cmdlet Invoke-WebRequest obtém o conteúdo da página da Web. Em seguida, a propriedade links do htmlWebResponseObject retornado é usada para exibir a propriedade Href de cada link.

Exemplo 4: 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 gera um erro de encerramento. Para capturar o erro e exibir o StatusCode você pode colocar a execução em um bloco de try/catch. O exemplo a seguir mostra como fazer isso.

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

404

O primeiro comando chama com uma ErrorAction de Parar, o que força a lançar um erro de encerramento em solicitações com falha. O erro de terminação é capturado pelo bloco que recupera o StatusCode do objeto Exception.

Parâmetros

-Body

Especifica o corpo da solicitação. O corpo da solicitação é o conteúdo que segue os cabeçalhos. Você também pode redirecionar um valor de corpo para Invoke-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 outras solicitações GET, o corpo é definido como o valor do corpo da solicitação no formato de name=value padrão.

Quando o corpo é um formulário ou é a saída de uma chamada Invoke-WebRequest, o 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

  • ou -

Invoke-RestMethod https://website.com/service.aspx -Body $r.Forms\[0\]

Propriedades do parâmetro

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

Conjuntos de parâmetros

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

-Certificate

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

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

Propriedades do parâmetro

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

Conjuntos de parâmetros

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

-CertificateThumbprint

Especifica o certificado de chave pública digital (X509) de uma conta de usuário que tem permissão para enviar a solicitação. Insira a impressão digital do certificado. Os certificados são usados na autenticação baseada em certificado do cliente. Eles podem ser mapeados apenas para contas de usuário local; eles não funcionam com contas de domínio.

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

Propriedades do parâmetro

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

Conjuntos de parâmetros

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

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

Propriedades do parâmetro

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

Conjuntos de parâmetros

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

-Credential

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

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

Propriedades do parâmetro

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

Conjuntos de parâmetros

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

-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 as solicitações subsequentes.

Propriedades do parâmetro

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

Conjuntos de parâmetros

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

-Headers

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

Para definir cabeçalhos UserAgent, use o parâmetro UserAgent. Você não pode usar esse parâmetro para especificar useragent ou cabeçalhos de cookie.

Propriedades do parâmetro

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

Conjuntos de parâmetros

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

-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 do parâmetro

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

Conjuntos de parâmetros

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

-MaximumRedirection

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

Propriedades do parâmetro

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

Conjuntos de parâmetros

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

-Method

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

  • Padrão
  • Excluir
  • Obter
  • Head
  • Mesclar
  • Opções
  • Patch
  • Postar
  • Put
  • Traço

Propriedades do parâmetro

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

Conjuntos de parâmetros

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

-OutFile

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.

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 do parâmetro

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

Conjuntos de parâmetros

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

-PassThru

Indica que o cmdlet retorna os resultados, além de escrevê-los em um arquivo. Esse parâmetro é válido somente quando o parâmetro OutFile também é usado no comando.

Propriedades do parâmetro

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

Conjuntos de parâmetros

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

-Proxy

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 do parâmetro

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

Conjuntos de parâmetros

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

-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 do parâmetro

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

Conjuntos de parâmetros

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

-ProxyUseDefaultCredentials

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

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 do parâmetro

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

Conjuntos de parâmetros

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

-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 de 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 na 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 o estado e os dados entre solicitações da Web.

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

Não é possível usar os parâmetros sessionvariable e webSession no mesmo comando.

Propriedades do parâmetro

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

Conjuntos de parâmetros

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

-TimeoutSec

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

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

Propriedades do parâmetro

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

Conjuntos de parâmetros

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

-TransferEncoding

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

  • Em partes
  • Comprimir
  • Deflate
  • GZip
  • Identidade

Propriedades do parâmetro

Tipo:String
Valor padrão:None
Valores aceitos:chunked, compress, deflate, gzip, identity
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

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

-Uri

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

Este parâmetro é obrigatório.

Propriedades do parâmetro

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

Conjuntos de parâmetros

(All)
Cargo:0
Obrigatório:True
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-UseBasicParsing

Indica que o cmdlet usa o objeto de resposta para conteúdo HTML sem a análise do DOM (Document Object Model). Esse parâmetro é necessário quando o Internet Explorer não está instalado nos computadores, como em uma instalação do Server Core de um sistema operacional Windows Server.

Propriedades do parâmetro

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

Conjuntos de parâmetros

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

-UseDefaultCredentials

Indica que o cmdet usa as credenciais do usuário atual para enviar a solicitação da Web.

Propriedades do parâmetro

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

Conjuntos de parâmetros

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

-UserAgent

Especifica um string de agente de usuário para a requisição web. O agente de usuário padrão é semelhante a Mozilla/5.0 (Windows NT; 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 de agente de usuário padrão usada pela maioria dos navegadores da Internet, use as propriedades da classe PSUserAgent, como Chrome, FireFox, InternetExplorer, Opera e Safari. Por exemplo, o comando a seguir usa a cadeia de caracteres do agente de usuário para o Internet Explorer

Propriedades do parâmetro

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

Conjuntos de parâmetros

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

-WebSession

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

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

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

Para criar uma sessão de solicitação da Web, insira um nome de variável (sem um sinal 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. Nos 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 do parâmetro

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

Conjuntos de parâmetros

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

CommonParameters

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

Entradas

Object

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

Saídas

HtmlWebResponseObject