Invoke-WebRequest

Referencia

Módulo:: Microsoft.PowerShell.Utility

Obtiene el contenido de una página web de Internet.

Syntax

Invoke-WebRequest
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-Method <WebRequestMethod>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [<CommonParameters>]

Description

El Invoke-WebRequest cmdlet envía solicitudes HTTP, HTTPS, FTP y FILE a una página web o servicio web. Analiza la respuesta y devuelve colecciones de formularios, vínculos, imágenes y otros elementos HTML importantes.

Este cmdlet se introdujo en Windows PowerShell 3.0.

Nota

De forma predeterminada, el código de script de la página web se puede ejecutar cuando se analiza la página para rellenar la ParsedHtml propiedad. Use el -UseBasicParsing modificador para suprimirlo.

Ejemplos

Ejemplo 1: Envío de una solicitud web

Este comando usa el Invoke-WebRequest cmdlet para enviar una solicitud web al sitio Bing.com.

$R = Invoke-WebRequest -URI https://www.bing.com?q=how+many+feet+in+a+mile
$R.AllElements | Where-Object {
    $_.name -like "* Value" -and $_.tagName -eq "INPUT"
} | Select-Object Name, Value

name       value
----       -----
From Value 1
To Value   5280

El primer comando emite la solicitud y guarda la respuesta en la $R variable .

El segundo comando filtra los objetos de la propiedad AllElements donde la propiedad name es como "* Value" y tagName es "INPUT". Los resultados filtrados se canalizan para Select-Object seleccionar las propiedades de 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, como Facebook.

$R = Invoke-WebRequest https://www.facebook.com/login.php -SessionVariable fb
# This command stores the first form in the Forms property of the $R variable in the $Form variable.
$Form = $R.Forms[0]
# This command shows the fields available in the Form.
$Form.fields

Key                     Value
---                     -----
...
email
pass
...

# These commands populate the username and password of the respective Form fields.
$Form.Fields["email"]="User01@Fabrikam.com"
$Form.Fields["pass"]="P@ssw0rd"
# This command creates the Uri that will be used to log in to facebook.
# The value of the Uri parameter is the value of the Action property of the form.
$Uri = "https://www.facebook.com" + $Form.Action
# Now the Invoke-WebRequest cmdlet is used to sign into the Facebook web service.
# The WebRequestSession object in the $FB variable is passed as the value of the WebSession parameter.
# The value of the Body parameter is the hash table in the Fields property of the form.
# The value of the *Method* parameter is POST. The command saves the output in the $R variable.
$R = Invoke-WebRequest -Uri $Uri -WebSession $FB -Method POST -Body $Form.Fields
$R.StatusDescription

El primer comando usa el Invoke-WebRequest cmdlet para enviar una solicitud de inicio de sesión. El comando especifica un valor de "FB" para el valor del parámetro SessionVariable y guarda el resultado en la $R variable . Cuando se completa el comando, la $R variable contiene htmlWebResponseObject y la $FB variable contiene un objeto WebRequestSession .

Una vez que el Invoke-WebRequest cmdlet inicia sesión en Facebook, la propiedad StatusDescription del objeto de respuesta web en la $R variable indica que el usuario ha iniciado sesión correctamente.

Ejemplo 3: Obtener vínculos de una página web

Este comando obtiene los vínculos en una página web.

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

El Invoke-WebRequest cmdlet obtiene el contenido de la página web. A continuación, la propiedad Links del HtmlWebResponseObject devuelto se usa para mostrar la propiedad Href de cada vínculo.

Ejemplo 4: Detectar mensajes no correctos de Invoke-WebRequest

Cuando Invoke-WebRequest encuentra un mensaje HTTP no correcto (404, 500, etc.), no devuelve ningún resultado y produce un error de terminación. Para detectar el error y ver statusCode , puede incluir la ejecución en un try/catch bloque . En el ejemplo siguiente se muestra cómo hacerlo.

try
{
    $response = Invoke-WebRequest -Uri "www.microsoft.com/unkownhost" -ErrorAction Stop
    # This will only execute if the Invoke-WebRequest is successful.
    $StatusCode = $Response.StatusCode
}
catch
{
    $StatusCode = $_.Exception.Response.StatusCode.value__
}
$StatusCode

404

