Compartir a través de

Invoke-RestMethod

Módulo:
Microsoft.PowerShell.Utility Module

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

Sintaxis

StandardMethod (Es el valor predeterminado). 

Invoke-RestMethod
    [-Uri] <Uri>
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-HttpVersion <Version>]
    [-WebSession <WebRequestSession>]
    [-SessionVariable <String>]
    [-AllowUnencryptedAuthentication]
    [-Authentication <WebAuthenticationType>]
    [-Credential <PSCredential>]
    [-UseDefaultCredentials]
    [-CertificateThumbprint <String>]
    [-Certificate <X509Certificate>]
    [-SkipCertificateCheck]
    [-SslProtocol <WebSslProtocol>]
    [-Token <SecureString>]
    [-UserAgent <String>]
    [-DisableKeepAlive]
    [-ConnectionTimeoutSeconds <Int32>]
    [-OperationTimeoutSeconds <Int32>]
    [-Headers <IDictionary>]
    [-SkipHeaderValidation]
    [-AllowInsecureRedirect]
    [-MaximumRedirection <Int32>]
    [-MaximumRetryCount <Int32>]
    [-PreserveAuthorizationOnRedirect]
    [-RetryIntervalSec <Int32>]
    [-Method <WebRequestMethod>]
    [-PreserveHttpMethodOnRedirect]
    [-UnixSocket <UnixDomainSocketEndPoint>]
    [-Proxy <Uri>]
    [-ProxyCredential <PSCredential>]
    [-ProxyUseDefaultCredentials]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [<CommonParameters>]

StandardMethodNoProxy 

Invoke-RestMethod
    [-Uri] <Uri>
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-HttpVersion <Version>]
    [-WebSession <WebRequestSession>]
    [-SessionVariable <String>]
    [-AllowUnencryptedAuthentication]
    [-Authentication <WebAuthenticationType>]
    [-Credential <PSCredential>]
    [-UseDefaultCredentials]
    [-CertificateThumbprint <String>]
    [-Certificate <X509Certificate>]
    [-SkipCertificateCheck]
    [-SslProtocol <WebSslProtocol>]
    [-Token <SecureString>]
    [-UserAgent <String>]
    [-DisableKeepAlive]
    [-ConnectionTimeoutSeconds <Int32>]
    [-OperationTimeoutSeconds <Int32>]
    [-Headers <IDictionary>]
    [-SkipHeaderValidation]
    [-AllowInsecureRedirect]
    [-MaximumRedirection <Int32>]
    [-MaximumRetryCount <Int32>]
    [-PreserveAuthorizationOnRedirect]
    [-RetryIntervalSec <Int32>]
    [-Method <WebRequestMethod>]
    [-PreserveHttpMethodOnRedirect]
    [-UnixSocket <UnixDomainSocketEndPoint>]
    [-NoProxy]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [<CommonParameters>]

CustomMethod 

Invoke-RestMethod
    [-Uri] <Uri>
    -CustomMethod <String>
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-HttpVersion <Version>]
    [-WebSession <WebRequestSession>]
    [-SessionVariable <String>]
    [-AllowUnencryptedAuthentication]
    [-Authentication <WebAuthenticationType>]
    [-Credential <PSCredential>]
    [-UseDefaultCredentials]
    [-CertificateThumbprint <String>]
    [-Certificate <X509Certificate>]
    [-SkipCertificateCheck]
    [-SslProtocol <WebSslProtocol>]
    [-Token <SecureString>]
    [-UserAgent <String>]
    [-DisableKeepAlive]
    [-ConnectionTimeoutSeconds <Int32>]
    [-OperationTimeoutSeconds <Int32>]
    [-Headers <IDictionary>]
    [-SkipHeaderValidation]
    [-AllowInsecureRedirect]
    [-MaximumRedirection <Int32>]
    [-MaximumRetryCount <Int32>]
    [-PreserveAuthorizationOnRedirect]
    [-RetryIntervalSec <Int32>]
    [-PreserveHttpMethodOnRedirect]
    [-UnixSocket <UnixDomainSocketEndPoint>]
    [-Proxy <Uri>]
    [-ProxyCredential <PSCredential>]
    [-ProxyUseDefaultCredentials]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [<CommonParameters>]

