Invoke-RestMethod

Referencia

Módulo:: Microsoft.PowerShell.Utility

Envía una solicitud HTTP o HTTPS a un servicio web RESTful.

Syntax

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

El Invoke-RestMethod cmdlet envía solicitudes HTTP y HTTPS a servicios web de transferencia de estado representacional (REST) que devuelven datos estructurados enriquecidos.

Windows PowerShell da formato a la respuesta según el tipo de datos. Para una fuente RSS o ATOM, Windows PowerShell devuelve los nodos XML Item o Entry. Para JavaScript Object Notation (JSON) o XML, Windows PowerShell convierte (o deserializa) el contenido en objetos.

Este cmdlet se incorporó 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: Obtención de la fuente RSS de PowerShell

Invoke-RestMethod -Uri https://blogs.msdn.microsoft.com/powershell/feed/ |
  Format-Table -Property Title, pubDate

Title                                                                pubDate
-----                                                                -------
Join the PowerShell 10th Anniversary Celebration!                    Tue, 08 Nov 2016 23:00:04 +0000
DSC Resource Kit November 2016 Release                               Thu, 03 Nov 2016 00:19:07 +0000
PSScriptAnalyzer Community Call - Oct 18, 2016                       Thu, 13 Oct 2016 17:52:35 +0000
New Home for In-Box DSC Resources                                    Sat, 08 Oct 2016 07:13:10 +0000
New Social Features on Gallery                                       Fri, 30 Sep 2016 23:04:34 +0000
PowerShellGet and PackageManagement in PowerShell Gallery and GitHub Thu, 29 Sep 2016 22:21:42 +0000
PowerShell Security at DerbyCon                                      Wed, 28 Sep 2016 01:13:19 +0000
DSC Resource Kit September Release                                   Thu, 22 Sep 2016 00:25:37 +0000
PowerShell DSC and implicit remoting broken in KB3176934             Tue, 23 Aug 2016 15:07:50 +0000
PowerShell on Linux and Open Source!                                 Thu, 18 Aug 2016 15:32:02 +0000

Este comando usa el Invoke-RestMethod cmdlet para obtener información de la fuente RSS del blog de PowerShell. El comando usa el Format-Table cmdlet para mostrar los valores de las propiedades Title y pubDate de cada blog de una tabla.

Ejemplo 2

En el ejemplo siguiente, un usuario ejecuta Invoke-RestMethod para realizar una solicitud POST en un sitio web de intranet de la organización del usuario.

$Cred = Get-Credential

# Next, allow the use of self-signed SSL certificates.

[System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $True }

# Create variables to store the values consumed by the Invoke-RestMethod command.
# The search variable contents are later embedded in the body variable.

$Server = 'server.contoso.com'
$Url = "https://${server}:8089/services/search/jobs/export"
$Search = "search index=_internal | reverse | table index,host,source,sourcetype,_raw"

# The cmdlet handles URL encoding. The body variable describes the search criteria, specifies CSV as the output mode, and specifies a time period for returned data that starts two days ago and ends one day ago. The body variable specifies values for parameters that apply to the particular REST API with which Invoke-RestMethod is communicating.

$Body = @{
    search = $Search
    output_mode = "csv"
    earliest_time = "-2d@d"
    latest_time = "-1d@d"
}

# Now, run the Invoke-RestMethod command with all variables in place, specifying a path and file name for the resulting CSV output file.

Invoke-RestMethod -Method Post -Uri $url -Credential $Cred -Body $body -OutFile output.csv

{"preview":true,"offset":0,"result":{"sourcetype":"contoso1","count":"9624"}}

{"preview":true,"offset":1,"result":{"sourcetype":"contoso2","count":"152"}}

{"preview":true,"offset":2,"result":{"sourcetype":"contoso3","count":"88494"}}

{"preview":true,"offset":3,"result":{"sourcetype":"contoso4","count":"15277"}}

Ejemplo 3: Pasar varios encabezados

$headers = @{
    'userId' = 'UserIDValue'
    'token' = 'TokenValue'
}
Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $body

A menudo, las API requieren encabezados pasados para la autenticación, la validación, etc.

En este ejemplo se muestra cómo pasar varios encabezados de a hash-table una API REST.

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

El -Body parámetro 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 con el formato nombre estándar= valor.

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 Content-Length encabezado HTTP.

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

Por ejemplo:

$R = Invoke-WebRequest $R.Forms https://website.com/login.aspx [0]. Name = "MyName" $R.Forms[0]. Password = "MyPassword" 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 para 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 Windows 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-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.

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

Establece el valor de 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 -UserAgent parámetro . No puede utilizar este parámetro para especificar encabezados de 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

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

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

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

-PassThru

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:	No output
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Proxy

Utiliza 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 -Proxy parámetro . 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 también se usa el parámetro -Proxy en el comando. No puede usar los -ProxyCredential parámetros 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

Usa las credenciales del usuario actual para tener acceso al servidor proxy especificado por el -Proxy parámetro .

Este parámetro solo es válido cuando también se usa el parámetro -Proxy en el comando. No puede usar los -ProxyCredential parámetros y -ProxyUseDefaultCredentials en el mismo comando.

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

-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 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 usar la sesión de solicitud web en solicitudes web posteriores, especifique la variable de sesión en el valor del -WebSession parámetro . 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 -SessionVariable parámetros 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 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

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

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

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

-UseBasicParsing

Indica que el cmdlet usa el análisis básico. El cmdlet devuelve el HTML sin formato en un objeto String .

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

-UseDefaultCredentials

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

Type:	SwitchParameter
Position:	Named
Default value:	None
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 pequeñas 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 de agente de usuario para Internet

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.

Para crear una sesión de solicitud web, escriba un nombre de variable (sin un signo de dólar) en el -SessionVariable valor del parámetro de un Invoke-RestMethod comando. Invoke-RestMethod crea la sesión y la guarda en la variable . En los comandos posteriores, use la variable como valor del -WebSession parámetro .