El primer comando llama Invoke-WebRequest a con un error ErrorAction de Stop, que obliga Invoke-WebRequest a producir un error de terminación en las solicitudes con errores. El bloque detecta el catch error de terminación que recupera statusCode del objeto Exception .

Parámetros

-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 GET y el cuerpo es un IDictionary (normalmente, una tabla hash), el cuerpo se agrega al URI como parámetros de consulta. Para otras solicitudes GET, el cuerpo se establece como el valor del cuerpo de la solicitud en el formato estándar name=value .

Cuando el cuerpo es un formulario o es la salida de una Invoke-WebRequest llamada, PowerShell establece el contenido de la solicitud en los campos del formulario. Por ejemplo:

$r = Invoke-WebRequest https://website.com/login.aspx $r.Forms\[0\].Name = "MyName" $r.Forms\[0\].Password = "MyPassword" Invoke-RestMethod https://website.com/service.aspx -Body $r

Invoke-RestMethod https://website.com/service.aspx -Body $r.Forms\[0\]

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

-Certificate

Especifica 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 autoridad suficiente, el comando genera un error.

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 en la autenticación basada en certificados de cliente. Solo se pueden asignar a cuentas de usuario locales y no funcionan con cuentas de dominio.

Para obtener una huella digital de certificado, use el Get-Item comando o Get-ChildItem en la unidad de PowerShell Cert: .

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 se omite este parámetro y el método de solicitud es POST, Invoke-WebRequest establece el tipo de contenido en application/x-www-form-urlencoded. De lo contrario, el tipo de contenido no se especifica en la llamada.

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 , como uno generado por el Get-Credential cmdlet .

Type:	PSCredential
Position:	Named
Default value:	Current user
Required:	False
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:	KeepAlive
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.

Para establecer encabezados UserAgent , use el parámetro UserAgent . No puede usar este parámetro para especificar encabezados UserAgent o cookie.

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

-InFile

Obtiene el contenido de la solicitud web de un archivo.

Especifique 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

-Method

Especifica el método utilizado para la solicitud web. Los valores permitidos para este parámetro son los siguientes:

Default
Eliminar
Obtener
Head
Fusionar mediante combinación
Opciones
Revisión
Publicar
Put
Seguimiento

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

-OutFile

Especifica el archivo de salida para el que este cmdlet guarda el cuerpo de la respuesta. Especifique una ruta de acceso y un nombre de archivo. Si omite la ruta de acceso, el valor predeterminado es la ubicación actual.

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

-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 tener acceso 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:	None
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.

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 máximo de redireccionamiento y la cadena de agente de usuario. Puede usarlo para compartir el estado y los datos entre las solicitudes web.

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 se pueden 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

-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 agotarse 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 se agote el tiempo de espera de la solicitud.

Type:	Int32
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:

Fragmentado
Comprimir
Deflate
GZip
Identidad

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 admite valores HTTP, HTTPS, FTP y FILE.

Este parámetro es obligatorio.

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

-UseBasicParsing

Indica que el cmdlet usa el objeto de respuesta para el contenido HTML sin el análisis del Modelo de objetos de documento (DOM). Este parámetro es necesario cuando Internet Explorer no está instalado en los equipos, como en una instalación Server Core del sistema operativo Windows Server.

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

-UseDefaultCredentials

Indica que el cmdet usa las credenciales del usuario actual para enviar la solicitud web.

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; Windows NT 6.1; en-US) WindowsPowerShell/3.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.

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.

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 se pueden 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

Object

Puede canalizar el cuerpo de una solicitud web a Invoke-WebRequest.

Salidas

HtmlWebResponseObject

Compartir a través de

Invoke-WebRequest

Syntax

Description

Ejemplos

Ejemplo 1: Envío de una solicitud web

Ejemplo 2: Uso de un servicio web con estado

Ejemplo 3: Obtener vínculos de una página web

Ejemplo 4: Detectar mensajes no correctos de Invoke-WebRequest

Parámetros

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

Entradas

Salidas

Recursos adicionales

Compartir a través de

Invoke-WebRequest

Syntax

Description

Ejemplos

Ejemplo 1: Envío de una solicitud web

Ejemplo 2: Uso de un servicio web con estado

Ejemplo 3: Obtener vínculos de una página web

Ejemplo 4: Detectar mensajes no correctos de Invoke-WebRequest

Parámetros

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

Entradas

Salidas

Vínculos relacionados

Recursos adicionales