Invoke-RestMethod

Permite o redirecionamento de HTTPS para HTTP. Por padrão, qualquer solicitação redirecionada de HTTPS para HTTP resulta em um erro e a solicitação é anulada para impedir a comunicação involuntária em texto simples por meio de conexões não criptografadas. Para substituir esse comportamento por sua conta e risco, use o parâmetro AllowInsecureRedirect .

Esse parâmetro foi adicionado no PowerShell 7.4.

Permite o envio de credenciais e segredos por meio de conexões não criptografadas. Por padrão, fornecer Credencial ou qualquer opção de Autenticação com um Uri que não comece resultará https:// em um erro e a solicitação será anulada para evitar a comunicação involuntária de segredos em texto sem formatação em conexões não criptografadas. Para substituir esse comportamento por sua conta e risco, forneça o parâmetro AllowUnencryptedAuthentication .

Esse recurso foi adicionado no PowerShell 6.0.0.

Especifica o tipo de autenticação explícito a ser usado para a solicitação. O padrão é Nenhum. O parâmetro Authentication não pode ser usado com o parâmetro UseDefaultCredentials .

Opções de autenticação disponíveis:

• None: Esta é a opção padrão quando a autenticação não é fornecida. Nenhuma autenticação explícita será usada.
• Basic: Requer credencial. As credenciais serão usadas para enviar um cabeçalho de autenticação Authorization: Basic básica RFC 7617 no formato .base64(user:password)
• Bearer: Requer o parâmetro Token . Envia um cabeçalho RFC 6750 Authorization: Bearer com o token fornecido.
• OAuth: Requer o parâmetro Token . Envia um cabeçalho RFC 6750 Authorization: Bearer com o token fornecido.

O fornecimento de autenticação substitui todos Authorization os cabeçalhos fornecidos aos cabeçalhos ou incluídos na WebSession.

Esse recurso foi adicionado no PowerShell 6.0.0.

Especifica o corpo da solicitação. O corpo é o conteúdo da solicitação que segue os cabeçalhos. Você também pode canalizar um valor de corpo para Invoke-RestMethod.

O parâmetro Body pode ser usado para especificar uma lista de parâmetros de consulta ou especificar o conteúdo da resposta. Para parâmetros de consulta, o cmdlet usa o método System.Net.WebUtility.UrlEncode para codificar os pares chave-valor. Para obter mais informações sobre a codificação de cadeias de caracteres para URLs, consulte a referência do método UrlEncode().

Quando a entrada é uma solicitação POST e o corpo é uma String, o valor à esquerda do primeiro sinal de igual (=) é definido como uma chave nos dados do formulário e o texto restante é definido como o valor. Para especificar várias chaves, use um objeto IDictionary , como uma tabela de hash, para o Body.

Quando a entrada é uma solicitação GET e o corpo é um IDictionary (normalmente, uma tabela de hash), o corpo é adicionado ao URI como parâmetros de consulta. Para outros tipos de solicitação (como PATCH), o corpo é definido como o valor do corpo da solicitação no formato padrão name=value com os valores codificados em URL.

Quando a entrada é um objeto System.Xml.XmlNode e a declaração XML especifica uma codificação, essa codificação é usada para os dados na solicitação, a menos que seja substituída pelo parâmetro ContentType .

Quando o corpo é um formulário ou é a saída de outra Invoke-WebRequest chamada, o PowerShell define o conteúdo da solicitação como os campos do formulário.

O parâmetro Body também pode aceitar um objeto System.Net.Http.MultipartFormDataContent . Isso facilitará multipart/form-data as solicitações. Quando um objeto MultipartFormDataContent é fornecido para Body, todos os cabeçalhos relacionados ao conteúdo fornecidos para os parâmetros ContentType, Headers ou WebSession serão substituídos pelos cabeçalhos de conteúdo do MultipartFormDataContent objeto. Esse recurso foi adicionado no PowerShell 6.0.0.

Especifica o certificado do cliente que é usado para uma solicitação da Web segura. Insira uma variável que contém um certificado, comando ou expressão que obtém os objetos.