CustomMethodNoProxy 

Invoke-RestMethod
    [-Uri] <Uri>
    -CustomMethod <String>
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-HttpVersion <Version>]
    [-WebSession <WebRequestSession>]
    [-SessionVariable <String>]
    [-AllowUnencryptedAuthentication]
    [-Authentication <WebAuthenticationType>]
    [-Credential <PSCredential>]
    [-UseDefaultCredentials]
    [-CertificateThumbprint <String>]
    [-Certificate <X509Certificate>]
    [-SkipCertificateCheck]
    [-SslProtocol <WebSslProtocol>]
    [-Token <SecureString>]
    [-UserAgent <String>]
    [-DisableKeepAlive]
    [-ConnectionTimeoutSeconds <Int32>]
    [-OperationTimeoutSeconds <Int32>]
    [-Headers <IDictionary>]
    [-SkipHeaderValidation]
    [-AllowInsecureRedirect]
    [-MaximumRedirection <Int32>]
    [-MaximumRetryCount <Int32>]
    [-PreserveAuthorizationOnRedirect]
    [-RetryIntervalSec <Int32>]
    [-PreserveHttpMethodOnRedirect]
    [-UnixSocket <UnixDomainSocketEndPoint>]
    [-NoProxy]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [<CommonParameters>]

Description

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

PowerShell da formato a la respuesta basada en el tipo de datos. Para una fuente RSS o ATOM, PowerShell devuelve los nodos XML Item o Entry. Para notación de objetos JavaScript (JSON) o XML, PowerShell convierte o deserializa el contenido en objetos [pscustomobject]. Los comentarios se permiten en los datos JSON.

Nota:

Cuando el punto de conexión REST devuelve varios objetos, los objetos se reciben como una matriz. Si canaliza la salida de Invoke-RestMethod a otro comando, se envía como un solo objeto [Object[]]. El contenido de esa matriz no se enumera para el siguiente comando en la canalización.

Este cmdlet se presenta en Windows PowerShell 3.0.

A partir de PowerShell 7.0, Invoke-RestMethod admite la configuración de proxy definida por variables de entorno. Véase la sección NOTAS de este artículo.

A partir de PowerShell 7.4, la codificación de caracteres para las solicitudes tiene como valor predeterminado UTF-8 en lugar de ASCII. Si necesita una codificación diferente, debe establecer el atributo charset en el encabezado Content-Type.

Ejemplos

Ejemplo 1: Obtención de la fuente RSS de PowerShell

En este ejemplo se usa el cmdlet Invoke-RestMethod para obtener información de la fuente RSS del blog de PowerShell. El comando utiliza el cmdlet Format-Table para mostrar los valores de las propiedades Título y pubDate de cada blog en una tabla.

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

Ejemplo 2: Ejecución de una solicitud POST

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

$Cred = Get-Credential
$Url = "https://server.contoso.com:8089/services/search/jobs/export"
$Body = @{
    search = "search index=_internal | reverse | table index,host,source,sourcetype,_raw"
    output_mode = "csv"
    earliest_time = "-2d@d"
    latest_time = "-1d@d"
}
Invoke-RestMethod -Method 'Post' -Uri $url -Credential $Cred -Body $body -OutFile output.csv

El cmdlet solicita credenciales y las almacena en $Cred. $Url contiene la dirección URL del punto de conexión de REST.

La variable $Body describe los criterios de búsqueda, especifica CSV como modo de salida y especifica un período de tiempo para los datos devueltos que comienzan hace dos días y finalizan hace un día. La variable body especifica valores para los parámetros que se aplican a la API REST determinada con la que se comunica Invoke-RestMethod.

El comando Invoke-RestMethod se ejecuta con todas las variables en su lugar, especificando una ruta de acceso y un nombre de archivo para el archivo de salida CSV resultante.

Ejemplo 3: Seguir los vínculos de relación

