Invoke-RestMethod

Sintaxis

StandardMethod (valor predeterminado)

Invoke-RestMethod
    [-Uri] <Uri>
    [-Method <WebRequestMethod>]
    [-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]
    [-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>]

StandardMethodNoProxy

Invoke-RestMethod
    [-Uri] <Uri>
    -NoProxy
    [-Method <WebRequestMethod>]
    [-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]
    [-TimeoutSec <Int32>]
    [-Headers <IDictionary>]
    [-MaximumRedirection <Int32>]
    [-MaximumRetryCount <Int32>]
    [-RetryIntervalSec <Int32>]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [-PreserveAuthorizationOnRedirect]
    [-SkipHeaderValidation]
    [<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]
    [-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>]

CustomMethodNoProxy

Invoke-RestMethod
    [-Uri] <Uri>
    -CustomMethod <String>
    -NoProxy
    [-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]
    [-TimeoutSec <Int32>]
    [-Headers <IDictionary>]
    [-MaximumRedirection <Int32>]
    [-MaximumRetryCount <Int32>]
    [-RetryIntervalSec <Int32>]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [-PreserveAuthorizationOnRedirect]
    [-SkipHeaderValidation]
    [<CommonParameters>]

Description

Ejemplos

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

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

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

Ejemplo 2: Ejecución de una solicitud POST

$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

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

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

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

$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

Ejemplo 5: Pasar varios encabezados

$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

$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

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

Ejemplo 8: Envío de una solicitud mediante HTTP 2.0

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

Parámetros

-AllowUnencryptedAuthentication

Permite el envío de credenciales y secretos a través de conexiones sin cifrar. De forma predeterminada, proporcionar una credencial o cualquier opción de autenticación con un URI que no comience con https:// dará como resultado 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.

Esta característica se agregó en PowerShell 6.0.0.

Propiedades de parámetro

Conjuntos de parámetros

-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 utilizará ninguna autenticación explícita.
• Basic: requiere credencial . Las credenciales se utilizarán para enviar un encabezado de autenticación Authorization: Basic básica RFC 7617 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 de parámetro

Conjuntos de parámetros

-Body

Especifica el cuerpo de la solicitud. El cuerpo es el contenido de la solicitud que sigue a los encabezados. También puede enviar un valor de cuerpo a Invoke-RestMethod.

El parámetro Body se puede usar para especificar una lista de parámetros de consulta o especificar el contenido de la respuesta.

Cuando la entrada es una solicitud 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 . Esto facilitará multipart/form-data las solicitudes. Cuando se proporciona un objeto MultipartFormDataContent para Body, los encabezados de contenido del objeto invalidarán los encabezados relacionados con el contenido proporcionados a los parámetros ContentType, Headers o MultipartFormDataContent. Esta característica se agregó en PowerShell 6.0.0.

Propiedades de parámetro

Conjuntos de parámetros

-Certificate

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

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

Propiedades de parámetro

Conjuntos de parámetros

-CertificateThumbprint

Especifica el certificado de clave pública digital (X509) de una cuenta de usuario que tiene permiso para enviar la solicitud. Ingrese la huella digital del certificado.

Los certificados se usan en la autenticación basada en certificados de cliente. 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.

Propiedades de parámetro

Conjuntos de parámetros

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

ContentType se invalidará cuando se proporcione un MultipartFormDataContent objeto para Body.

Propiedades de parámetro

Conjuntos de parámetros

-Credential

Especifica una cuenta de usuario que tiene permiso para enviar la solicitud. El valor predeterminado es el usuario actual.

Escriba un nombre de usuario, como User01 o Domain01\User01, o escriba un objeto de PSCredential generado por el cmdlet Get-Credential.

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

Propiedades de parámetro

Conjuntos de parámetros

-CustomMethod

Especifica el método personalizado que se usa para la solicitud web. Esto se puede usar con la opción Método de solicitud requerido por el punto de conexión no está disponible en el Método. Method 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 de parámetro

Conjuntos de parámetros

-DisableKeepAlive

Indica que el cmdlet establece el valor KeepAlive en el encabezado HTTP en False. De forma predeterminada, KeepAlive es verdadero. KeepAlive establece una conexión persistente con el servidor para facilitar las solicitudes posteriores.

Propiedades de parámetro

Conjuntos de parámetros

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

Propiedades de parámetro

Conjuntos de parámetros

-Form

Convierte un diccionario en un envío de multipart/form-data. Formulario no puede usarse con Cuerpo. Si se omitirá ContentType .

Las claves del diccionario se utilizará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 una lista, el campo for 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. 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 tags campo se proporcionará tres veces en el formulario, una para cada uno de Vacation, Italy, y 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.

Propiedades de parámetro

Conjuntos de parámetros

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

Propiedades de parámetro

Conjuntos de parámetros

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

Conjuntos de parámetros

-InFile

Obtiene el contenido de la solicitud web de un archivo.

Escriba una ruta de acceso y un nombre de archivo. Si omite la ruta de acceso, el valor predeterminado es la ubicación actual.

