Invoke-WebRequest
Obtiene contenido de una página web en Internet.
Syntax
Invoke-WebRequest
[-UseBasicParsing]
[-Uri] <Uri>
[-HttpVersion <Version>]
[-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>
[-HttpVersion <Version>]
[-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>
[-HttpVersion <Version>]
[-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>
[-HttpVersion <Version>]
[-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
El Invoke-WebRequest
cmdlet envía solicitudes HTTP y HTTPS a una página web o servicio web. Analiza la respuesta y devuelve colecciones de vínculos, imágenes y otros elementos HTML importantes.
Este cmdlet se introdujo en PowerShell 3.0.
A partir de PowerShell 7.0, Invoke-WebRequest
admite la configuración de proxy definida por variables de entorno. Consulte la sección Notas de este artículo.
Importante
Los ejemplos de este artículo hacen referencia a hosts en el contoso.com
dominio. Se trata de un dominio ficticio usado por Microsoft para obtener ejemplos. Los ejemplos están diseñados para mostrar cómo usar los cmdlets.
Sin embargo, dado que los contoso.com
sitios no existen, los ejemplos no funcionan. Adapte los ejemplos a los hosts de su entorno.
Ejemplos
Ejemplo 1: Envío de una solicitud web
En este ejemplo se usa el Invoke-WebRequest
cmdlet para enviar una solicitud web al sitio de 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
El primer comando emite la solicitud y guarda la respuesta en la $Response
variable .
El segundo comando obtiene cualquier InputField donde la propiedad Name sea como "* Value"
. Los resultados filtrados se canalizan para Select-Object
seleccionar las propiedades Nombre y Valor .
Ejemplo 2: Uso de un servicio web con estado
En este ejemplo se muestra cómo usar el Invoke-WebRequest
cmdlet con un servicio web con estado.
$LoginParameters = @{
Uri = 'https://www.contoso.com/login/'
SessionVariable = 'Session'
Method = 'POST'
Body = @{
User = 'jdoe'
Password = 'P@S$w0rd!'
}
}
$LoginResponse = Invoke-WebRequest @LoginParameters
$ProfileResponse = Invoke-WebRequest 'https://www.contoso.com/profile/' -WebSession $Session
La primera llamada a Invoke-WebRequest
envía una solicitud de inicio de sesión. El comando especifica un valor de Session
para el valor del parámetro SessionVariable . Cuando se completa el comando, la $LoginResponse
variable contiene un BasicHtmlWebResponseObject y la $Session
variable contiene un WebRequestSession
objeto . Esto registra al usuario en el sitio.
La segunda llamada para Invoke-WebRequest
capturar el perfil del usuario, que requiere que el usuario inicie sesión en el sitio. Los datos de sesión almacenados en la $Session
variable proporcionan cookies de sesión al sitio creado durante el inicio de sesión.
Ejemplo 3: Obtener vínculos de una página web
En este ejemplo se obtienen los vínculos de una página web. Usa el Invoke-WebRequest
cmdlet para obtener el contenido de la página web. A continuación, usa la propiedad Links del BasicHtmlWebResponseObject que Invoke-WebRequest
devuelve y la propiedad Href de cada vínculo.
(Invoke-WebRequest -Uri "https://aka.ms/pscore6-docs").Links.Href
Ejemplo 4: Escribir contenido de respuesta en un archivo mediante la codificación definida en la página solicitada
En este ejemplo se usa el Invoke-WebRequest
cmdlet para recuperar el contenido de la página web de una página de documentación de 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()
}
El primer comando recupera la página y guarda el objeto de respuesta en la $Response
variable .
El segundo comando crea un Objeto StreamWriter que se usará para escribir el contenido de la respuesta en un archivo. La propiedad Encoding del objeto de respuesta se usa para establecer la codificación para el archivo.
Los comandos finales escriben la propiedad Content en el archivo y, a continuación, eliminan StreamWriter.
Tenga en cuenta que la propiedad Encoding es null si la solicitud web no devuelve contenido de texto.
Ejemplo 5: Enviar un archivo de datos de varias partes o formularios
En este ejemplo se usa el Invoke-WebRequest
cmdlet para cargar un archivo como envío multipart/form-data
. El archivo c:\document.txt
se envía como campo document
de formulario con el 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'
Ejemplo 6: Envío simplificado de varios elementos o datos de formulario
Algunas API requieren multipart/form-data
envíos para cargar archivos y contenido mixto. En este ejemplo se muestra cómo actualizar un perfil de usuario.
$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
El formulario de perfil requiere estos campos: firstName
, lastName
, email
, avatar
, birthday
y hobbies
. La API espera que se proporcione una imagen para la imagen de perfil de usuario en el avatar
campo . La API también acepta varias hobbies
entradas que se enviarán con el mismo formato.
Al crear hashTable $Form
, los nombres de clave se usan como nombres de campo de formulario. De forma predeterminada, los valores de HashTable se convierten en cadenas. Si hay un valor System.IO.FileInfo , se envía el contenido del archivo. Si hay una colección como matrices o listas, el campo de formulario se envía varias veces.
Con Get-Item
en la avatar
clave, el FileInfo
objeto se establece como valor. El resultado es que se envían los datos de imagen de jdoe.png
.
Al proporcionar una lista a la hobbies
clave, el hobbies
campo está presente en los envíos una vez para cada elemento de lista.
Ejemplo 7: Detectar mensajes no correctos de Invoke-WebRequest
Cuando Invoke-WebRequest
encuentra un mensaje HTTP no correcto (404, 500, etc.), no devuelve ninguna salida y genera un error de terminación. Para detectar el error y ver statusCode , puede incluir la ejecución en un try/catch
bloque.
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
El bloque detecta el catch
error de terminación, que recupera statusCode del objeto Exception .
Ejemplo 8: Descargar varios archivos al mismo tiempo
El Invoke-WebRequest
cmdlet solo puede descargar un archivo cada vez. En el ejemplo siguiente se usa Start-ThreadJob
para crear varios trabajos de subproceso para descargar varios archivos al mismo tiempo.
$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
}
Ejemplo 9: Omitir validación de encabezados
De forma predeterminada, el Invoke-WebRequest
cmdlet valida los valores de los encabezados conocidos que tienen un formato de valor definido por estándares. En el ejemplo siguiente se muestra cómo esta validación puede generar un error y cómo puede usar el parámetro SkipHeaderValidation para evitar validar los valores de los puntos de conexión que toleran valores con formato no válido.
$Uri = 'https://httpbin.org/headers'
$InvalidHeaders = @{
'If-Match' = '12345'
}
Invoke-WebRequest -Uri $Uri -Headers $InvalidHeaders
Invoke-WebRequest -Uri $Uri -Headers $InvalidHeaders -SkipHeaderValidation
Invoke-WebRequest: The format of value '12345' is invalid.
StatusCode : 200
StatusDescription : OK
Content : {
"headers": {
"Host": "httpbin.org",
"If-Match": "12345",
"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.19044; en-US) PowerShell/7.2.5",
"X-Amzn-Trace-Id": �
RawContent : HTTP/1.1 200 OK
Date: Mon, 08 Aug 2022 16:24:24 GMT
Connection: keep-alive
Server: gunicorn/19.9.0
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
Content-Type: application�
Headers : {[Date, System.String[]], [Connection, System.String[]], [Server, System.String[]], [Access-Control-Allow-Origin, System.String[]]�}
Images : {}
InputFields : {}
Links : {}
RawContentLength : 249
RelationLink : {}
httpbin.org es un servicio que devuelve información sobre las solicitudes web y las respuestas para solucionar problemas. La $Uri
variable se asigna al /headers
punto de conexión del servicio, que devuelve los encabezados de una solicitud como contenido en su respuesta.
El If-Match
encabezado de solicitud se define en la sección 3.1 de RFC-7232 y requiere que el valor de ese encabezado se defina con comillas circundantes. A la $InvalidHeaders
variable se le asigna una tabla hash donde el valor de If-Match
no es válido porque se define como 12345
en lugar de "12345"
.
Al llamar Invoke-WebRequest
con los encabezados no válidos, se devuelve un error que informa de que el valor con formato no es válido. La solicitud no se envía al punto de conexión.
Al llamar Invoke-WebRequest
con el parámetro SkipHeaderValidation , se omite el error de validación y se envía la solicitud al punto de conexión. Dado que el punto de conexión tolera valores de encabezado no compatibles, el cmdlet devuelve el objeto de respuesta sin errores.
Ejemplo 10: Envío de una solicitud mediante HTTP 2.0
En este ejemplo se obtienen los vínculos de una página web mediante el protocolo HTTP 2.0. Usa el Invoke-WebRequest
cmdlet para obtener el contenido de la página web. A continuación, usa la propiedad Links del BasicHtmlWebResponseObject que Invoke-WebRequest
devuelve y la propiedad Href de cada vínculo.
(Invoke-WebRequest -Uri 'https://aka.ms/pscore6-docs' -HttpVersion 2.0).Links.Href
Parámetros
-AllowUnencryptedAuthentication
Permite el envío de credenciales y secretos a través de conexiones sin cifrar. De forma predeterminada, proporcionar credenciales o cualquier opción de autenticación con un URI que no comience con https://
da como resultado un error y la solicitud se anula para evitar la comunicación involuntaria de secretos en texto sin formato a través de conexiones sin cifrar. Para invalidar este comportamiento en su propio riesgo, proporcione el parámetro AllowUnencryptedAuthentication .
Advertencia
El uso de este parámetro no es seguro y no se recomienda. Solo se proporciona por compatibilidad con sistemas heredados que no pueden proporcionar conexiones cifradas. Úselo en su propio riesgo.
Esta característica se agregó en PowerShell 6.0.0.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Authentication
Especifica el tipo de autenticación explícito que se va a usar para la solicitud. El valor predeterminado es None (Ninguno). El parámetro Authentication no se puede usar con el parámetro UseDefaultCredentials .
Opciones de autenticación disponibles:
None
: esta es la opción predeterminada cuando no se proporciona la autenticación . No se usa ninguna autenticación explícita.Basic
: requiere credencial. Las credenciales se envían como un encabezado de autenticaciónAuthorization: Basic
básica RFC 7617 con el formato .base64(user:password)
Bearer
: requiere el parámetro Token . Envía un encabezado RFC 6750Authorization: Bearer
con el token proporcionado.OAuth
: requiere el parámetro Token . Envía un encabezado RFC 6750Authorization: Bearer
con el token proporcionado.
El suministro de autenticación invalida los Authorization
encabezados proporcionados a los encabezados o incluidos en WebSession.
Esta característica se agregó en 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 el cuerpo de la solicitud. El cuerpo es el contenido de la solicitud que sigue a los encabezados.
También puede canalizar un valor de cuerpo a Invoke-WebRequest
.
El parámetro Body se puede utilizar para especificar una lista de parámetros de consulta o el contenido de la respuesta.
Cuando la entrada es una solicitud POST y el cuerpo es string, el valor situado a la izquierda del primer signo igual (=
) se establece como una clave en los datos del formulario y el texto restante se establece como valor. Para especificar varias claves, use un objeto IDictionary, como una tabla hash, para body.
Cuando la entrada es una solicitud GET y el cuerpo es un IDictionary (normalmente, una tabla hash), el cuerpo se agrega al URI como parámetros de consulta. Para otros tipos de solicitud (como PATCH), el cuerpo se establece como el valor del cuerpo de la solicitud en el formato estándar name=value
con los valores codificados por url.
Cuando la entrada es un System.Xml. El objeto XmlNode y la declaración XML especifican una codificación, que la codificación se usa para los datos de la solicitud a menos que se invalide mediante el parámetro ContentType .
El parámetro Body también acepta un System.Net.Http.MultipartFormDataContent
objeto . Esto facilita las multipart/form-data
solicitudes. Cuando se proporciona un objeto MultipartFormDataContent para Body, los encabezados relacionados con el contenido proporcionados a los parámetros ContentType, Headers o WebSession se invalidan mediante los encabezados Content del objeto MultipartFormDataContent . Esta característica se agregó en PowerShell 6.0.0.
Type: | Object |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-Certificate
Especifica el certificado de cliente que se usa para una solicitud web segura. Introduzca una variable que contenga un certificado o un comando o una expresión que obtenga el certificado.
Para buscar un certificado, use o use Get-PfxCertificate
el Get-ChildItem
cmdlet en la unidad Certificado (Cert:
). Si el certificado no es válido o no tiene suficiente autoridad, se produce un error en el comando.
Type: | X509Certificate |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CertificateThumbprint
Especifica el certificado de clave pública digital (X509) de una cuenta de usuario que tiene permiso para realizar esta acción. Escriba la huella digital del certificado.
Los certificados se usan para la autenticación basada en certificados de cliente. Los certificados solo se pueden asignar a cuentas de usuario locales, no a cuentas de dominio.
Para ver la huella digital del certificado, use el Get-Item
comando o Get-ChildItem
para buscar el certificado en Cert:\CurrentUser\My
.
Nota
Esta característica solo se admite en plataformas del sistema operativo Windows.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ContentType
Especifica el tipo de contenido de la solicitud web.
Si el valor de ContentType contiene el formato de codificación (como charset
), el cmdlet usa ese formato para codificar el cuerpo de la solicitud web. Si ContentType no especifica un formato de codificación, se usa en su lugar el formato de codificación predeterminado. Un ejemplo de contentType con un formato de codificación es text/plain; charset=iso-8859-5
, que especifica el alfabeto latino/cirílico .
Si se omite este parámetro y el método de solicitud es POST, Invoke-WebRequest
establece el tipo application/x-www-form-urlencoded
de contenido en . De lo contrario, el tipo de contenido no se especifica en la llamada.
ContentType se invalida cuando se proporciona un objeto MultipartFormDataContent para Body.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Credential
Especifica una cuenta de usuario que tiene permisos para enviar la solicitud. El valor predeterminado es el usuario actual.
Escriba un nombre de usuario, como User01 o Domain01\User01, o escriba un objeto PSCredential generado por el Get-Credential
cmdlet .
Las credenciales se pueden usar por sí solas o junto con determinadas opciones de parámetro de autenticación . Cuando se usa solo, solo proporciona credenciales al servidor remoto si el servidor remoto envía una solicitud de desafío de autenticación. Cuando se usa con las opciones de autenticación , las credenciales se envían explícitamente.
Las credenciales se almacenan en un objeto PSCredential y la contraseña se almacena como secureString.
Nota
Para obtener más información sobre la protección de datos SecureString , consulte ¿Cómo es SecureString?.
Type: | PSCredential |
Position: | Named |
Default value: | Current user |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CustomMethod
Especifica un método personalizado que se usa para la solicitud web. Esto se puede usar si el método de solicitud requerido por el punto de conexión no es una opción disponible en el método . El método y CustomMethod no se pueden usar juntos.
En este ejemplo se realiza una TEST
solicitud HTTP a la API:
Invoke-WebRequest -uri 'https://api.contoso.com/widget/' -CustomMethod 'TEST'
Esta característica se agregó en 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 el cmdlet establece el valor KeepAlive en el encabezado HTTP en False. De forma predeterminada, KeepAlive es True. KeepAliveestablece una conexión persistente con el servidor para facilitar las solicitudes posteriores.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Form
Convierte un diccionario en un multipart/form-data
envío. Puede que el formulario no se use con Body.
Si se usa ContentType , se omite.
Las claves del diccionario se usan como nombres de campo de formulario. De forma predeterminada, los valores de formulario se convierten en valores de cadena.
Si el valor es un objeto System.IO.FileInfo , se envía el contenido del archivo binario. El nombre del archivo se envía como la propiedad filename . El tipo MIME se establece como application/octet-stream
. Get-Item
se puede usar para simplificar el suministro del objeto System.IO.FileInfo .
$Form = @{ resume = Get-Item 'c:\Users\jdoe\Documents\John Doe.pdf' }
Si el valor es un tipo de colección, tales matrices o Listas, el campo for se envía varias veces. Los valores de la lista se tratan como cadenas de forma predeterminada. Si el valor es un objeto System.IO.FileInfo , se envía el contenido del archivo binario. No se admiten colecciones anidadas.
$Form = @{ tags = 'Vacation', 'Italy', '2017' pictures = Get-ChildItem 'c:\Users\jdoe\Pictures\2017-Italy' }
En el ejemplo anterior, el tags
campo se proporciona tres veces en el formulario, una vez para cada uno de Vacation
, Italy
y 2017
. El pictures
campo también se envía una vez para cada archivo de la 2017-Italy
carpeta. El contenido binario de los archivos de esa carpeta se envían como valores.
Esta característica se agregó en PowerShell 6.1.0.
Type: | IDictionary |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Headers
Especifica los encabezados de la solicitud web. Especifique una tabla hash o un diccionario.
Los encabezados relacionados con el contenido, como Content-Type
, se invalidan cuando se proporciona un objeto MultipartFormDataContent para Body.
Type: | IDictionary |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-HttpVersion
Especifica la versión HTTP usada para la solicitud. El valor predeterminado es 1.1
.
Los valores válidos son:
- 1.0
- 1.1
- 2.0
- 3.0
Type: | Version |
Position: | Named |
Default value: | 1.1 |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-InFile
Obtiene el contenido de la solicitud web de un archivo. Escriba una ruta de acceso y un nombre de archivo. Si omite la ruta de acceso, el valor predeterminado es la ubicación actual.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumRedirection
Especifica cuántas veces PowerShell redirige una conexión a un identificador uniforme de recursos (URI) alternativo antes de que se produzca un error en la conexión. El valor predeterminado es 5. Un valor 0 (cero) evita cualquier redirección.
Type: | Int32 |
Position: | Named |
Default value: | 5 |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumRetryCount
Especifica cuántas veces PowerShell reintenta una conexión cuando se recibe un código de error entre 400 y 599, ambos incluidos o 304. Consulte también el parámetro RetryIntervalSec para especificar el número de reintentos.
Type: | Int32 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Method
Especifica el método utilizado para la solicitud web. Los valores permitidos para este parámetro son los siguientes:
Default
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace
El parámetro CustomMethod se puede usar para los métodos de solicitud no enumerados anteriormente.
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 el cmdlet no debe usar un proxy para llegar al destino. Cuando necesite omitir el proxy configurado en el entorno, use este modificador. Esta característica se agregó en PowerShell 6.0.0.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-OutFile
Especifica el archivo de salida para el que este cmdlet guarda el cuerpo de la respuesta. Escriba una ruta de acceso y un nombre de archivo.
Si omite la ruta de acceso, el valor predeterminado es la ubicación actual. El nombre se trata como una ruta de acceso literal.
Los nombres que contienen corchetes ([]
) deben incluirse entre comillas simples ('
).
De forma predeterminada, Invoke-WebRequest
devuelve los resultados a la canalización. Para enviar los resultados a un archivo y a la canalización, utilice el parámetro Passthru.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-PassThru
Indica que el cmdlet devuelve los resultados, además de escribirlos en un archivo. Este parámetro solo es válido cuando también se usa el parámetro OutFile en el comando.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-PreserveAuthorizationOnRedirect
Indica que el cmdlet debe conservar el Authorization
encabezado, cuando está presente, entre redireccionamientos.
De forma predeterminada, el cmdlet quita el Authorization
encabezado antes de redirigir. Al especificar este parámetro, se deshabilita esta lógica en los casos en los que se debe enviar el encabezado a la ubicación de redireccionamiento.
Esta característica se agregó en PowerShell 6.0.0.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Proxy
Especifica un servidor proxy para la solicitud, en lugar de conectarse directamente al recurso de Internet. Especifique el URI de un servidor proxy de red.
Type: | Uri |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ProxyCredential
Especifica una cuenta de usuario que tiene permiso para usar el servidor proxy especificado por el parámetro Proxy . El valor predeterminado es el usuario actual.
Escriba un nombre de usuario, como User01
o Domain01\User01
, o escriba un objeto PSCredential , como uno generado por el Get-Credential
cmdlet .
Este parámetro solo es válido cuando el parámetro Proxy también se usa en el comando . No puede usar los parámetros ProxyCredential y ProxyUseDefaultCredentials en el mismo comando.
Type: | PSCredential |
Position: | Named |
Default value: | Current user |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ProxyUseDefaultCredentials
Indica que el cmdlet usa las credenciales del usuario actual para acceder al servidor proxy especificado por el parámetro Proxy .
Este parámetro solo es válido cuando el parámetro Proxy también se usa en el comando . No puede usar los parámetros ProxyCredential y ProxyUseDefaultCredentials en el mismo comando.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Resume
Realiza un mejor intento de reanudar la descarga de un archivo parcial. Reanudar requiere OutFile.
Resume solo funciona en el tamaño del archivo local y el archivo remoto y no realiza ninguna otra validación de que el archivo local y el archivo remoto sean los mismos.
Si el tamaño del archivo local es menor que el tamaño del archivo remoto, el cmdlet intenta reanudar la descarga del archivo y anexa los bytes restantes al final del archivo.
Si el tamaño del archivo local es el mismo que el tamaño del archivo remoto, no se realiza ninguna acción y el cmdlet supone que la descarga ya se ha completado.
Si el tamaño del archivo local es mayor que el tamaño del archivo remoto, se sobrescribe el archivo local y se vuelve a descargar todo el archivo remoto. Este comportamiento es el mismo que el uso de OutFile sin Resume.
Si el servidor remoto no admite la reanudación de descargas, se sobrescribe el archivo local y se vuelve a descargar todo el archivo remoto. Este comportamiento es el mismo que el uso de OutFile sin Resume.
Si el archivo local no existe, se crea el archivo local y se descarga todo el archivo remoto. Este comportamiento es el mismo que el uso de OutFile sin Resume.
Esta característica se agregó en PowerShell 6.1.0.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-RetryIntervalSec
Especifica el intervalo entre reintentos para la conexión cuando se recibe un código de error entre 400 y 599, ambos incluidos o 304. Consulte también el parámetro MaximumRetryCount para especificar el número de reintentos. El valor debe estar entre 1
y [int]::MaxValue
.
Type: | Int32 |
Position: | Named |
Default value: | 5 |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SessionVariable
Especifica una variable para la que este cmdlet crea una sesión de solicitud web y la guarda en el valor .
Escriba un nombre de variable sin el símbolo de signo de dólar ($
).
Al especificar una variable de sesión, Invoke-WebRequest
crea un objeto de sesión de solicitud web y lo asigna a una variable con el nombre especificado en la sesión de PowerShell. Puede usar la variable en la sesión en cuanto finalice la ejecución del comando.
Antes de PowerShell 7.4, la sesión de solicitud web no es una conexión persistente. Es un objeto que contiene información sobre la conexión y la solicitud, incluidas las cookies, las credenciales, el valor de redireccionamiento máximo y la cadena del agente de usuario. Puede usarlo para compartir el estado y los datos entre las solicitudes web.
A partir de PowerShell 7.4, la sesión de solicitud web es persistente siempre y cuando las propiedades de la sesión no se invalidan en una solicitud posterior. Cuando son, el cmdlet vuelve a crear la sesión con los nuevos valores. Las sesiones persistentes reducen la sobrecarga de las solicitudes repetidas, lo que las hace mucho más rápidas.
Para utilizar la sesión de solicitud web en solicitudes web posteriores, especifique la variable de sesión en el valor del parámetro WebSession. PowerShell usa los datos del objeto de sesión de solicitud web al establecer la nueva conexión. Para reemplazar un valor en la sesión de solicitud web, utilice un parámetro de cmdlet, como UserAgent o Credential. Los valores de parámetro tienen prioridad sobre los valores de la sesión de solicitud web.
No puede usar los parámetros SessionVariable y WebSession en el mismo comando.
Type: | String |
Aliases: | SV |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SkipCertificateCheck
Omite las comprobaciones de validación de certificados. Esto incluye todas las validaciones, como expiración, revocación, autoridad raíz de confianza, etc.
Advertencia
El uso de este parámetro no es seguro y no se recomienda. Este modificador solo está pensado para usarse en hosts conocidos mediante un certificado autofirmado con fines de prueba. Úselo en su propio riesgo.
Esta característica se agregó en PowerShell 6.0.0.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SkipHeaderValidation
Indica que el cmdlet debe agregar encabezados a la solicitud sin validación.
Este modificador debe usarse para sitios que requieran valores de encabezado que no cumplan los estándares. Al especificar este modificador, se deshabilita la validación para permitir que el valor se pase sin activar. Cuando se especifica, se agregan todos los encabezados sin validación.
Este modificador deshabilita la validación de los valores pasados a los parámetrosContentType, Headers y UserAgent.
Esta característica se agregó en PowerShell 6.0.0.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SkipHttpErrorCheck
Este parámetro hace que el cmdlet omita los estados de error HTTP y continúe procesando las respuestas. Las respuestas de error se escriben en la canalización como si fueran correctas.
Este parámetro se introdujo en PowerShell 7.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SslProtocol
Establece los protocolos SSL/TLS permitidos para la solicitud web. De forma predeterminada, se permiten los protocolos SSL/TLS admitidos por el sistema. SslProtocol permite limitar a protocolos específicos con fines de cumplimiento.
Estos valores se definen como una enumeración basada en marcas. Puede combinar varios valores para establecer varias marcas mediante este parámetro. Los valores se pueden pasar al parámetro SslProtocol como una matriz de valores o como una cadena separada por comas de esos valores. El cmdlet combina los valores mediante una operación binary-OR. Pasar valores como una matriz es la opción más sencilla y también permite usar la finalización de tabulación en los valores. Es posible que no pueda definir varias opciones en todas las plataformas.
Nota
En plataformas que no son windows, es posible que no sea posible proporcionar Tls
o Tls12
como opción. Tls13
La compatibilidad con no está disponible en todos los sistemas operativos y deberá comprobarse por sistema operativo.
Esta característica se agregó en PowerShell 6.0.0 y se agregó compatibilidad con Tls13
en 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 cuánto tiempo puede estar pendiente la solicitud antes de que se agote el tiempo de espera. Escriba un valor en segundos. El valor predeterminado, 0, especifica un tiempo de espera indefinido.
Una consulta del Sistema de nombres de dominio (DNS) puede tardar hasta 15 segundos en devolver o agotar el tiempo de espera. Si la solicitud contiene un nombre de host que requiere resolución y establece TimeoutSec en un valor mayor que cero, pero menos de 15 segundos, puede tardar 15 segundos o más antes de que se inicie una excepción WebException y la solicitud agote el tiempo de espera.
Type: | Int32 |
Position: | Named |
Default value: | 0 |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Token
Token de OAuth o Portador que se va a incluir en la solicitud. El token es necesario para determinadas opciones de autenticación . No se puede usar de forma independiente.
El token toma un SecureString
objeto que contiene el token. Para proporcionar el token manualmente, use lo siguiente:
Invoke-WebRequest -Uri $uri -Authentication OAuth -Token (Read-Host -AsSecureString)
Este parámetro se introdujo en PowerShell 6.0.
Type: | SecureString |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-TransferEncoding
Especifica un valor para el encabezado de respuesta HTTP de codificación de transferencia. Los valores permitidos para este parámetro son los siguientes:
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 el identificador uniforme de recursos (URI) del recurso de Internet al que se envía la solicitud web. Especifique un identificador URI. Este parámetro solo admite HTTP o HTTPS.
Este parámetro es obligatorio. El URI del nombre del parámetro es opcional.
Type: | Uri |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UseBasicParsing
Este parámetro ha quedado en desuso. A partir de PowerShell 6.0.0, todas las solicitudes web solo usan el análisis básico. Este parámetro solo se incluye para la compatibilidad con versiones anteriores y cualquier uso de este no tiene ningún efecto en el funcionamiento del cmdlet.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UseDefaultCredentials
Indica que el cmdlet usa las credenciales del usuario actual para enviar la solicitud web. No se puede usar con autenticación o credencial y es posible que no se admita en todas las plataformas.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UserAgent
Especifica una cadena de agente de usuario para la solicitud web.
El agente de usuario predeterminado es similar a Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0
con ligeras variaciones para cada sistema operativo y plataforma.
Para probar un sitio web con la cadena de agente de usuario estándar que usa la mayoría de los exploradores de Internet, use las propiedades de la clase PSUserAgent , como Chrome, FireFox, InternetExplorer, Opera y Safari.
Por ejemplo, el siguiente comando usa la cadena del agente de usuario para 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 una sesión de solicitud web. Escriba el nombre de la variable, incluido el signo de dólar ($
).
Para reemplazar un valor en la sesión de solicitud web, utilice un parámetro de cmdlet, como UserAgent o Credential. Los valores de parámetro tienen prioridad sobre los valores de la sesión de solicitud web. Los encabezados relacionados con el contenido, como Content-Type
, también se invalidan cuando se proporciona un objeto MultipartFormDataContent para Body.
A diferencia de una sesión remota, la sesión de solicitud web no es una conexión persistente. Es un objeto que contiene información sobre la conexión y la solicitud, incluidas las cookies, las credenciales, el valor de redireccionamiento máximo y la cadena del agente de usuario. Puede usarlo para compartir el estado y los datos entre las solicitudes web.
Para crear una sesión de solicitud web, escriba un nombre de variable, sin un signo de dólar, en el valor del parámetro SessionVariable de un Invoke-WebRequest
comando. Invoke-WebRequest
crea la sesión y la guarda en la variable . En los siguientes comandos, utilice la variable como valor del parámetro WebSession.
No puede usar los parámetros SessionVariable y WebSession en el mismo comando.
Type: | WebRequestSession |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Entradas
Puede canalizar el cuerpo de una solicitud web a este cmdlet.
Salidas
Este cmdlet devuelve el objeto de respuesta que representa el resultado de la solicitud web.
Notas
PowerShell incluye los siguientes alias para Invoke-WebRequest
:
- Todas las plataformas:
iwr
A partir de PowerShell 6.0.0 solo Invoke-WebRequest
admite el análisis básico.
Para obtener más información, vea BasicHtmlWebResponseObject.
Debido a los cambios en .NET Core 3.1, PowerShell 7.0 y versiones posteriores usan la propiedad HttpClient.DefaultProxy para determinar la configuración del proxy.
El valor de esta propiedad viene determinado por la plataforma:
- Para Windows: lee la configuración del proxy de las variables de entorno. Si esas variables no están definidas, la propiedad se deriva de la configuración de proxy del usuario.
- Para macOS: lee la configuración del proxy de las variables de entorno. Si esas variables no están definidas, la propiedad se deriva de la configuración del proxy del sistema.
- Para Linux: lee la configuración del proxy de las variables de entorno. Si esas variables no están definidas, la propiedad inicializa una instancia no configurada que omite todas las direcciones.
Las variables de entorno que se usan para la inicialización de DefaultProxy
en plataformas basadas en Windows y Unix son las siguientes:
HTTP_PROXY
: el nombre de host o la dirección IP del servidor proxy utilizado en las solicitudes HTTP.HTTPS_PROXY
: el nombre de host o la dirección IP del servidor proxy utilizado en las solicitudes HTTPS.ALL_PROXY
: el nombre de host o la dirección IP del servidor proxy utilizado en las solicitudes HTTP y HTTPS en casoHTTP_PROXY
deHTTPS_PROXY
que no se definan.NO_PROXY
: una lista separada por comas de nombres de host que se deben excluir del proxy.