Invoke-RestMethod
Envía una solicitud HTTP o HTTPS a un servicio web RESTful.
Syntax
Invoke-RestMethod
[-Method <WebRequestMethod>]
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <String>]
[-StatusCodeVariable <String>]
[-UseBasicParsing]
[-Uri] <Uri>
[-HttpVersion <Version>]
[-WebSession <WebRequestSession>]
[-SessionVariable <String>]
[-AllowUnencryptedAuthentication]
[-Authentication <WebAuthenticationType>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-CertificateThumbprint <String>]
[-Certificate <X509Certificate>]
[-SkipCertificateCheck]
[-SslProtocol <WebSslProtocol>]
[-Token <SecureString>]
[-UserAgent <String>]
[-DisableKeepAlive]
[-TimeoutSec <Int32>]
[-Headers <IDictionary>]
[-MaximumRedirection <Int32>]
[-MaximumRetryCount <Int32>]
[-RetryIntervalSec <Int32>]
[-Proxy <Uri>]
[-ProxyCredential <PSCredential>]
[-ProxyUseDefaultCredentials]
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>] Invoke-RestMethod
[-Method <WebRequestMethod>]
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <String>]
[-StatusCodeVariable <String>]
[-UseBasicParsing]
[-Uri] <Uri>
[-HttpVersion <Version>]
[-WebSession <WebRequestSession>]
[-SessionVariable <String>]
[-AllowUnencryptedAuthentication]
[-Authentication <WebAuthenticationType>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-CertificateThumbprint <String>]
[-Certificate <X509Certificate>]
[-SkipCertificateCheck]
[-SslProtocol <WebSslProtocol>]
[-Token <SecureString>]
[-UserAgent <String>]
[-DisableKeepAlive]
[-TimeoutSec <Int32>]
[-Headers <IDictionary>]
[-MaximumRedirection <Int32>]
[-MaximumRetryCount <Int32>]
[-RetryIntervalSec <Int32>]
-NoProxy
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>] Invoke-RestMethod
-CustomMethod <String>
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <String>]
[-StatusCodeVariable <String>]
[-UseBasicParsing]
[-Uri] <Uri>
[-HttpVersion <Version>]
[-WebSession <WebRequestSession>]
[-SessionVariable <String>]
[-AllowUnencryptedAuthentication]
[-Authentication <WebAuthenticationType>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-CertificateThumbprint <String>]
[-Certificate <X509Certificate>]
[-SkipCertificateCheck]
[-SslProtocol <WebSslProtocol>]
[-Token <SecureString>]
[-UserAgent <String>]
[-DisableKeepAlive]
[-TimeoutSec <Int32>]
[-Headers <IDictionary>]
[-MaximumRedirection <Int32>]
[-MaximumRetryCount <Int32>]
[-RetryIntervalSec <Int32>]
[-Proxy <Uri>]
[-ProxyCredential <PSCredential>]
[-ProxyUseDefaultCredentials]
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>] Invoke-RestMethod
-CustomMethod <String>
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <String>]
[-StatusCodeVariable <String>]
[-UseBasicParsing]
[-Uri] <Uri>
[-HttpVersion <Version>]
[-WebSession <WebRequestSession>]
[-SessionVariable <String>]
[-AllowUnencryptedAuthentication]
[-Authentication <WebAuthenticationType>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-CertificateThumbprint <String>]
[-Certificate <X509Certificate>]
[-SkipCertificateCheck]
[-SslProtocol <WebSslProtocol>]
[-Token <SecureString>]
[-UserAgent <String>]
[-DisableKeepAlive]
[-TimeoutSec <Int32>]
[-Headers <IDictionary>]
[-MaximumRedirection <Int32>]
[-MaximumRetryCount <Int32>]
[-RetryIntervalSec <Int32>]
-NoProxy
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>] Description
El Invoke-RestMethod cmdlet envía solicitudes HTTP y HTTPS a servicios web de transferencia de estado representacional (REST) que devuelven datos enriquecidos estructurados.
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. En el caso de la notación de objetos JavaScript (JSON) o XML, PowerShell convierte o deserializa el contenido en [PSCustomObject] objetos .
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 único [Object[]] objeto. El contenido de esa matriz no se enumera para el siguiente comando de la canalización.
Este cmdlet se incorporó en Windows PowerShell 3.0.
A partir de PowerShell 7.0, Invoke-RestMethod admite la configuración de proxy definida por variables de entorno. Consulte la sección Notas de este artículo.
Ejemplos
Ejemplo 1: Obtención de la fuente RSS de PowerShell
En este ejemplo se 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.
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 +0000Ejemplo 2: Ejecución de una solicitud POST
En este ejemplo, un usuario se ejecuta Invoke-RestMethod para realizar una solicitud POST en un sitio web de intranet de 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.csvSe solicitan las credenciales y, a continuación, se almacenan en $Cred y la dirección URL a la que se accederá se define en $Url.
La $Body variable 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 concreta con la que Invoke-RestMethod se comunica.
El Invoke-RestMethod comando 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 vínculos de relación
Algunas API REST admiten la paginación a través de vínculos de relación por 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 2Ejemplo 4: Envío simplificado de datos de varias partes o formularios
Algunas API requieren multipart/form-data envíos para cargar archivos y contenido mixto. En este ejemplo se muestra cómo actualizar 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 $FormEl formulario de perfil requiere estos campos: firstName, lastName, email, avatar, birthdayy hobbies. La API espera que se proporcione una imagen de la imagen de perfil de usuario en el avatar campo . La API también aceptará varias hobbies entradas que se enviarán en el mismo formulario.
Al crear hashTable $Form , los nombres de clave se usan como nombres de campo de formulario. De forma predeterminada, los valores de HashTable se convertirán en cadenas. Si hay un System.IO.FileInfo valor presente, se enviará el contenido del archivo. Si hay una colección como matrices o listas, el campo de formulario se enviará varias veces.
Get-Item Con en la avatar clave, el FileInfo objeto se establecerá como valor. El resultado es que se enviarán los datos jdoe.png de la imagen.
Al proporcionar una lista a la hobbies clave, el hobbies campo estará 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 a hash-table una API REST.
$headers = @{
'userId' = 'UserIDValue'
'token' = 'TokenValue'
}
Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $bodyEjemplo 6: Enumerar 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 [Object[]]objeto.
Para enumerar los objetos en la canalización, canalice los resultados a Write-Output o encapsula el cmdlet entre paréntesis. En el ejemplo siguiente se cuenta el número de objetos devueltos por GitHub. A continuación, cuenta el número de objetos enumerados en la canalización.
$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
30Ejemplo 7: Omitir la validación de encabezados
De forma predeterminada, el Invoke-RestMethod cmdlet valida los valores de los encabezados conocidos que tienen un formato de valor definido por estándar. 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 $Uri variable se asigna al /headers punto de conexión del servicio, que devuelve los encabezados de una solicitud como contenido en su respuesta.
El If-Match encabezado de solicitud se define en la sección 3.1 de RFC-7232 y requiere que el valor de ese encabezado se defina con comillas circundantes. A $InvalidHeaders la variable se le asigna una tabla hash donde el valor de If-Match no es válido porque se define como 12345 en lugar de "12345".
Al llamar Invoke-RestMethod con los encabezados no válidos, se devuelve un error que informa de que el valor con formato no es válido. La solicitud no se envía al punto de conexión.
Al llamar Invoke-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 -SkipCertificateCheckParámetros
-AllowUnencryptedAuthentication
Permite el envío de credenciales y secretos a través de conexiones sin cifrar. De forma predeterminada, proporcionar credenciales o cualquier opción de autenticación con un URI que no comience por https:// producirá un error y la solicitud se anulará para evitar la comunicación involuntaria de secretos en texto sin formato a través de conexiones sin cifrar. Para invalidar este comportamiento en su propio riesgo, proporcione el parámetro AllowUnencryptedAuthentication .
Advertencia
El uso de este parámetro no es seguro y no se recomienda. Solo se proporciona para la compatibilidad con sistemas heredados que no pueden proporcionar conexiones cifradas. Use en su propio riesgo.
Esta característica se agregó en PowerShell 6.0.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Authentication
Especifica el tipo de autenticación explícito que se va a usar para la solicitud. El valor predeterminado es None (Ninguno). El parámetro Authentication no se puede usar con el parámetro UseDefaultCredentials .
Opciones de autenticación disponibles:
None: esta es la opción predeterminada cuando no se proporciona autenticación . No se usará ninguna autenticación explícita.Basic: requiere credencial. Las credenciales se usarán para enviar un encabezado de autenticaciónAuthorization: Basicbásica RFC 7617 con el formato debase64(user:password).Bearer: requiere el parámetro Token . Envía un encabezado RFC 6750Authorization: Bearercon el token proporcionado.OAuth: requiere el parámetro Token . Envía un encabezado RFC 6750Authorization: Bearercon el token proporcionado.
Proporcionar autenticación invalida los Authorization encabezados proporcionados a los encabezados o incluidos en WebSession.
Esta característica se agregó en PowerShell 6.0.0.
| Type: | WebAuthenticationType |
| Accepted values: | None, Basic, Bearer, OAuth |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Body
Especifica el cuerpo de la solicitud. El cuerpo es el contenido de la solicitud que sigue a los encabezados.
También puede canalizar un valor de cuerpo a Invoke-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 POST y el cuerpo es string, el valor a la izquierda del primer signo igual (=) se establece como una clave en los datos del formulario y el texto restante se establece como el valor. Para especificar varias claves, use un objeto IDictionary, como una tabla hash, para body.
Cuando la entrada es una solicitud GET y el cuerpo es un IDictionary (normalmente, una tabla hash), el cuerpo se agrega al URI como parámetros de consulta. Para otros tipos de solicitud (como PATCH), el cuerpo se establece como el valor del cuerpo de la solicitud en el formato estándar name=value con los valores codificados por url.
Cuando la entrada es un objeto System.Xml.XmlNode y la declaración XML especifica una codificación, esa codificación se usa para los datos de la solicitud a menos que el parámetro ContentType lo invalide.
Cuando el cuerpo es un formulario o es la salida de otra Invoke-WebRequest llamada, PowerShell establece el contenido de la solicitud en los campos del formulario.
El parámetro Body también puede aceptar un objeto System.Net.Http.MultipartFormDataContent . Esto facilitará multipart/form-data las solicitudes. Cuando se proporciona un objeto MultipartFormDataContent para Body, los encabezados de contenido proporcionados a los parámetros ContentType, Headers o WebSession se invalidarán mediante los encabezados de contenido del MultipartFormDataContent objeto. Esta característica se agregó en PowerShell 6.0.0.
| Type: | Object |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Certificate
Especifica el certificado de cliente que se usa para una solicitud web segura. Introduzca una variable que contenga un certificado o un comando o una expresión que obtenga el certificado.
Para buscar un certificado, use Get-PfxCertificate o use el Get-ChildItem cmdlet en la unidad Certificado (Cert:). Si el certificado no es válido o no tiene suficiente autoridad, se produce un error en el comando.
| Type: | X509Certificate |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-CertificateThumbprint
Especifica el certificado de clave pública digital (X509) de una cuenta de usuario que tiene permiso para realizar esta acción. Escriba la huella digital del certificado.
Los certificados se usan para la autenticación basada en certificados de cliente. Los certificados solo se pueden asignar a cuentas de usuario locales, no a cuentas de dominio.
Para ver la huella digital del certificado, use el Get-Item comando o Get-ChildItem para buscar el certificado en Cert:\CurrentUser\My.
Nota:
Esta característica solo se admite actualmente en plataformas del sistema operativo Windows.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ContentType
Especifica el tipo de contenido de la solicitud web.
Si el valor de ContentType contiene el formato de codificación (como charset), el cmdlet usa ese formato para codificar el cuerpo de la solicitud web. Si ContentType no especifica un formato de codificación, se usa en su lugar el formato de codificación predeterminado. Un ejemplo de contentType con un formato de codificación es text/plain; charset=iso-8859-5, que especifica el alfabeto latino/cirílico.
Si se omite este parámetro y el método de solicitud es POST, Invoke-RestMethod establece el tipo application/x-www-form-urlencodedde contenido en . De lo contrario, el tipo de contenido no se especifica en la llamada.
ContentType se invalidará cuando se proporcione un MultipartFormDataContent objeto para Body.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Credential
Especifica una cuenta de usuario que tiene permisos para enviar la solicitud. El valor predeterminado es el usuario actual.
Escriba un nombre de usuario, como User01 o Domain01\User01, o escriba un objeto PSCredential generado por el Get-Credential cmdlet .
Las credenciales se pueden usar solas o junto con determinadas opciones de parámetro de autenticación . Cuando se usa solo, solo proporcionará credenciales al servidor remoto si el servidor remoto envía una solicitud de desafío de autenticación. Cuando se usa con opciones de autenticación , las credenciales se enviarán explícitamente.
Las credenciales se almacenan en un objeto PSCredential y la contraseña se almacena como SecureString.
Nota:
Para obtener más información sobre la protección de datos SecureString , consulte ¿Cómo es secure is SecureString?.
| Type: | PSCredential |
| Position: | Named |
| Default value: | Current user |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-CustomMethod
Especifica el método personalizado que se usa para la solicitud web. Esto se puede usar con el método de solicitud requerido por el punto de conexión no es una opción disponible en el método . El método y CustomMethod no se pueden usar juntos.
Ejemplo:
Invoke-RestMethod -uri 'https://api.contoso.com/widget/' -CustomMethod 'TEST'
Esto realiza una TEST solicitud HTTP a la API.
Esta característica se agregó en PowerShell 6.0.0.
| Type: | String |
| Aliases: | CM |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-DisableKeepAlive
Indica que el cmdlet establece el valor KeepAlive en el encabezado HTTP en False. De forma predeterminada, KeepAlive es True. KeepAlive establece una conexión persistente con el servidor para facilitar las solicitudes posteriores.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-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 por 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.
| Type: | SwitchParameter |
| Aliases: | FL |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Form
Convierte un diccionario en un multipart/form-data envío. El formulario no se puede usar con Body.
Si Se omitirá ContentType .
Las claves del diccionario se usarán como nombres de campo de formulario. De forma predeterminada, los valores de formulario se convertirán en valores de cadena.
Si el valor es un objeto System.IO.FileInfo , se enviará el contenido del archivo binario.
El nombre del archivo se enviará como .filename El MIME se establecerá 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 para se enviará varias veces. Los valores de la lista se tratarán como cadenas de forma predeterminada. Si el valor es un objeto System.IO.FileInfo , se enviará el contenido del archivo binario. No se admiten colecciones anidadas.
$Form = @{ tags = 'Vacation', 'Italy', '2017' pictures = Get-ChildItem 'c:\Users\jdoe\Pictures\2017-Italy' }
En el ejemplo anterior, el tags campo se proporcionará tres veces en el formulario, una vez para cada uno de Vacation, Italyy 2017. El pictures campo también se enviará una vez para cada archivo de la 2017-Italy carpeta. El contenido binario de los archivos de esa carpeta se enviará como valores.
Esta característica se agregó en PowerShell 6.1.0.
| Type: | IDictionary |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Headers
Especifica los encabezados de la solicitud web. Especifique una tabla hash o un diccionario.
Los encabezados relacionados con el contenido, como Content-Type , por ejemplo, se invalidan cuando se proporciona un MultipartFormDataContent objeto para Body.
| Type: | IDictionary |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-HttpVersion
Especifica la versión HTTP usada para la solicitud. El valor predeterminado es 1.1.
Los valores válidos son:
- 1.0
- 1.1
- 2.0
- 3.0
| Type: | Version |
| Position: | Named |
| Default value: | 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 |
-MaximumFollowRelLink
Especifica cuántas veces se deben seguir 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 limita debido a demasiadas solicitudes. El valor predeterminado es [Int32]::MaxValue. Un valor de 0 (cero) impide seguir los vínculos de relación.
| Type: | Int32 |
| Aliases: | ML |
| Position: | Named |
| Default value: | Int32.MaxValue |
| 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: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MaximumRetryCount
Especifica cuántas veces PowerShell reintenta una conexión cuando se recibe un código de error entre 400 y 599, ambos incluidos o 304. Consulte también el parámetro RetryIntervalSec para especificar el número de segundos entre reintentos.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Method
Especifica el método utilizado para la solicitud web. Los valores permitidos para este parámetro son los siguientes:
DefaultDeleteGetHeadMergeOptionsPatchPostPutTrace
El parámetro CustomMethod se puede usar para los métodos de solicitud no enumerados anteriormente.
| Type: | WebRequestMethod |
| Accepted values: | Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-NoProxy
Indica que el cmdlet no usará un proxy para llegar al destino.
Cuando necesite omitir el proxy configurado en Internet Explorer o un proxy especificado en el entorno, use este modificador.
Este parámetro se introdujo en PowerShell 6.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-OutFile
Guarda el cuerpo de 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. El nombre se trata como una ruta de acceso literal. Los nombres que contienen corchetes ([]) deben incluirse entre comillas simples (').
De forma predeterminada, Invoke-RestMethod devuelve los resultados a la canalización.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | 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 tener los resultados escritos en el archivo y en la canalización.
Nota:
Cuando se usa el parámetro PassThru , la salida se escribe en la canalización, pero no se crea el archivo. Para obtener más información, vea Problema de PowerShell n.º 15409.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | No output |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PreserveAuthorizationOnRedirect
Indica que el cmdlet debe conservar el Authorization encabezado, cuando está presente, entre redirecciones.
De forma predeterminada, el cmdlet quita el Authorization encabezado antes de redirigirlo. Al especificar este parámetro, se deshabilita esta lógica para los casos en los que el encabezado debe enviarse a la ubicación de redireccionamiento.
Esta característica se agregó en PowerShell 6.0.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Proxy
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.
| 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, User@Domain.Como escriba un PSCredential objeto, 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: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ProxyUseDefaultCredentials
Indica que el cmdlet usa las credenciales del usuario actual para acceder al servidor proxy especificado por el parámetro Proxy .
Este parámetro solo es válido cuando el parámetro Proxy también se usa en el comando . No puede usar los parámetros ProxyCredential y ProxyUseDefaultCredentials en el mismo comando.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-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.
| Type: | String |
| Aliases: | RHV |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | 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 intentará reanudar la descarga del archivo y anexará 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, se sobrescribirá el archivo local y se volverá a descargar completamente el archivo remoto. Este comportamiento es el mismo que el uso de OutFile sin Resume.
Si el servidor remoto no admite la reanudación de descargas, se sobrescribirá el archivo local y se volverá a descargar completamente el archivo remoto. Este comportamiento es el mismo que el uso de OutFile sin Resume.
Si el archivo local no existe, se creará el archivo local y se descargará por completo el archivo remoto. Este comportamiento es el mismo que el uso de OutFile sin Resume.
Esta característica se agregó en PowerShell 6.1.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-RetryIntervalSec
Especifica el intervalo entre reintentos para la conexión cuando se recibe un código de error entre 400 y 599, ambos incluidos o 304. El valor debe estar entre 1 y [int]::MaxValue.
Consulte también el parámetro MaximumRetryCount para especificar el número de reintentos.
| Type: | Int32 |
| Position: | Named |
| Default value: | 5 |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | 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 en cuanto finalice la ejecución del comando.
Antes de PowerShell 7.4, la sesión de solicitud web no es una conexión persistente. Es un objeto que contiene información sobre la conexión y la solicitud, incluidas las cookies, las credenciales, el valor de redireccionamiento máximo y la cadena del agente de usuario. Puede usarlo para compartir el estado y los datos entre las solicitudes web.
A partir de PowerShell 7.4, la sesión de solicitud web es persistente siempre que las propiedades de la sesión no se invalidan en una solicitud posterior. Cuando son, el cmdlet vuelve a crear la sesión con los nuevos valores. Las sesiones persistentes reducen la sobrecarga de las solicitudes repetidas, lo que las hace mucho más rápidas.
Para usar la sesión de solicitud web en solicitudes web posteriores, especifique la variable de sesión en el valor del parámetro WebSession . PowerShell usa los datos del objeto de sesión de solicitud web al establecer la nueva conexión. Para invalidar un valor en la sesión de solicitud web, use un parámetro de cmdlet, como UserAgent o Credential. Los valores de parámetro tienen prioridad sobre los valores de la sesión de solicitud web.
No puede usar los parámetros SessionVariable y WebSession en el mismo comando.
| Type: | String |
| Aliases: | SV |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SkipCertificateCheck
Omite las comprobaciones de validación de certificados 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 usarse en hosts conocidos mediante un certificado autofirmado con fines de prueba. Use en su propio riesgo.
Esta característica se agregó en PowerShell 6.0.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SkipHeaderValidation
Indica que el cmdlet debe agregar encabezados a la solicitud sin validación.
Este modificador debe usarse para sitios que requieran valores de encabezado que no cumplan los estándares. Al especificar este modificador, se deshabilita la validación para permitir que el valor se pase sin activar. Cuando se especifica, se agregan todos los encabezados sin validación.
Esto deshabilitará la validación de los valores pasados a los parámetros ContentType, Headers y UserAgent .
Esta característica se agregó en PowerShell 6.0.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SkipHttpErrorCheck
Este parámetro hace que el cmdlet ignore los estados de error HTTP y continúe procesando las respuestas. Las respuestas de error se escriben en la canalización como si fueran correctas.
Este parámetro se introdujo en PowerShell 7.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SslProtocol
Establece los protocolos SSL/TLS permitidos para la solicitud web. De forma predeterminada, se permiten los protocolos SSL/TLS admitidos por el sistema. SslProtocol permite limitar a protocolos específicos con fines de cumplimiento.
Estos valores se definen como una enumeración basada en marcas. Puede combinar varios valores para establecer varias marcas mediante este parámetro. Los valores se pueden pasar al parámetro SslProtocol como una matriz de valores o como una cadena separada por comas de esos valores. El cmdlet combinará 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.
Nota:
En plataformas que no son de Windows, es posible que no sea posible proporcionar Tls o Tls12 como opción. La compatibilidad con Tls13 no está disponible en todos los sistemas operativos y deberá comprobarse por sistema operativo.
Esta característica se agregó en PowerShell 6.0.0 y se agregó compatibilidad con Tls13 en PowerShell 7.1.
| Type: | WebSslProtocol |
| Accepted values: | Default, Tls, Tls11, Tls12, Tls13 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | 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 usa 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.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-TimeoutSec
Especifica cuánto tiempo puede estar pendiente la solicitud antes de que se agote el tiempo de espera. Escriba un valor en segundos. El valor predeterminado, 0, especifica un tiempo de espera indefinido.
Una consulta del Sistema de nombres de dominio (DNS) puede tardar hasta 15 segundos en devolverse o agotar el tiempo de espera. Si la solicitud contiene un nombre de host que requiere resolución y establece TimeoutSec en un valor mayor que cero, pero menos de 15 segundos, puede tardar 15 segundos o más antes de que se produzca una excepción WebException y la solicitud agote el tiempo de espera.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Token
Token de OAuth o Portador que se va a incluir en la solicitud. El token es necesario para determinadas opciones de autenticación . No se puede usar de forma independiente.
El token toma un SecureString 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.
| Type: | SecureString |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-TransferEncoding
Especifica un valor para el encabezado de respuesta HTTP de codificación de transferencia. Los valores permitidos para este parámetro son los siguientes:
- Fragmentado
- Compress
- 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
Este parámetro ha quedado en desuso. A partir de PowerShell 6.0.0, todas las solicitudes web solo usan el análisis básico. Este parámetro se incluye solo para la compatibilidad con versiones anteriores y cualquier uso de él no tendrá ningún efecto en el funcionamiento del cmdlet.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UseDefaultCredentials
Indica que el cmdlet usa las credenciales del usuario actual para enviar la solicitud web. Esto no se puede usar con autenticación o credencial y es posible que no se admita en todas las plataformas.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UserAgent
Especifica una cadena de agente de usuario para la solicitud web.
El agente de usuario predeterminado es similar a Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0 con ligeras variaciones para cada sistema operativo y plataforma.
Para probar un sitio web con la cadena de agente de usuario estándar que usa la mayoría de los exploradores de Internet, use las propiedades de la clase PSUserAgent , como Chrome, FireFox, InternetExplorer, Opera y Safari.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-WebSession
Especifica una sesión de solicitud web. Escriba el nombre de la variable, incluido el signo de dólar ($).
Para invalidar un valor en la sesión de solicitud web, use un parámetro de cmdlet, como UserAgent o Credential. Los valores de parámetro tienen prioridad sobre los valores de la sesión de solicitud web. Los encabezados relacionados con el contenido, como Content-Type, también se invalidarán cuando se proporcione un objeto MultipartFormDataContent para Body.
A diferencia de una sesión remota, la sesión de solicitud web no es una conexión persistente. Es un objeto que contiene información sobre la conexión y la solicitud, incluidas las cookies, las credenciales, el valor de redireccionamiento máximo y la cadena del agente de usuario. Puede usarlo para compartir el estado y los datos entre las solicitudes web.
Para crear una sesión de solicitud web, escriba un nombre de variable, sin un signo de dólar, en el valor del parámetro SessionVariable de un Invoke-RestMethod comando. 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.
| Type: | WebRequestSession |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Entradas
Puede canalizar el cuerpo de una solicitud web a este cmdlet.
Salidas
Cuando la solicitud devuelve un entero, este cmdlet devuelve ese entero.
Cuando la solicitud devuelve una cadena, este cmdlet devuelve esa cadena.
Cuando la solicitud devuelve XML válido, este cmdlet lo devuelve como 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 es diferente en función de la plataforma:
- Para Windows: lee la configuración de proxy de las variables de entorno o, si no se definen, de la configuración del proxy del usuario.
- Para macOS: lee la configuración de proxy de las variables de entorno o, si no se definen, de la configuración del proxy del sistema.
- Para Linux: lee la configuración de 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 que se usan para la inicialización de DefaultProxy en plataformas basadas en Windows y Unix son las siguientes:
HTTP_PROXY: el nombre de host o la dirección IP del servidor proxy utilizado en las solicitudes HTTP.HTTPS_PROXY: el nombre de host o la dirección IP del servidor proxy que se usa en las solicitudes HTTPS.ALL_PROXY: el nombre de host o la dirección IP del servidor proxy que se usa en las solicitudes HTTP y HTTPS en casoHTTP_PROXYdeHTTPS_PROXYque no estén definidos.NO_PROXY: una lista separada por comas de nombres de host que se deben excluir del proxy.
Vínculos relacionados
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de