Algunas API REST admiten la paginación a través de vínculos de relación según RFC5988. En lugar de analizar el encabezado para obtener la dirección URL de la página siguiente, puede hacer que el cmdlet lo haga por usted. En este ejemplo se devuelven las dos primeras páginas de problemas del repositorio de GitHub de PowerShell.

$url = 'https://api.github.com/repos/powershell/powershell/issues'
Invoke-RestMethod $url -FollowRelLink -MaximumFollowRelLink 2

Ejemplo 4: Envío simplificado de Multipart/Form-Data

Algunas API requieren envíos de multipart/form-data para cargar archivos y contenido mixto. En este ejemplo se muestra cómo actualizar el perfil de un 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-RestMethod -Uri $Uri -Method Post -Form $Form

El formulario de perfil requiere estos campos: firstName, lastName, email, avatar, birthdayy hobbies. La API espera que se proporcione una imagen para la imagen de perfil de usuario en el campo avatar. La API también acepta varias entradas hobbies que se enviarán en el mismo formulario.

Al crear el $Form HashTable, los nombres de clave se usan como nombres de campo de formulario. De forma predeterminada, los valores de HashTable se convierten en cadenas. Si está presente un valor System.IO.FileInfo, se envía el contenido del archivo. Si hay una colección, como una matriz o lista, el campo de formulario se envía varias veces.

Con Get-Item en la clave avatar, el objeto FileInfo se establece como valor. El resultado es que se envían los datos de la imagen para jdoe.png.

Al proporcionar una lista a la clave hobbies, el campo hobbies está presente en los envíos una vez para cada elemento de lista.

Ejemplo 5: Pasar varios encabezados

A menudo, las API requieren encabezados pasados para la autenticación o validación. En este ejemplo se muestra cómo pasar varios encabezados de un hash-table a una API REST.

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

Ejemplo 6: Enumerar los elementos devueltos en la canalización

GitHub devuelve varios objetos de una matriz. Si canaliza la salida a otro comando, se envía como un solo objeto [Object[]].

Para enumerar los objetos en la canalización, canalice los resultados a Write-Output o coloque el cmdlet entre paréntesis. En el ejemplo siguiente se cuenta el número de objetos devueltos por GitHub. A continuación, cuente el número de objetos enumerados a la pipeline.

$uri = 'https://api.github.com/repos/microsoftdocs/powershell-docs/issues'
$x = 0
Invoke-RestMethod -Uri $uri | ForEach-Object { $x++ }
$x
1

$x = 0
(Invoke-RestMethod -Uri $uri) | ForEach-Object { $x++ }
$x
30

$x = 0
Invoke-RestMethod -Uri $uri | Write-Output | ForEach-Object { $x++ }
$x
30

Ejemplo 7: Omitir la validación de encabezados

De forma predeterminada, el cmdlet Invoke-RestMethod 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-RestMethod -Uri $Uri -Headers $InvalidHeaders

Invoke-RestMethod -Uri $Uri -Headers $InvalidHeaders -SkipHeaderValidation |
    Format-List

Invoke-RestMethod: The format of value '12345' is invalid.

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=Root=1-62f150a6-27754fd4226f31b43a3d2874}

httpbin.org es un servicio que devuelve información sobre las solicitudes web y las respuestas para solucionar problemas. La variable $Uri se asigna al punto de conexión de /headers del servicio, que devuelve los encabezados de una solicitud como contenido en su respuesta.

El If-Match encabezado de solicitud se define en la sección 3.1 de RFC-7232 y requiere que el valor de ese encabezado se defina con comillas circundantes. A la variable $InvalidHeaders 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".

Llamar a Invoke-RestMethod con encabezados no válidos produce un error que indica que el valor con formato no es válido. La solicitud no se envía al punto de conexión.

Al llamar a Invoke-RestMethod 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 8: Envío de una solicitud mediante HTTP 2.0

En este ejemplo se consulta el problema de GitHub mediante el protocolo HTTP 2.0.

$uri = 'https://api.github.com/repos/microsoftdocs/powershell-docs/issues'
Invoke-RestMethod -Uri $uri -HttpVersion 2.0 -SkipCertificateCheck

