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. Este es 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 5280El primer comando emite la solicitud y guarda la respuesta en la $Response variable .
El segundo comando obtiene cualquier inputField donde la propiedad Name es 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 $SessionLa 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 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 de BasicHtmlWebResponseObject que Invoke-WebRequest devuelve y la propiedad Href de cada vínculo.
(Invoke-WebRequest -Uri "https://aka.ms/pscore6-docs").Links.HrefEjemplo 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 datos de varias partes o formularios
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 $FormEl formulario de perfil requiere estos campos: firstName, lastName, email, avatar, birthdayy hobbies. La API espera que se proporcione una imagen de la imagen de perfil de usuario en el avatar campo . La API también acepta varias hobbies entradas que se enviarán en el mismo formulario.
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 existe 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 la imagen.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 produce 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
404El 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 a la 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 la validación de encabezados
De forma predeterminada, el Invoke-WebRequest cmdlet valida los valores de 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 $InvalidHeaders la 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 error.
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 de 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.HrefPará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. Use 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 autenticación . No se usa ninguna autenticación explícita.Basic: requiere credencial. Las credenciales se envían como un encabezado de autenticaciónAuthorization: Basicbásica RFC 7617 en el formato debase64(user:password).Bearer: requiere el parámetro Token . Envía un encabezado RFC 6750Authorization: Bearercon el token proporcionado.OAuth: requiere el parámetro Token . Envía un encabezado RFC 6750Authorization: Bearercon el token proporcionado.
Proporcionar 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 usar para especificar una lista de parámetros de consulta o especificar el contenido de la respuesta.
Cuando la entrada es una solicitud POST y el cuerpo es string, el valor a la izquierda del primer signo igual (=) se establece como una clave en los datos del formulario y el texto restante se establece como el 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 objeto System.Xml.XmlNode y la declaración XML especifica una codificación, esa codificación se usa para los datos de la solicitud a menos que el parámetro ContentType lo invalide.
El parámetro Body también acepta un System.Net.Http.MultipartFormDataContent objeto . Esto facilita multipart/form-data las solicitudes. Cuando se proporciona un objeto MultipartFormDataContent para Body, los encabezados relacionados con content 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 Get-PfxCertificate o use 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-urlencodedde 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 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 secure is 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 usado 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. KeepAlive establece 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. El formulario no se puede usar 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, Italyy 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:
DefaultDeleteGetHeadMergeOptionsPatchPostPutTrace
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, use 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 el parámetro OutFile también se usa 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 redirecciones.
De forma predeterminada, el cmdlet quita el Authorization encabezado antes de redirigirlo. Al especificar este parámetro, se deshabilita esta lógica para los casos en los que el encabezado debe enviarse 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, el archivo local se sobrescribe 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 la descarga, 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 que 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 usar 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 invalidar un valor en la sesión de solicitud web, use 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. Use 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ámetros ContentType, 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 ignore 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 de Windows, es posible que no sea posible proporcionar Tls o Tls12 como opción. La compatibilidad con Tls13 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 devolverse 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 produzca 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:
ChunkedCompressDeflateGZipIdentity
| 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 de nombre de 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 se incluye solo para la compatibilidad con versiones anteriores y cualquier uso de él 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. Esto 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 comando siguiente 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 invalidar un valor en la sesión de solicitud web, use 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 reemplazan 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 comandos posteriores, use 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 Invoke-WebRequest solo 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 de proxy de las variables de entorno. Si esas variables no están definidas, la propiedad se deriva de la configuración del proxy del usuario.
- Para macOS: lee la configuración de 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 que se usa en las solicitudes HTTPS.ALL_PROXY: el nombre de host o la dirección IP del servidor proxy que se usa en las solicitudes HTTP y HTTPS en casoHTTP_PROXYHTTPS_PROXYde que no se definan.NO_PROXY: una lista separada por comas de nombres de host que se deben excluir del proxy.
Vínculos relacionados
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de