Para localizar um certificado, use Get-PfxCertificate ou use o Get-ChildItem cmdlet na unidade Certificado (Cert:). Se o certificado não for válido ou não tiver autoridade suficiente, o comando falhará.

Especifica o certificado de chave pública digital (X509) de uma conta de usuário com permissão para executar essa solicitação. Insira a impressão digital do certificado.

Certificados digitais são empregados na autenticação de clientes baseada em certificados. Os certificados só podem ser mapeados apenas para contas de usuário locais, não para contas de domínio.

Para ver a impressão digital do certificado, use o Get-Item comando ou Get-ChildItem para localizar o certificado em Cert:\CurrentUser\My.

Especifica por quanto tempo a solicitação pode ficar pendente antes de atingir o tempo limite. Insira um valor em segundos. O valor padrão, 0, especifica um tempo limite indefinido.

Uma consulta DNS (Sistema de Nomes de Domínio) pode levar até 15 segundos para retornar ou atingir o tempo limite. Se sua solicitação contiver um nome de host que exija resolução e você definir ConnectionTimeoutSeconds como um valor maior que zero, mas menor que 15 segundos, poderá levar 15 segundos ou mais antes que uma WebException seja lançada e sua solicitação atinja o tempo limite.

Esse parâmetro substituiu o parâmetro TimeoutSec no PowerShell 7.4. Você pode usar TimeoutSec como um alias para ConnectionTimeoutSeconds.

Especifica o tipo de conteúdo da solicitação da Web.

Se o valor de ContentType contiver o formato de codificação (como charset), o cmdlet usará esse formato para codificar o corpo da solicitação da Web. Se o ContentType não especificar um formato de codificação, o formato de codificação padrão será usado. Um exemplo de um ContentType com um formato de codificação é text/plain; charset=iso-8859-5, que especifica o alfabeto latino/cirílico .

Se esse parâmetro for omitido e o método de solicitação for POST, Invoke-RestMethod definirá o tipo de conteúdo como application/x-www-form-urlencoded. Caso contrário, o tipo de conteúdo não será especificado na chamada.

ContentType será substituído quando um MultipartFormDataContent objeto for fornecido para Body.

A partir do PowerShell 7.4, se você usar esse parâmetro e o parâmetro Headers para definir o Content-Type cabeçalho, o valor especificado no parâmetro ContentType será usado.

Especifica uma conta de usuário com permissão para enviar a solicitação. O padrão é o usuário atual.

Digite um nome de usuário, como User01 ou Domain01\User01, ou insira um objeto PSCredential gerado pelo Get-Credential cmdlet.

A credencial pode ser usada sozinha ou em conjunto com determinadas opções de parâmetro de autenticação . Quando usado sozinho, ele só fornecerá credenciais ao servidor remoto se o servidor remoto enviar uma solicitação de desafio de autenticação. Quando usado com opções de autenticação , as credenciais serão enviadas explicitamente.

As credenciais são armazenadas em um objeto PSCredential e a senha é armazenada como um SecureString.

Especifica o método personalizado usado para a solicitação da Web. Isso pode ser usado com o método de solicitação exigido pelo ponto de extremidade não é uma opção disponível no método. Method e CustomMethod não podem ser usados juntos.

Exemplo:

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

Isso faz uma TEST solicitação HTTP para a API.

Esse recurso foi adicionado no PowerShell 6.0.0.

Indica que o cmdlet define o valor KeepAlive no cabeçalho HTTP como False. Por padrão, KeepAlive é True. KeepAlive estabelece uma conexão persistente com o servidor para facilitar as solicitações subsequentes.

Indica que o cmdlet deve seguir links de relação.

Algumas APIs REST dão suporte à paginação por meio de Links de Relação por RFC5988. Em vez de analisar o cabeçalho para obter a URL da próxima página, você pode fazer com que o cmdlet faça isso por você. Para definir quantas vezes seguir links de relação, use o parâmetro MaximumFollowRelLink .