Ejemplo 9: Envío de una solicitud a una aplicación de socket unix

Algunas aplicaciones, como Docker, exponen un socket unix para la comunicación. En este ejemplo se consulta una lista de imágenes de Docker mediante la API de Docker. El cmdlet se conecta al demonio de Docker mediante el socket Unix.

Invoke-RestMethod -Uri "http://localhost/v1.40/images/json/" -UnixSocket "/var/run/docker.sock"

Parámetros

-AllowInsecureRedirect

Permite el redireccionamiento desde HTTPS a HTTP. De forma predeterminada, cualquier solicitud que se redirige desde HTTPS a HTTP produce un error y la solicitud se anula para evitar la comunicación involuntaria en texto sin formato a través de conexiones sin cifrar. Para anular este comportamiento bajo su propio riesgo, utilice el parámetro AllowInsecureRedirect.

Este parámetro se agregó en PowerShell 7.4.

Propiedades del parámetro

Tipo:SwitchParameter
Valor predeterminado:False
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-AllowUnencryptedAuthentication

Permite el envío de credenciales y secretos a través de conexiones sin cifrar. De forma predeterminada, el suministro de Credencial o cualquier opción de Autenticación con una Uri que no empiece por https:// provoca un error y la solicitud se aborta para evitar la comunicación involuntaria de secretos en texto plano a través de conexiones no cifradas. 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 para la compatibilidad con sistemas heredados que no pueden proporcionar conexiones cifradas. Úselo bajo su responsabilidad.

Esta característica se agregó en PowerShell 6.0.0.

Propiedades del parámetro

Tipo:SwitchParameter
Valor predeterminado:False
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-Authentication

Especifica el tipo de autenticación explícito que se va a usar para la solicitud. El valor predeterminado es 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 usan para enviar un encabezado de autenticación básica RFC 7617 Authorization: Basic en el formato de base64(user:password).
  • Bearer: requiere el parámetro Token. Envía un encabezado RFC 6750 Authorization: Bearer con el token proporcionado.
  • OAuth: requiere el parámetro Token. Envía un encabezado RFC 6750 Authorization: Bearer con el token proporcionado.

Proporcionar autenticación invalida los encabezados de Authorization proporcionados a encabezados o incluidos en WebSession.

Esta característica se agregó en PowerShell 6.0.0.

Propiedades del parámetro

Tipo:WebAuthenticationType
Valor predeterminado:None
Valores aceptados:None, Basic, Bearer, OAuth
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-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 solicitud. Para los parámetros de consulta, el cmdlet usa el método System.Net.WebUtility.UrlEncode para codificar los pares clave-valor. Para obtener más información sobre las cadenas de codificación para direcciones URL, consulte la referencia de método UrlEncode().

Cuando la entrada es una solicitud POST y el cuerpo es un 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 valor. Para especificar varias claves, use un objeto IDictionary, como una tabla hash, para Cuerpo.

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

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

El parámetro Body también puede aceptar un objeto System.Net.Http.MultipartFormDataContent, lo que facilita las solicitudes multipart/form-data. Cuando se proporciona un objeto MultipartFormDataContent para Body, los encabezados relacionados con el contenido proporcionados a los parámetros ContentType, Headerso WebSession son invalidados por los encabezados de contenido del objeto MultipartFormDataContent. Esta característica se agregó en PowerShell 6.0.0.

Propiedades del parámetro

Tipo:Object
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:True
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-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 del parámetro

Tipo:X509Certificate
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-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. 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 comando Get-Item o Get-ChildItem para buscar el certificado en Cert:\CurrentUser\My.

Nota:

Esta característica solo se admite actualmente en plataformas del sistema operativo Windows.

Propiedades del parámetro

Tipo:String
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-ConnectionTimeoutSeconds

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 ConnectionTimeoutSeconds en un valor mayor que cero, pero menos de 15 segundos, puede tardar 15 segundos o más antes de que se produzca un webException y se agote el tiempo de espera de la solicitud.

Este parámetro reemplazó el parámetro TimeoutSec en PowerShell 7.4. Puede usar TimeoutSec como alias para ConnectionTimeoutSeconds.

