Invoke-RestMethod

Sintaxis

Default (valor predeterminado)

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

Description

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 enviar un valor de cuerpo a Invoke-RestMethod.

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 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 POST), el cuerpo se establece como el valor del cuerpo de la solicitud en el formato name=value estándar.

advertencia: La salida detallada de un cuerpo POST finalizará con with -1-byte payload, aunque el tamaño del cuerpo sea conocido y enviado en el encabezado HTTP de Content-Length.

Cuando el cuerpo es un formulario o es la salida de otra llamada de Invoke-WebRequest, Windows 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.Forms[0]

Propiedades de parámetro

Conjuntos de parámetros

-Certificate

Especifica el certificado de cliente que se usa para una solicitud web segura. Escriba una variable que contenga un certificado o un comando o expresión que obtenga el certificado.

Para encontrar un certificado, utilice Get-PfxCertificate o el comando Get-ChildItem en la unidad de certificados (Cert:). Si el certificado no es válido o no tiene suficiente autoridad, se produce un error en el comando.

Propiedades de parámetro

Conjuntos de parámetros

-CertificateThumbprint

Especifica el certificado de clave pública digital (X509) de una cuenta de usuario que tiene permiso para enviar la solicitud. Ingrese 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; no funcionan con cuentas de dominio.

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

Propiedades de parámetro

Conjuntos de parámetros

-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-RestMethod establece el tipo de contenido en "application/x-www-form-urlencoded". De lo contrario, el tipo de contenido no se especifica en la llamada.

Propiedades de parámetro

Conjuntos de parámetros

-Credential

Especifica una cuenta de usuario que tiene permiso 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 de PSCredential, como uno generado por el cmdlet Get-Credential.

Propiedades de parámetro

Conjuntos de parámetros

-DisableKeepAlive

Establece el valor KeepAlive del encabezado HTTP en Falso. De forma predeterminada, KeepAlive es verdadero. KeepAlive establece una conexión persistente con el servidor para facilitar las solicitudes posteriores.

Propiedades de parámetro

Conjuntos de parámetros

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

Propiedades de parámetro

Conjuntos de parámetros

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

Propiedades de parámetro

Conjuntos de parámetros

-MaximumRedirection

Determina cuántas veces Windows 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 de 0 (cero) impide toda la redirección.

Propiedades de parámetro

Conjuntos de parámetros

-Method

Especifica el método usado para la solicitud web. Los valores aceptables para este parámetro son:

• Predeterminado
• Borrar
• Obtener
• Head
• Fusionar
• Opciones
• Revisión
• Publicar
• Put
• Seguimiento

Propiedades de parámetro

Conjuntos de parámetros

-OutFile

Guarda el cuerpo de la respuesta en el archivo de salida especificado. Escriba 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-RestMethod devuelve los resultados a la canalización. Para enviar los resultados a un archivo y a la canalización, use el parámetro -Passthru.

Propiedades de parámetro

Conjuntos de parámetros

-PassThru

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 .

Propiedades de parámetro

Conjuntos de parámetros

-Proxy

Usa un servidor proxy para la solicitud, en lugar de conectarse directamente al recurso de Internet. Escriba el URI de un servidor proxy de red.

Propiedades de parámetro

Conjuntos de parámetros

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

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.

Propiedades de parámetro

Conjuntos de parámetros

-ProxyUseDefaultCredentials

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.

Propiedades de parámetro

Conjuntos de parámetros

-SessionVariable

Crea una sesión de solicitud web y la guarda en el valor de la variable especificada. Escriba un nombre de variable sin el símbolo de signo de dólar ($).

Al especificar una variable de sesión, Invoke-RestMethod crea un objeto de sesión de solicitud web y lo asigna a una variable con el nombre especificado en la sesión de Windows PowerShell. Puede usar la variable en la sesión tan pronto como se complete el 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 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 usar la sesión de solicitud web en solicitudes web posteriores, especifique la variable de sesión en el valor del parámetro -WebSession. Windows 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.

Propiedades de parámetro

Conjuntos de parámetros

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

Propiedades de parámetro

Conjuntos de parámetros

-TransferEncoding

Especifica un valor para el encabezado de respuesta HTTP de codificación de transferencia. Los valores aceptables para este parámetro son:

• Chunked
• Comprimir
• Deflate
• GZip
• identidad

Propiedades de parámetro

Conjuntos de parámetros

-Uri

Especifica el identificador uniforme de recursos (URI) del recurso de Internet al que se envía la solicitud web. Este parámetro admite valores HTTP, HTTPS, FTP y FILE.

Este parámetro es obligatorio. El nombre del parámetro (-Uri) es opcional.

Propiedades de parámetro

Conjuntos de parámetros

-UseBasicParsing

Indica que el cmdlet utiliza análisis sintáctico básico. El cmdlet devuelve el HTML sin procesar en un objeto String.

Propiedades de parámetro

Conjuntos de parámetros

-UseDefaultCredentials

Usa las credenciales del usuario actual para enviar la solicitud web.

Propiedades de parámetro

Conjuntos de parámetros

-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, Internet Explorer, Opera y Safari.

Por ejemplo, el siguiente comando usa la cadena del agente de usuario para Internet.

Invoke-WebRequest -Uri https://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)

Propiedades de parámetro

Conjuntos de parámetros

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

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

Propiedades de parámetro

Conjuntos de parámetros

CommonParameters

Entradas

Object

Salidas

System.Xml.XmlDocument, Microsoft.PowerShell.Commands.HtmlWebResponseObject, System.String

PSObject

Vínculos relacionados

• ConvertTo-Json
• ConvertFrom-Json
• Invoke-WebRequest