Ao usar essa opção, o cmdlet retorna uma coleção de páginas de resultados. Cada página de resultados pode conter vários itens de resultado.

Esse recurso foi adicionado no PowerShell 6.0.0.

Converte um dicionário em um multipart/form-data envio. O formulário não pode ser usado com o corpo. Se ContentType será ignorado.

As chaves do dicionário serão usadas como nomes de campos de formulário. Por padrão, os valores de formulário serão convertidos em valores de cadeia de caracteres.

Se o valor for um objeto System.IO.FileInfo , o conteúdo do arquivo binário será enviado. O nome do arquivo será enviado como .filename O MIME será definido como application/octet-stream. Get-Item pode ser usado para simplificar o fornecimento do objeto System.IO.FileInfo .

$Form = @{ resume = Get-Item 'c:\Users\jdoe\Documents\John Doe.pdf' }

Se o valor for um tipo de coleção, como uma Matriz ou Lista, o campo for será enviado várias vezes. Os valores da lista serão tratados como strings por padrão. Se o valor for um objeto System.IO.FileInfo , o conteúdo do arquivo binário será enviado. Não há suporte para coleções aninhadas.

$Form = @{ tags = 'Férias', 'Itália', '2017' pictures = Get-ChildItem 'c:\Users\jdoe\Pictures\2017-Italy' }

No exemplo acima, o tags campo será fornecido três vezes no formulário, uma vez para cada um de Vacation, Italy, e 2017. O pictures campo também será enviado uma vez para cada arquivo na 2017-Italy pasta. O conteúdo binário dos arquivos nessa pasta será enviado como os valores.

Esse recurso foi adicionado no PowerShell 6.1.0.

Especifica os cabeçalhos da solicitação da Web. Insira uma tabela de hash ou dicionário.

Cabeçalhos relacionados ao conteúdo, como Content-Type são substituídos quando um MultipartFormDataContent objeto é fornecido para Body.

A partir do PowerShell 7.4, se você usar esse parâmetro para definir o cabeçalho e usar o Content-Type parâmetro ContentType, o valor especificado no parâmetro ContentType será usado.

Especifica a versão HTTP usada para a solicitação. O padrão é 1.1.

Os valores válidos são:

• 1.0
• 1,1
• 2,0
• 3.0

Obtém o conteúdo da solicitação da Web de um arquivo.

Digite um caminho e nome de arquivo. Se você omitir o caminho, o padrão será o local atual.

Especifica quantas vezes seguir links de relação se FollowRelLink for usado. Um valor menor pode ser necessário se a API REST for limitada devido a muitas solicitações. O valor padrão é [Int32]::MaxValue. Um valor de 0 (zero) impede os links de relação a seguir.

Especifica quantas vezes o PowerShell redireciona uma conexão para um URI (Uniform Resource Identifier) alternativo antes que a conexão falhe. O valor padrão é 5. Um valor de 0 (zero) impede qualquer redirecionamento.

Especifica quantas vezes o PowerShell tenta novamente uma conexão quando um código de falha entre 400 e 599, inclusive ou 304 é recebido. Além disso, consulte o parâmetro RetryIntervalSec para especificar o número de segundos entre as tentativas.

Especifica o método usado para a solicitação da Web. Os valores aceitáveis para esse parâmetro são:

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

O parâmetro CustomMethod pode ser usado para métodos de solicitação não listados acima.

Indica que o cmdlet não usará um proxy para chegar ao destino.

Quando você precisar ignorar o proxy configurado no Internet Explorer ou um proxy especificado no ambiente, use essa opção.

Esse parâmetro foi introduzido no PowerShell 6.0.

Esse tempo limite se aplica a leituras de dados em um fluxo, não ao tempo de fluxo como um todo. O valor padrão, 0, especifica um tempo limite indefinido.

Definir o valor como 30 segundos significa que qualquer atraso superior a 30 segundos entre os dados no fluxo encerra a solicitação. Um arquivo grande que leva vários minutos para ser baixado não será encerrado, a menos que o fluxo seja interrompido por mais de 30 segundos.