Propiedades del parámetro

Tipo:Int32
Valor predeterminado:0
Admite caracteres comodín:False
DontShow:False
Alias:TimeoutSec

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes: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 el 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 omite el parámetro , el tipo de contenido puede ser diferente en función del método HTTP que use:

  • Para un método POST, el tipo de contenido se application/x-www-form-urlencoded
  • Para un método PUT, el tipo de contenido se application/json
  • Para otros métodos, el tipo de contenido no se especifica en la solicitud.

Si usa el parámetro inFile para cargar un archivo, debe establecer el tipo de contenido. Normalmente, el tipo debe ser application/octet-stream. Sin embargo, debe establecer el tipo de contenido en función de los requisitos del punto de conexión.

ContentType se invalida cuando el Body de es un objeto MultipartFormDataContent.

A partir de PowerShell 7.4, si usa este parámetro y el parámetro Headers para definir el encabezado Content-Type, se usa el valor especificado en el parámetro ContentType.

Propiedades del parámetro

Tipo:String
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

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

Puede utilizar Credencial solo o junto con ciertas opciones de parámetros 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 utiliza 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 de SecureString, consulte ¿Qué tan segura es SecureString?.

Propiedades del parámetro

Tipo:PSCredential
Valor predeterminado:Current user
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-CustomMethod

Especifica el método personalizado que se usa para la solicitud web. Esto se puede utilizar cuando el método de solicitud requerido por el punto de conexión no está disponible como opción en el método . Método y CustomMethod no se pueden usar juntos.

Ejemplo:

Invoke-RestMethod -Uri 'https://api.contoso.com/widget/' -CustomMethod 'TEST'

Esto realiza una solicitud HTTP TEST a la API.

Esta característica se agregó en PowerShell 6.0.0.

Propiedades del parámetro

Tipo:String
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False
Alias:CM

Conjuntos de parámetros

CustomMethod
Posición:Named
Mandatory:True
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False
CustomMethodNoProxy
Posición:Named
Mandatory:True
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-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 del parámetro

Tipo:SwitchParameter
Valor predeterminado:False
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-FollowRelLink

Indica que el cmdlet debe seguir los vínculos de relación.

Algunas API REST admiten la paginación a través de vínculos de relación según RFC5988. En lugar de analizar el encabezado para obtener la dirección URL de la página siguiente, puede hacer que el cmdlet lo haga por usted. Para establecer cuántas veces se siguen los vínculos de relación, use el parámetro MaximumFollowRelLink.

Al usar este modificador, el cmdlet devuelve una colección de páginas de resultados. Cada página de resultados puede contener varios elementos de resultado.

Esta característica se agregó en PowerShell 6.0.0.

