Invoke-WebRequest
Obtém conteúdo de uma página da Web na Internet.
Syntax
Invoke-WebRequest
[-UseBasicParsing]
[-Uri] <Uri>
[-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>]
Invoke-WebRequest
[-UseBasicParsing]
[-Uri] <Uri>
[-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>]
-NoProxy
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>]
Invoke-WebRequest
[-UseBasicParsing]
[-Uri] <Uri>
[-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>]
-CustomMethod <String>
[-Proxy <Uri>]
[-ProxyCredential <PSCredential>]
[-ProxyUseDefaultCredentials]
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>]
Invoke-WebRequest
[-UseBasicParsing]
[-Uri] <Uri>
[-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>]
-CustomMethod <String>
-NoProxy
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>]
Description
O Invoke-WebRequest
cmdlet envia solicitações HTTP e HTTPS para uma página da Web ou serviço Web. Ele analisa a resposta e retorna conjuntos de links, imagens e outros elementos HTML significativos.
Esse cmdlet foi introduzido no PowerShell 3.0.
A partir do PowerShell 7.0, Invoke-WebRequest
dá suporte à configuração de proxy definida por variáveis de ambiente. Consulte a seção Anotações deste artigo.
Importante
Os exemplos neste artigo referenciam hosts no contoso.com
domínio. Esse é 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 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 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 $Response
variável.
O segundo comando obtém qualquer InputField em que a propriedade Name é como "* Value"
. Os resultados filtrados são canalizados para Select-Object
selecionar as propriedades 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.
$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
enviar uma solicitação de entrada. O comando especifica um valor de "Session" para o valor do parâmetro -SessionVariable e salva o resultado na $LoginResponse
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 exige que o usuário seja conectado ao site. Os dados de sessão armazenados na $Session
variável são usados para fornecer cookies de sessão ao site criado durante o logon. O resultado é salvo na $ProfileResponse
variável .
A chamada para $ProfileResponse
por si só mostra o BasicHtmlWebResponseObject
na variável .
Exemplo 3: Obter links de uma página da Web
Este exemplo obtém os links em uma página da Web. Ele usa o Invoke-WebRequest
cmdlet 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 Invoke-WebRequest
cmdlet 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 $Response
variável.
O segundo comando cria um StreamWriter
a ser usado para gravar o conteúdo da resposta em um arquivo. A propriedade Encoding do objeto de resposta é usada para definir a codificação do arquivo.
Os últimos comandos gravam a propriedade Content no arquivo e descartam o StreamWriter
.
Observe que a propriedade Codificação será nula se a solicitação da Web não retornar conteúdo de texto.
Exemplo 5: Enviar um arquivo de dados de várias partes/formulários
Este exemplo usa o Invoke-WebRequest
cmdlet upload de um arquivo como um multipart/form-data
envio. O arquivo c:\document.txt
é enviado como o campo document
de formulário 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: Envio simplificado de dados de várias partes/formulários
Algumas APIs exigem multipart/form-data
envios 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
, birthday
, e hobbies
. A API espera que uma imagem para a foto de perfil do usuário seja fornecida no avatar
campo. A API também aceita várias hobbies
entradas 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 da HashTable são convertidos em cadeias de caracteres. Se um valor System.IO.FileInfo estiver presente, o conteúdo do arquivo será enviado. Se uma coleção como matrizes ou listas estiverem presentes, o campo de formulário será enviado várias vezes.
Get-Item
Usando na avatar
chave, o FileInfo
objeto é definido como o valor . O resultado é que os dados da imagem para jdoe.png
são enviados.
Ao fornecer uma lista para a hobbies
chave, o hobbies
campo estará presente nos envios uma vez para cada item de 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 gera um erro de encerramento. Para capturar o erro e exibir o StatusCode , você pode colocar 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 pelo catch
bloco, que recupera o StatusCode do objeto Exception .
Parâmetros
-AllowUnencryptedAuthentication
Permite o envio de credenciais e segredos em conexões não criptografadas. Por padrão, fornecer 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 é anulada para evitar a comunicação intencional de segredos em texto sem formatação em conexões não criptografadas. Para substituir esse comportamento por sua conta e risco, forneça o parâmetro AllowUnencryptedAuthentication .
Aviso
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 ao PowerShell 6.0.0.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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
: essa é 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çãoAuthorization: Basic
Básica RFC 7617 no formato debase64(user:password)
.Bearer
: requer o parâmetro Token . Envia um cabeçalho RFC 6750Authorization: Bearer
com o token fornecido.OAuth
: requer o parâmetro Token . Envia um cabeçalho RFC 6750Authorization: Bearer
com o token fornecido.
Fornecer Autenticação substitui todos Authorization
os cabeçalhos fornecidos para Cabeçalhos ou incluídos na WebSession.
Esse recurso foi adicionado ao PowerShell 6.0.0.
Type: | WebAuthenticationType |
Accepted values: | None, Basic, Bearer, OAuth |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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 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 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 as multipart/form-data
solicitações. Quando um objeto MultipartFormDataContent é fornecido para Body, todos os cabeçalhos relacionados a Content fornecidos aos parâmetrosContentType, Headers ou WebSession são substituídos pelos cabeçalhos Content do objeto MultipartFormDataContent. Esse recurso foi adicionado ao PowerShell 6.0.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 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 utilizados na autenticação baseada em certificado do cliente. Eles só podem ser mapeados 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 Get-Item
comando ou Get-ChildItem
na unidade do PowerShell Cert:
.
Observação
Atualmente, esse recurso só tem suporte em plataformas do sistema operacional Windows.
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.
ContentType é substituído quando um objeto MultipartFormDataContent é fornecido para Body.
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 .
A credencial pode ser usada sozinha ou em conjunto com determinadas opções de parâmetro de autenticação . Quando usado sozinho, ele só fornece credenciais para o servidor remoto se o servidor remoto envia uma solicitação de desafio de autenticação. Quando usadas com opções de autenticação , as credenciais são enviadas explicitamente.
As credenciais são armazenadas em um objeto PSCredential e a senha é armazenada como uma SecureString.
Observação
Para obter mais informações sobre a proteção de dados SecureString , consulte Quão seguro é SecureString?.
Type: | PSCredential |
Position: | Named |
Default value: | Current user |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CustomMethod
Especifica um método personalizado usado para a solicitação da Web. Isso poderá 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 . O método e o CustomMethod não podem ser usados juntos.
Este exemplo faz uma solicitação TEST
HTTP para a API:
Invoke-WebRequest -uri 'https://api.contoso.com/widget/' -CustomMethod 'TEST'
Esse recurso foi adicionado ao PowerShell 6.0.0.
Type: | String |
Aliases: | CM |
Position: | Named |
Default value: | None |
Required: | True |
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: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Form
Converte um dicionário em um multipart/form-data
envio. O formulário não pode ser usado com Corpo.
Se ContentType for usado, ele será ignorado.
As chaves do dicionário são usadas como nomes de campo 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 a propriedade filename . 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 tags
campo é fornecido três vezes no formulário, uma vez para cada um de Vacation
, Italy
e 2017
. O pictures
campo também é enviado uma vez para cada arquivo na 2017-Italy
pasta . O conteúdo binário dos arquivos nessa pasta é enviado como os valores.
Esse recurso foi adicionado ao PowerShell 6.1.0.
Type: | IDictionary |
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 de agente de usuário ou cookie.
Cabeçalhos relacionados ao conteúdo, como Content-Type
é substituído quando um objeto MultipartFormDataContent é fornecido para Body.
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 |
-MaximumRetryCount
Especifica quantas vezes o PowerShell tentará novamente uma conexão quando um código de falha entre 400 e 599, inclusive ou 304 for recebido. Consulte também o parâmetro RetryIntervalSec para especificar o número de repetições.
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
O parâmetro CustomMethod pode ser usado para métodos de solicitação não listados acima.
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 |
-NoProxy
Indica que o cmdlet não deve usar um proxy para alcançar o destino. Quando você precisar ignorar o proxy configurado no ambiente, use essa opção. Esse recurso foi adicionado ao PowerShell 6.0.0.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | True |
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. O nome é tratado como um caminho literal.
Os nomes que contêm colchetes ([]
) 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.
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: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-PreserveAuthorizationOnRedirect
Indica que o cmdlet deve preservar o Authorization
cabeçalho, quando presente, entre redirecionamentos.
Por padrão, o cmdlet remove o Authorization
cabeçalho antes de redirecionar. Especificar esse 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 ao PowerShell 6.0.0.
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 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, User@Domain.Comou insira um PSCredential
objeto, como um gerado pelo Get-Credential
cmdlet .
Esse parâmetro é válido somente quando o parâmetro Proxy também é usado no comando . Você não pode 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 .
Esse parâmetro é válido somente quando o parâmetro Proxy também é usado no comando . Você não pode usar os parâmetros ProxyCredential e ProxyUseDefaultCredentials no mesmo comando.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Resume
Executa uma tentativa de melhor esforço para retomar o download de um arquivo parcial. Retomar requer OutFile.
O Resume opera apenas no tamanho do arquivo local e do arquivo remoto e não executa nenhuma outra validação de que o arquivo local e o arquivo remoto sejam os mesmos.
Se o tamanho do arquivo local for menor que o tamanho do arquivo remoto, o cmdlet tentará retomar o download do arquivo e acrescentar 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á tomada e o cmdlet assumirá que o download já foi concluído.
Se o tamanho do arquivo local for maior que o tamanho do arquivo remoto, o arquivo local será substituído e todo o arquivo remoto será baixado novamente. Esse comportamento é o mesmo que usar OutFile sem Resume.
Se o servidor remoto não der suporte à retomada do download, o arquivo local será substituído e todo o arquivo remoto será baixado novamente. Esse 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. Esse comportamento é o mesmo que usar OutFile sem Resume.
Esse recurso foi adicionado ao PowerShell 6.1.0.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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 o parâmetro MaximumRetryCount para especificar o número de repetições.
Type: | Int32 |
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 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 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.
Você não pode 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 |
-SkipCertificateCheck
Ignora as verificações de validação de certificado. Isso inclui todas as validações, como expiração, revogação, autoridade raiz confiável etc.
Aviso
O uso desse parâmetro não é seguro e não é recomendado. Essa opção destina-se apenas a ser usada em hosts conhecidos usando um certificado autoassinado para fins de teste. Use por sua conta e risco.
Esse recurso foi adicionado ao PowerShell 6.0.0.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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. Especificar essa opção desabilita a validação para permitir que o valor seja passado desmarcado. Quando especificado, todos os cabeçalhos são adicionados sem validação.
Essa opção desabilita a validação de valores passados para os parâmetrosContentType, Headers e UserAgent.
Esse recurso foi adicionado ao PowerShell 6.0.0.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SkipHttpErrorCheck
Esse parâmetro faz com que o cmdlet ignore os status de erro HTTP e continue processando respostas. As respostas de erro são gravadas no pipeline como se tivessem sido bem-sucedidas.
Esse parâmetro foi introduzido no PowerShell 7.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SslProtocol
Define os protocolos SSL/TLS que são permitidos para a solicitação da Web. Por padrão, todos os protocolos SSL/TLS compatíveis com o sistema são permitidos. O SslProtocol permite a limitação de 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 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 a conclusão de tabulação nos valores. Talvez você não consiga definir várias opções em todas as plataformas.
Observação
Em plataformas não Windows, pode não ser possível fornecer Tls
ou Tls12
como uma opção. O suporte para Tls13
não está disponível em todos os sistemas operacionais e precisará ser verificado por sistema operacional.
Esse recurso foi adicionado ao PowerShell 6.0.0 e o suporte para Tls13
foi adicionado ao PowerShell 7.1.
Type: | WebSslProtocol |
Accepted values: | Default, Tls, Tls11, Tls12 |
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 um 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 lançada e sua solicitação expirar.
Type: | Int32 |
Position: | Named |
Default value: | 0 |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Token
O token OAuth ou Bearer a ser incluído na solicitação. O token é exigido por determinadas opções de autenticação . Ele não pode ser usado de forma independente.
O token usa 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.
Type: | SecureString |
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 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 apenas a HTTP ou HTTPS.
Este parâmetro é necessário. O URI do nome do parâmetro é opcional.
Type: | Uri |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UseBasicParsing
Esse parâmetro foi preterido. A partir do PowerShell 6.0.0, todas as solicitações da Web usam somente 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.
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. Isso não pode ser usado com Autenticação ou Credencial e pode não ter suporte em todas as plataformas.
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 de usuário padrão é semelhante a 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 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 do usuário para a 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. 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 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 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.
Você não pode 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
Você pode redirecionar o corpo de uma solicitação da Web para Invoke-WebRequest
.
Saídas
Observações
A partir do PowerShell 6.0.0 Invoke-WebRequest
dá 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 dessa propriedade é determinado pela 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 de variáveis de ambiente. Se essas variáveis não forem definidas, a propriedade inicializará uma instância não configurada que ignora todos os endereços.
As variáveis de ambiente usadas para inicialização 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 o endereço IP do servidor proxy usado em solicitações HTTP e HTTPS no casoHTTP_PROXY
ouHTTPS_PROXY
não estão definidos.NO_PROXY
: uma lista separada por vírgulas de nomes de host que devem ser excluídos do proxy.