Invoke-WebRequest

Referência

Módulo:: Microsoft.PowerShell.Utility

Obtém 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 -UseBasicParsing opção para suprimir isso.

Importante

Os exemplos neste artigo fazem referência a contoso.com hosts no domínio. Este é um domínio fictício usado pela Microsoft para exemplos. Os exemplos foram criados 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 hosts em seu ambiente.

Exemplos

Exemplo 1: Enviar uma solicitação da Web

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

$Response = Invoke-WebRequest -UseBasicParsing -URI https://www.bing.com?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

Os dados retornados por Invoke-WebRequest são armazenados na $Response variável. A propriedade InputFields da resposta contém os campos de formulário. Where-Object é usado para filtrar os campos de formulário para aqueles em que a propriedade name é como "* Value". Os resultados filtrados são canalizados para Select-Object selecionar as propriedades name e value .

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

Este exemplo mostra como usar o cmdlet com um serviço Web com monitoração de estado, como o Invoke-WebRequest 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 $R resultado na 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 Web na $R variável indica que o usuário entrou 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 lança um erro de encerramento. Para capturar o erro e exibir o StatusCode, você pode incluir a execução em um try/catch bloco.

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 é capturado catch pelo bloco , que recupera o StatusCode do objeto Exception.

Exemplo 8: Baixar vários arquivos ao mesmo tempo

O Invoke-WebRequest cmdlet só pode baixar um arquivo por vez. O exemplo a seguir usa Start-ThreadJob para criar vários trabalhos de thread para baixar vários arquivos ao mesmo tempo.

$baseUri = 'https://github.com/PowerShell/PowerShell/releases/download'
$files = @(
    @{
        Uri = "$baseUri/v7.3.0-preview.5/PowerShell-7.3.0-preview.5-win-x64.msi"
        OutFile = 'PowerShell-7.3.0-preview.5-win-x64.msi'
    },
    @{
        Uri = "$baseUri/v7.3.0-preview.5/PowerShell-7.3.0-preview.5-win-x64.zip"
        OutFile = 'PowerShell-7.3.0-preview.5-win-x64.zip'
    },
    @{
        Uri = "$baseUri/v7.2.5/PowerShell-7.2.5-win-x64.msi"
        OutFile = 'PowerShell-7.2.5-win-x64.msi'
    },
    @{
        Uri = "$baseUri/v7.2.5/PowerShell-7.2.5-win-x64.zip"
        OutFile = 'PowerShell-7.2.5-win-x64.zip'
    }
)

$jobs = @()

foreach ($file in $files) {
    $jobs += Start-ThreadJob -Name $file.OutFile -ScriptBlock {
        $params = $using:file
        Invoke-WebRequest @params
    }
}

Write-Host "Downloads started..."
Wait-Job -Job $jobs

foreach ($job in $jobs) {
    Receive-Job -Job $job
}

Observação

Para usar o Start-ThreadJob cmdlet, você deve instalar o módulo ThreadJob da Galeria do PowerShell.

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 canalizar 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 outros tipos de solicitação (como POST), 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 usado para uma solicitação segura da Web. 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 Certificate (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 utilizados na autenticação baseada em certificado do cliente. Os certificados só podem ser mapeados para contas de usuário locais, não para contas de domínio.

Para ver a impressão digital do certificado, use o Get-Item comando or Get-ChildItem para localizar o certificado no Cert:\CurrentUser\My.

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 defina 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 gerado pelo Get-Credential cmdlet.

As credenciais são armazenadas em um objeto PSCredential e a senha é armazenada como um SecureString.

Observação

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

Type:	PSCredential
Position:	Named
Default value:	None
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. KeepAlive estabelece uma conexão persistente com o servidor para facilitar solicitações subsequentes.

Type:	SwitchParameter
Position:	Named
Default value:	None
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:	None
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
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace

Type:	WebRequestMethod
Accepted values:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Position:	Named
Default value:	None
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 gravá-los em um arquivo. Esse parâmetro é válido somente quando o parâmetro OutFile também é usado no comando.

Type:	SwitchParameter
Position:	Named
Default value:	None
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 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 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:	None
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.

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 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. 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 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, poderá levar 15 segundos ou mais até que uma WebException seja lançada e sua solicitação atinja 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:

Chunked
Compress
Deflate
GZip
Identity

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 é obrigatório. O nome do parâmetro Uri é opcional.

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

-UseDefaultCredentials

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

Type:	SwitchParameter
Position:	Named
Default value:	None
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 do usuário padrão é semelhante ao 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 do 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 do usuário para o Internet Explorer: Invoke-WebRequest -Uri https://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)

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

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 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 Invoke-WebRequest comando. 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.

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

Entradas

Object

Você pode canalizar o corpo de uma solicitação da Web para esse cmdlet.

Saídas

HtmlWebResponseObject

Esse cmdlet retorna o objeto de resposta que representa o resultado da solicitação da Web.

Observações

O Windows PowerShell inclui os seguintes aliases para Invoke-WebRequest:

iwr

Compartilhar via

Invoke-WebRequest

Syntax

Description

Exemplos

Exemplo 1: Enviar uma solicitação da Web

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

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

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

Exemplo 8: Baixar vários arquivos ao mesmo tempo

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

Observações

Comentários

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 monitoração de estado

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

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

Exemplo 8: Baixar vários arquivos ao mesmo tempo

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

Observações

Links Relacionados

Comentários

Recursos adicionais