Por padrão, Invoke-RestMethod retorna os resultados para o pipeline. Quando você usa o parâmetro OutFile , os resultados são salvos no arquivo especificado e não retornados ao pipeline. Insira um caminho e um nome de arquivo. Para enviar os resultados para um arquivo e para o pipeline, adicione o parâmetro Passthru .

Se você omitir o caminho, o padrão será o local atual. O nome é tratado como um caminho literal. Os nomes que contêm colchetes ([]) devem ser colocados entre aspas simples (').

A partir do PowerShell 7.4, você pode especificar um caminho de pasta sem o nome do arquivo. Quando você fizer isso, o comando usará o nome do arquivo do último segmento do URI resolvido após qualquer redirecionamento. Ao especificar um caminho de pasta para OutFile, você não pode usar o parâmetro Resume .

Esse parâmetro é válido somente quando o parâmetro OutFile também é usado no comando. A intenção é ter os resultados gravados no arquivo e no pipeline.

Indica que o cmdlet deve preservar o Authorization cabeçalho, quando presente, entre redirecionamentos.

Por padrão, o cmdlet remove o Authorization cabeçalho antes de redirecionar. Especificar esse parâmetro desabilita essa lógica para casos em que o cabeçalho precisa ser enviado para o local de redirecionamento.

Esse recurso foi adicionado no PowerShell 6.0.0.

Indica que o cmdlet deve preservar o método da solicitação entre redirecionamentos.

Por padrão, o cmdlet altera o método para GET quando redirecionado. Especificar esse parâmetro desabilita essa lógica para garantir que o método pretendido possa ser usado com redirecionamento.

Esse recurso foi adicionado no PowerShell 7.4.

Usa um servidor proxy para a solicitação, em vez de se conectar diretamente ao recurso da Internet. Insira o URI (Uniform Resource Identifier) de um servidor proxy de rede.

Esse recurso foi adicionado no PowerShell 6.0.0.

Especifica uma conta de usuário que tem permissão para usar o servidor proxy especificado pelo parâmetro Proxy . O padrão é o usuário atual.

Digite um nome de usuário, como User01 ou Domain01\User01, User@Domain.Comou insira um PSCredential objeto, como um gerado pelo Get-Credential cmdlet.

Esse parâmetro é válido somente quando o parâmetro Proxy também é usado no comando. Você não pode usar os parâmetros ProxyCredential e ProxyUseDefaultCredentials no mesmo comando.

Indica que o cmdlet usa as credenciais do usuário atual para acessar o servidor proxy especificado pelo parâmetro Proxy .

Esse parâmetro é válido somente quando o parâmetro Proxy também é usado no comando. Você não pode usar os parâmetros ProxyCredential e ProxyUseDefaultCredentials no mesmo comando.

Cria uma variável que contém um Dicionário de Cabeçalhos de Resposta. Insira um nome de variável sem o símbolo do cifrão ($). As chaves do dicionário contêm os nomes de campo e os valores do Cabeçalho de Resposta retornado pelo servidor Web.

Esse recurso foi adicionado no PowerShell 6.0.0.

Executa uma tentativa de melhor esforço para retomar o download de um arquivo parcial. O parâmetro Resume requer o parâmetro OutFile .

O Resume opera apenas no tamanho do arquivo local e do arquivo remoto e não executa nenhuma outra validação de que o arquivo local e o arquivo remoto são iguais.

Se o tamanho do arquivo local for menor que o tamanho do arquivo remoto, o cmdlet tentará retomar o download do arquivo e acrescentar os bytes restantes ao final do arquivo.

Se o tamanho do arquivo local for igual ao tamanho do arquivo remoto, nenhuma ação será executada e o cmdlet pressupõe que o download já foi concluído.

Se o tamanho do arquivo local for maior que o tamanho do arquivo remoto, o arquivo local será substituído e todo o arquivo remoto será completamente baixado novamente. Esse comportamento é o mesmo que usar OutFile sem Resume.

Se o servidor remoto não suportar a retomada do download, o arquivo local será substituído e todo o arquivo remoto será completamente baixado novamente. Esse comportamento é o mesmo que usar OutFile sem Resume.

Se o arquivo local não existir, o arquivo local será criado e todo o arquivo remoto será completamente baixado. Esse comportamento é o mesmo que usar OutFile sem Resume.

Esse recurso foi adicionado no PowerShell 6.1.0.

Especifica o intervalo entre as tentativas da conexão quando um código de falha entre 400 e 599, inclusive ou 304 é recebido. O valor deve estar entre 1 e [int]::MaxValue. Quando o código de falha é 429 e a resposta inclui a propriedade Retry-After em seus cabeçalhos, o cmdlet usa esse valor para o intervalo de repetição, mesmo que esse parâmetro seja especificado.

Além disso, consulte o parâmetro MaximumRetryCount para especificar o número de novas tentativas.

Cria uma variável que contém a sessão de solicitação da Web. Insira um nome de variável sem o símbolo do cifrão ($).

Quando você especifica uma variável de sessão, Invoke-RestMethod cria um objeto de sessão de solicitação da Web e o atribui a uma variável com o nome especificado em sua sessão do PowerShell. Você pode usar a variável na sessão, assim que o comando for concluído.

Antes do PowerShell 7.4, a sessão de solicitação da Web não é uma conexão persistente. É um objeto que contém informações sobre a conexão e a solicitação, incluindo cookies, credenciais, o valor máximo de redirecionamento e a cadeia de caracteres do agente do usuário. Você pode usá-lo para compartilhar o estado e os dados entre solicitações da Web.

A partir do PowerShell 7.4, a sessão de solicitação da Web é persistente, desde que as propriedades da sessão não sejam substituídas em uma solicitação subsequente. Quando estiverem, o cmdlet recriará a sessão com os novos valores. As sessões persistentes reduzem a sobrecarga de solicitações repetidas, tornando-as muito mais rápidas.

Para usar a sessão de solicitação da Web em solicitações da Web subsequentes, especifique a variável de sessão no valor do parâmetro WebSession . O PowerShell usa os dados no objeto de sessão de solicitação da Web ao estabelecer a nova conexão. Para substituir um valor na sessão de solicitação da Web, use um parâmetro de cmdlet, como UserAgent ou Credential. Valores de parâmetro têm precedência sobre valores na seção de solicitação da Web.

Você não pode usar os parâmetros SessionVariable e WebSession no mesmo comando.

Ignora as verificações de validação de certificado que incluem todas as validações, como expiração, revogação, autoridade raiz confiável etc.

Esse recurso foi adicionado no PowerShell 6.0.0.

Indica que o cmdlet deve adicionar cabeçalhos à solicitação sem validação.

Essa opção deve ser usada para sites que exigem valores de cabeçalho que não estão em conformidade com os padrões. Especificar essa opção desabilita a validação para permitir que o valor seja passado desmarcado. Quando especificado, todos os cabeçalhos são adicionados sem validação.

Isso desabilitará a validação de valores passados para os parâmetros ContentType, Headers e UserAgent .

Esse recurso foi adicionado no PowerShell 6.0.0.

Esse parâmetro faz com que o cmdlet ignore os status de erro HTTP e continue a processar respostas. As respostas de erro são gravadas no pipeline como se fossem bem-sucedidas.

Esse parâmetro foi introduzido no PowerShell 7.

Define os protocolos SSL/TLS permitidos para a solicitação da Web. Por padrão, todos os protocolos SSL/TLS suportados pelo sistema são permitidos. O SslProtocol permite limitar a protocolos específicos para fins de conformidade.

Esses valores são definidos como uma enumeração baseada em sinalizador. Você pode combinar vários valores para definir vários sinalizadores usando esse parâmetro. Os valores podem ser passados para o parâmetro SslProtocol como uma matriz de valores ou como uma cadeia de caracteres separada por vírgulas desses valores. O cmdlet combinará os valores usando uma operação OR binária. Passar valores como uma matriz é a opção mais simples e também permite que você use o preenchimento de tabulação nos valores. Talvez você não consiga fornecer vários valores em todas as plataformas.

Esse recurso foi adicionado no PowerShell 6.0.0 e o suporte foi Tls13 adicionado no PowerShell 7.1.

Cria uma variável que contém um resultado de código de status HTTP da solicitação. Insira um nome de variável sem o símbolo do cifrão ($).

O parâmetro pode identificar mensagens de êxito ou mensagens de falha quando usado com o parâmetro SkipHttpErrorCheck .

Insira o nome da variável do parâmetro como uma cadeia de caracteres, como -StatusCodeVariable "scv".

Esse parâmetro foi introduzido no PowerShell 7.

O token OAuth ou Bearer a ser incluído na solicitação. O token é exigido por determinadas opções de autenticação . Não pode ser usado de forma independente.

Token recebe um SecureString que contém o token. Para fornecer o token, use manualmente o seguinte:

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

Esse parâmetro foi introduzido no PowerShell 6.0.

Especifica um valor para o cabeçalho de resposta HTTP de codificação de transferência. Os valores aceitáveis para esse parâmetro são:

• Blocos
• Compress
• Deflacionar
• GZip
• Identidade

Especifica o nome do soquete Unix ao qual se conectar. Esse parâmetro tem suporte em sistemas baseados em Unix e Windows versão 1803 e posterior. Para obter mais informações sobre o suporte do Windows a soquetes Unix, consulte a postagem no blog Interoperabilidade do Windows/WSL com AF_UNIX .

Esse parâmetro foi adicionado no PowerShell 7.4.

Especifica o URI (Uniform Resource Identifier) do recurso da Internet para o qual a solicitação da Web é enviada. Esse parâmetro oferece suporte a valores HTTP, HTTPS, FTP e FILE.

Este parâmetro é obrigatório. O nome do parâmetro (Uri) é opcional.

Esse parâmetro foi descontinuado. A partir do PowerShell 6.0.0, todas as solicitações da Web usam apenas a análise básica. Esse parâmetro é incluído apenas para compatibilidade com versões anteriores e qualquer uso dele não terá efeito sobre a operação do cmdlet.

Indica que o cmdlet usa as credenciais do usuário atual para enviar a solicitação da Web. Isso não pode ser usado com autenticação ou credencial e pode não ser compatível com todas as plataformas.

Especifica uma cadeia de caracteres de agente do usuário para a solicitação da web.

O agente de usuário padrão é semelhante a Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0 com pequenas variações para cada sistema operacional e plataforma.

Para testar um site com a cadeia de caracteres de agente de usuário padrão usada pela maioria dos navegadores da Internet, use as propriedades da classe PSUserAgent , como Chrome, FireFox, InternetExplorer, Opera e Safari.

Especifica uma sessão de solicitação da Web. Insira o nome da variável, incluindo o cifrão ($).

Para substituir um valor na sessão de solicitação da Web, use um parâmetro de cmdlet, como UserAgent ou Credential. Valores de parâmetro têm precedência sobre valores na seção de solicitação da Web. Cabeçalhos relacionados ao conteúdo, como Content-Type, também serão substituídos quando um objeto MultipartFormDataContent for fornecido para Body.

Ao contrário de uma sessão remota, a sessão de solicitação da Web não é uma conexão persistente. É um objeto que contém informações sobre a conexão e a solicitação, incluindo cookies, credenciais, o valor máximo de redirecionamento e a cadeia de caracteres do agente do usuário. Você pode usá-lo para compartilhar o estado e os dados entre solicitações da Web.

Para criar uma sessão de solicitação da Web, insira um nome de variável, sem um cifrão, no valor do parâmetro SessionVariable de um Invoke-RestMethod comando. Invoke-RestMethod cria a sessão e a salva na variável. Nos comandos subsequentes, use a variável como o valor do parâmetro WebSession .

Você não pode usar os parâmetros SessionVariable e WebSession no mesmo comando.