Propiedades de parámetro

Conjuntos de parámetros

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

Propiedades de parámetro

Conjuntos de parámetros

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

Conjuntos de parámetros

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

Propiedades de parámetro

Conjuntos de parámetros

-Method

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

• 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 de parámetro

Conjuntos de parámetros

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

Propiedades de parámetro

Conjuntos de parámetros

-OutFile

Guarda el cuerpo de la respuesta en el archivo de salida especificado. Escriba una ruta de acceso y un nombre de archivo. Si omite la ruta de acceso, el valor predeterminado es la ubicación actual. El nombre se trata como una ruta literal. Los nombres que contienen corchetes ([]) deben incluirse entre comillas simples (').

De forma predeterminada, Invoke-RestMethod devuelve los resultados a la canalización.

Propiedades de parámetro

Conjuntos de parámetros

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

Conjuntos de parámetros

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

Conjuntos de parámetros

-Proxy

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

Esta característica se agregó en PowerShell 6.0.0.

Propiedades de parámetro

Conjuntos de parámetros

-ProxyCredential

Especifica una cuenta de usuario que tiene permiso para usar el servidor proxy especificado por el parámetro Proxy . El valor predeterminado es el usuario actual.

Escriba un nombre de usuario, como User01 o Domain01\User01, 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 es usado en el comando. No puede usar los parámetros ProxyCredential y ProxyUseDefaultCredentials en el mismo comando.

Propiedades de parámetro

Conjuntos de parámetros

-ProxyUseDefaultCredentials

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

Propiedades de parámetro

Conjuntos de parámetros

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

Conjuntos de parámetros

-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, el archivo local se sobrescribirá y todo el archivo remoto se volverá a descargar por completo. Este comportamiento es el mismo que usar OutFile sin Reanudar.

Si el servidor remoto no admite la reanudación de la descarga, el archivo local se sobrescribirá y todo el archivo remoto se volverá a descargar por completo. Este comportamiento es el mismo que usar OutFile sin Reanudar.

Si el archivo local no existe, se creará el archivo local y se descargará completamente 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 de parámetro

Conjuntos de parámetros

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

Propiedades de parámetro

Conjuntos de parámetros

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

Conjuntos de parámetros

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

Esta característica se agregó en PowerShell 6.0.0.

Propiedades de parámetro

Conjuntos de parámetros

-SkipHeaderValidation

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

Este modificador debe usarse para sitios que requieren valores de encabezado que no se ajustan a 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.

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.

Propiedades de parámetro

Conjuntos de parámetros

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

Conjuntos de parámetros

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

Esta característica se agregó en PowerShell 6.0.0 y se agregó compatibilidad con Tls13 en PowerShell 7.1.

Propiedades de parámetro

Conjuntos de parámetros

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

Conjuntos de parámetros

-TimeoutSec

Especifica cuánto tiempo puede estar pendiente la solicitud antes de que se agote el tiempo de espera. Escriba un valor en segundos. El valor predeterminado, 0, especifica un tiempo de espera indefinido.

Una consulta del Sistema de nombres de dominio (DNS) puede tardar hasta 15 segundos en devolverse o agotar el tiempo de espera. Si la solicitud contiene un nombre de host que requiere resolución y establece TimeoutSec en un valor mayor que cero, pero inferior a 15 segundos, pueden pasar 15 segundos o más antes de que se produzca una WebException y se agote el tiempo de espera de la solicitud.

Propiedades de parámetro

Conjuntos de parámetros

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

Conjuntos de parámetros

-TransferEncoding

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

• Chunked
• Comprimir
• Deflate
• GZip
• identidad

Propiedades de parámetro

Conjuntos de parámetros

-Uri

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

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

Propiedades de parámetro

Conjuntos de parámetros

-UseBasicParsing

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.

Propiedades de parámetro

Conjuntos de parámetros

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

Conjuntos de parámetros

-UserAgent

Especifica una cadena de agente de usuario para la solicitud web.

El agente de usuario predeterminado es similar a Mozilla/5.0 (Windows NT 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 usan la mayoría de los navegadores de Internet, use las propiedades de la clase PSUserAgent , como Chrome, FireFox, InternetExplorer, Opera y Safari.

Propiedades de parámetro

Conjuntos de parámetros

-WebSession

Especifica una sesión de solicitud web. Escriba el nombre de la variable, incluido el signo de dólar ($).

Para invalidar un valor en la sesión de solicitud web, use un parámetro de cmdlet, como UserAgent o Credential. Los valores de parámetro tienen prioridad sobre los valores de la sesión de solicitud web. 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 comando Invoke-RestMethod. Invoke-RestMethod crea la sesión y la guarda en la variable . En los comandos posteriores, use la variable como valor del parámetro WebSession.

No puede usar los parámetros SessionVariable y WebSession en el mismo comando.

Propiedades de parámetro

Conjuntos de parámetros

CommonParameters

Entradas

Object

Salidas

Int64

String

XmlDocument

PSObject

Notas

Vínculos relacionados

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