Invoke-WebRequest

Referência

Módulo:: Microsoft.PowerShell.Utility

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

Syntax

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

Este 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 ParsedHtml propriedade. Use a opção -UseBasicParsing para suprimir isso.

Exemplos

Exemplo 1: Enviar uma solicitação da Web

Esse comando usa o Invoke-WebRequest cmdlet 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 $R variável .

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

Exemplo 2: usar um serviço Web com estado

Este exemplo mostra como usar o Invoke-WebRequest cmdlet com um serviço Web com estado, como 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 Invoke-WebRequest cmdlet 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 $R variável . Quando o comando é concluído, a $R variável contém um HtmlWebResponseObject e a $FB variável contém um objeto WebRequestSession .

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

Exemplo 3: Obter links de uma página da Web

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

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

O Invoke-WebRequest cmdlet 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 try/catch bloco. 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 Invoke-WebRequest com uma ErrorAction de Stop, que força Invoke-WebRequest a gerar um erro de encerramento em qualquer solicitação com falha. O erro de encerramento é capturado pelo catch bloco que recupera o StatusCode do objeto Exception .

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 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 padrão name=value .

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

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

-Certificate

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

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

-CertificateThumbprint

Especifica o certificado de chave pública digital (X509) de uma conta de usuário com permissão para executar essa 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 somente 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 Get-Item comando ou Get-ChildItem na unidade do PowerShell Cert: .

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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.

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

-Credential

Especifica uma conta de usuário com 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 Get-Credential cmdlet .

Type:	PSCredential
Position:	Named
Default value:	Current user
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-DisableKeepAlive

Indica que o cmdlet define o valor KeepAlive no cabeçalho HTTP como False. Por padrão, KeepAlive é True. KeepAliveestabelece uma conexão persistente com o servidor para facilitar as solicitações posteriores.

Type:	SwitchParameter
Position:	Named
Default value:	KeepAlive
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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 . Você não pode usar esse parâmetro para especificar cabeçalhos UserAgent ou cookie.

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

-InFile

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

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

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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 qualquer redirecionamento.

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

-Method

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

Default
Excluir
Obter
Head
Mesclar
Opções
Patch
Postar
Put
Trace

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

-OutFile

Especifica o arquivo de saída para o qual esse cmdlet salva o corpo da resposta. Digite um caminho e 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.

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

-PassThru

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

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

-Proxy

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

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

-ProxyCredential

Especifica uma conta de usuário com permissão para conectar-se aos computadores especificados 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 Get-Credential cmdlet .

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.

Type:	PSCredential
Position:	Named
Default value:	Current user
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ProxyUseDefaultCredentials

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

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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 em sua sessão do PowerShell. Você pode usar a variável na sessão, assim que o comando for concluído.

Diferente 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 de 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 da web nas solicitações da Web posteriores, 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. Valores de parâmetro têm precedência sobre valores na seção de solicitação da Web.

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

Type:	String
Aliases:	SV
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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 atingir o tempo limite. Se sua solicitação contiver um nome de host que exija resolução e você definir TimeoutSec como um valor maior que zero, mas menor que 15 segundos, poderá levar 15 segundos ou mais antes que uma WebException seja gerada e sua solicitação diminua o tempo limite.

Type:	Int32
Position:	Named
Default value:	None
Required:	False
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 esse parâmetro são:

Blocos
Compactar
Desinflar
GZip
Identidade

Type:	String
Accepted values:	chunked, compress, deflate, gzip, identity
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Uri

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

Este parâmetro é necessário.

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

-UseBasicParsing

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

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

-UseDefaultCredentials

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

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

-UserAgent

Especifica uma cadeia de caracteres 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 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 a Internet Explorer

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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 Credential. Valores de parâmetro têm precedência sobre valores na seção de solicitação 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 Invoke-WebRequest comando. Invoke-WebRequest cria a sessão e a salva na variável . Em comandos posteriores, 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.

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

Entradas

Object

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

Saídas

HtmlWebResponseObject

Compartilhar via

Invoke-WebRequest

Syntax

Description

Exemplos

Exemplo 1: Enviar uma solicitação da Web

Exemplo 2: usar um serviço Web com estado

Exemplo 3: Obter links de uma página da Web

Exemplo 4: capturar mensagens sem êxito de Invoke-WebRequest

Parâmetros

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

Entradas

Saídas

Recursos adicionais

Compartilhar via

Invoke-WebRequest

Syntax

Description

Exemplos

Exemplo 1: Enviar uma solicitação da Web

Exemplo 2: usar um serviço Web com estado

Exemplo 3: Obter links de uma página da Web

Exemplo 4: capturar mensagens sem êxito de Invoke-WebRequest

Parâmetros

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

Entradas

Saídas

Links Relacionados

Recursos adicionais