Tipo:SwitchParameter
Valor predeterminado:False
Admite caracteres comodín:False
DontShow:False
Alias:FL
(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-Form

Convierte un diccionario en un envío de multipart/form-data. Formulario no puede usarse con Cuerpo. El tipo de contenido 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 el 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, como una matriz o lista, el campo de formulario 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. Las colecciones anidadas no son compatibles.

$Form = @{
    tags     = 'Vacation', 'Italy', '2017'
    pictures = Get-ChildItem 'C:\Users\jdoe\Pictures\2017-Italy\'
}

En el ejemplo anterior, el campo tags se proporciona tres veces en el formulario, una vez para cada uno de los valores: Vacation, Italyy 2017. El campo pictures se envía una vez para cada archivo de la carpeta 2017-Italy. El contenido binario de los archivos de esa carpeta se envían como valores.

Esta característica se agregó en PowerShell 6.1.0.

Propiedades del parámetro

Tipo:IDictionary
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes: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.

A partir de PowerShell 7.4, si usa este parámetro para definir el encabezado Content-Type y usa el parámetro ContentType, se utiliza el valor especificado en el parámetro ContentType.

Propiedades del parámetro

Tipo:IDictionary
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes: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

Propiedades del parámetro

Tipo:Version
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-InFile

Obtiene el contenido del cuerpo 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.

También debe establecer el tipo de contenido de la solicitud. Por ejemplo, para cargar un archivo, debe establecer el tipo de contenido. Normalmente, el tipo debe ser application/octet-stream. Sin embargo, debe establecer el tipo de contenido en función de los requisitos del punto de conexión.

Propiedades del parámetro

Tipo:String
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-MaximumFollowRelLink

Especifica cuántas veces se siguen los vínculos de relación si se usa FollowRelLink. Es posible que se necesite un valor más pequeño si la API REST se limita debido a demasiadas solicitudes. El valor predeterminado es [int32]::MaxValue. Un valor de 0 (cero) impide seguir los vínculos de relación.

Tipo:Int32
Valor predeterminado:Int32.MaxValue
Admite caracteres comodín:False
DontShow:False
Alias:ML
(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes: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 de 0 (cero) impide toda la redirección.

Propiedades del parámetro

Tipo:Int32
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes: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 intervalo entre reintentos.

Propiedades del parámetro

Tipo:Int32
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-Method

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

  • Default
  • Delete
  • Get
  • Head
  • Merge
  • Options
  • Patch
  • Post
  • Put
  • Trace

El parámetro CustomMethod se puede usar para los métodos de solicitud no enumerados anteriormente.

Propiedades del parámetro

Tipo:WebRequestMethod
Valor predeterminado:None
Valores aceptados:Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

StandardMethod
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False
StandardMethodNoProxy
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-NoProxy

Indica que el cmdlet no usará un proxy para llegar al destino. Úselo para omitir el proxy configurado en la configuración de Internet o especificado en el entorno.

Este parámetro se introdujo en PowerShell 6.0.

Propiedades del parámetro

Tipo:SwitchParameter
Valor predeterminado:False
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

StandardMethodNoProxy
Posición:Named
Mandatory:True
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False
CustomMethodNoProxy
Posición:Named
Mandatory:True
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-OperationTimeoutSeconds

Este tiempo de espera se aplica a las lecturas de datos dentro de una secuencia, no al tiempo de secuencia en su conjunto. El valor predeterminado, 0, especifica un tiempo de espera indefinido.

Establecer el valor en 30 segundos significa que cualquier retraso de más de 30 segundos entre los datos del flujo finaliza la solicitud. Un archivo grande que tarda varios minutos en descargarse no finalizará a menos que la secuencia se detenga durante más de 30 segundos.

Propiedades del parámetro

Tipo:Int32
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-OutFile

De forma predeterminada, Invoke-RestMethod devuelve los resultados a la canalización. Cuando usas el parámetro OutFile, los resultados se guardan en el archivo especificado y no se devuelven a la canalización. Escriba una ruta de acceso y un nombre de archivo. Para enviar los resultados a un archivo y a la canalización, agregue el parámetro PassThru.

Si omite la ruta de acceso, el valor predeterminado es la ubicación actual. El nombre se trata como una ruta literal. Los nombres que contienen corchetes ([]) deben incluirse entre comillas simples (').

A partir de PowerShell 7.4, puede especificar una ruta de carpeta sin el nombre de archivo. Cuando lo hace, el comando usa el nombre de archivo del último segmento del URI resuelto después de las redirecciones. Al especificar una ruta de carpeta para OutFile, no se puede utilizar el parámetro Resume.

Propiedades del parámetro

Tipo:String
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-PassThru

Este parámetro solo es válido cuando el parámetro OutFile también se usa en el comando . La intención es que los resultados se escriban en el archivo y en la canalización.

Propiedades del parámetro

Tipo:SwitchParameter
Valor predeterminado:No output
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-PreserveAuthorizationOnRedirect

Indica que el cmdlet debe conservar el encabezado Authorization, cuando está presente, entre redirecciones.

De forma predeterminada, el cmdlet quita el encabezado Authorization antes de redirigir. 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.

Propiedades del parámetro

Tipo:SwitchParameter
Valor predeterminado:False
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-PreserveHttpMethodOnRedirect

Indica que el cmdlet debe conservar el método de la solicitud entre redirecciones.

De forma predeterminada, el cmdlet cambia el método a GET cuando se redirige. Al especificar este parámetro, se deshabilita esta lógica para asegurarse de que el método previsto se puede usar con el redireccionamiento.

Esta característica se agregó en PowerShell 7.4.

Propiedades del parámetro

Tipo:SwitchParameter
Valor predeterminado:False
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-Proxy

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

Esta característica se agregó en PowerShell 6.0.0.

Propiedades del parámetro

Tipo:Uri
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

StandardMethod
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False
CustomMethod
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes: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 de PSCredential, como uno generado por el cmdlet Get-Credential.

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

Propiedades del parámetro

Tipo:PSCredential
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

StandardMethod
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False
CustomMethod
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-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 es usado en el comando. No puede usar los parámetros ProxyCredential y ProxyUseDefaultCredentials en el mismo comando.

Propiedades del parámetro

Tipo:SwitchParameter
Valor predeterminado:False
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

StandardMethod
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False
CustomMethod
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-ResponseHeadersVariable

Crea una variable que contiene un diccionario de encabezados de respuesta. Escriba un nombre de variable sin el símbolo de signo de dólar ($). Las claves del diccionario contienen los nombres de campo y los valores del encabezado de respuesta devuelto por el servidor web.

Esta característica se agregó en PowerShell 6.0.0.

Propiedades del parámetro

Tipo:String
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False
Alias:RHV

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-Resume

Realiza un mejor intento de reanudar la descarga de un archivo parcial. El parámetro Resume requiere el parámetro 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 usar OutFile sin Reanudar.

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 usar OutFile sin Reanudar.

Si el archivo local no existe, se crea el archivo local y se descarga todo el archivo remoto. Este comportamiento es el mismo que usar OutFile sin Reanudar.

Esta característica se agregó en PowerShell 6.1.0.

Propiedades del parámetro

Tipo:SwitchParameter
Valor predeterminado:False
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes: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. El valor debe estar entre 1 y [int]::MaxValue. Cuando el código de error es 429 y la respuesta incluye la propiedad Retry-After en sus encabezados, el cmdlet usa ese valor para el intervalo de reintento, incluso si se especifica este parámetro.

Consulte también el parámetro MaximumRetryCount para especificar el número de reintentos.

Propiedades del parámetro

Tipo:Int32
Valor predeterminado:5
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-SessionVariable

Crea una variable que contiene la sesión de solicitud web. 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 PowerShell. Puede usar la variable en la sesión tan pronto como se complete el 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 lo son, el cmdlet recrea 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.

Propiedades del parámetro

Tipo:String
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False
Alias:SV

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-SkipCertificateCheck

Omite las comprobaciones de validación de certificados que incluyen todas las validaciones, como expiración, revocación, entidad 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 utilizarse en hosts conocidos que usen un certificado autofirmado con fines de prueba. Úselo bajo su responsabilidad.

Esta característica se agregó en PowerShell 6.0.0.

Propiedades del parámetro

Tipo:SwitchParameter
Valor predeterminado:False
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-SkipHeaderValidation

Indica que el cmdlet debe agregar encabezados a la solicitud sin validación.

Este interruptor 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 verificar. Cuando se especifica, se agregan todos los encabezados sin validación.

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

Propiedades del parámetro

Tipo:SwitchParameter
Valor predeterminado:False
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes: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.

Propiedades del parámetro

Tipo:SwitchParameter
Valor predeterminado:False
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes: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 proporcionar varios valores en todas las plataformas.

Esta característica se agregó en PowerShell 6.0.0. Se ha agregado compatibilidad con Tls13 en PowerShell 7.1.

Propiedades del parámetro

Tipo:WebSslProtocol
Valor predeterminado:None
Valores aceptados:Default, Tls, Tls11, Tls12, Tls13
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-StatusCodeVariable

Crea una variable que contiene un resultado de código de estado HTTP de la solicitud. Escriba un nombre de variable sin el símbolo de signo de dólar ($).

El parámetro puede identificar mensajes correctos o mensajes de error cuando se usan con el parámetro SkipHttpErrorCheck.

Escriba el nombre de variable del parámetro como una cadena como -StatusCodeVariable "scv".

Este parámetro se introdujo en PowerShell 7.

Propiedades del parámetro

Tipo:String
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-Token

Token OAuth o de portador que se va a incluir en la solicitud. El token es necesario para ciertas opciones de autenticación . No se puede usar de forma independiente.

Token toma una SecureString que contiene el token. Para proporcionar el token, use manualmente lo siguiente:

Invoke-RestMethod -Uri $uri -Authentication OAuth -Token (Read-Host -AsSecureString)

Este parámetro se introdujo en PowerShell 6.0.

Propiedades del parámetro

Tipo:SecureString
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-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 del parámetro

Tipo:String
Valor predeterminado:None
Valores aceptados:chunked, compress, deflate, gzip, identity
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-UnixSocket

Especifica el nombre del socket unix al que se va a conectar. Este parámetro se admite en sistemas basados en Unix y windows versión 1803 y posteriores. Para obtener más información sobre la compatibilidad de Windows con sockets Unix, consulte la entrada de blog Interoperabilidad de Windows/WSL con AF_UNIX.

Este parámetro se agregó en PowerShell 7.4.

Propiedades del parámetro

Tipo:UnixDomainSocketEndPoint
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes: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.

Propiedades del parámetro

Tipo:Uri
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:0
Mandatory:True
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-UseBasicParsing

Este parámetro ha quedado en desuso. A partir de PowerShell 6.0.0, todas las solicitudes web solo usan el análisis básico. Este parámetro solo se incluye para la compatibilidad con versiones anteriores. Cuando se usa, no tiene ningún efecto en el funcionamiento del cmdlet.

Propiedades del parámetro

Tipo:SwitchParameter
Valor predeterminado:False
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-UseDefaultCredentials

Indica que el cmdlet usa las credenciales del usuario actual para enviar la solicitud web. No se puede usar con Autenticación o Credencial y es posible que no se admita en todas las plataformas.

Propiedades del parámetro

Tipo:SwitchParameter
Valor predeterminado:False
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes: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.

Propiedades del parámetro

Tipo:String
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes: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, se invalidan cuando se proporciona un objeto MultipartFormDataContent para Cuerpo.

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 del parámetro

Tipo:WebRequestSession
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

CommonParameters

Este cmdlet admite los parámetros comunes: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction y -WarningVariable. Para obtener más información, vea about_CommonParameters.

Entradas

Object

Puede canalizar el cuerpo de una solicitud web a este cmdlet.

Salidas

Int64

Cuando la solicitud devuelve un entero, este cmdlet devuelve ese entero.

String

Cuando la solicitud devuelve una cadena, este cmdlet devuelve esa cadena.

XmlDocument

Cuando la solicitud devuelve XML válido, este cmdlet lo devuelve como un XmlDocument.

PSObject

Cuando la solicitud devuelve cadenas JSON, este cmdlet devuelve un PSObject que representa los datos.

Notas

PowerShell incluye los siguientes alias para Invoke-RestMethod:

  • Todas las plataformas:
    • irm

Es posible que algunas características no estén disponibles en todas las plataformas.

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 difiere en función de la plataforma:

  • Para Windows: Lee la configuración del proxy de las variables de entorno o, si estas no están definidas, desde la configuración del proxy del usuario.
  • Para macOS: Lee la configuración del proxy a partir de las variables de entorno o, si no están definidas, desde la configuración del proxy del sistema.
  • Para Linux: lee la configuración del proxy de las variables de entorno o, en caso de que no se definan, esta propiedad inicializa una instancia no configurada que omite todas las direcciones.

Las variables de entorno utilizadas para la inicialización de DefaultProxy en plataformas basadas en Windows y Unix son:

  • HTTP_PROXY: el nombre de host o la dirección IP del servidor proxy que se usa 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 caso de que no se definan HTTP_PROXY o HTTPS_PROXY.
  • NO_PROXY: una lista separada por comas de nombres de host que se deben excluir del uso de proxy.

PowerShell 7.4 agregó compatibilidad con el algoritmo de compresión Brotli.