Invoke-RestMethod

Ссылка

Модуль:: Microsoft.PowerShell.Utility

Отправляет запрос HTTP или HTTPS в веб-службу RESTful.

Синтаксис

Invoke-RestMethod
      [-Method <WebRequestMethod>]
      [-FollowRelLink]
      [-MaximumFollowRelLink <Int32>]
      [-ResponseHeadersVariable <String>]
      [-StatusCodeVariable <String>]
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-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>
      [-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>
      [-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>
      [-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 отправляет http- и HTTPS-запросы в веб-службы передачи репрезентативного состояния (REST), возвращающие структурированные данные.

PowerShell форматирует ответ на основе типа данных. Для rss или atom-канала PowerShell возвращает XML-узлы Item или Entry. Для нотации объектов JavaScript (JSON) или XML PowerShell преобразует или десериализует содержимое в [PSCustomObject] объекты.

Примечание

Когда конечная точка REST возвращает несколько объектов, объекты получаются в виде массива. Если передать выходные данные из Invoke-RestMethod в другую команду, они отправляются в виде одного [Object[]] объекта. Содержимое этого массива не перечисляется для следующей команды в конвейере.

Этот командлет впервые появился в Windows PowerShell 3.0.

Начиная с PowerShell 7.0, поддерживает конфигурацию прокси-сервера, Invoke-RestMethod определяемую переменными среды. См. раздел Примечания этой статьи.

Примеры

Пример 1. Получение RSS-канала PowerShell

В этом примере используется Invoke-RestMethod командлет для получения сведений из RSS-канала блога PowerShell. Команда использует Format-Table командлет для отображения значений свойств Title и pubDate каждого блога в таблице.

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

Пример 2. Выполнение запроса POST

В этом примере пользователь выполняет Invoke-RestMethod запрос 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

Учетные данные запрашиваются, а затем сохраняются в $Cred , а URL-адрес, к которому будет осуществляться доступ, определяется в $Url.

Переменная $Body описывает условия поиска, задает CSV в качестве режима вывода и указывает период времени для возвращаемых данных, который начинается два дня назад и заканчивается один день назад. Переменная body задает значения для параметров, которые применяются к конкретному REST API, с которым Invoke-RestMethod взаимодействует.

Команда Invoke-RestMethod выполняется со всеми переменными, указывая путь и имя файла для полученного выходного CSV-файла.

Пример 3. Переход по ссылкам на связь

Некоторые ИНТЕРФЕЙСы REST API поддерживают разбиение на страницы по реляционным ссылкам для каждого RFC5988. Вместо синтаксического анализа заголовка, чтобы получить URL-адрес следующей страницы, вы можете заставить командлет сделать это за вас. В этом примере возвращаются первые две страницы проблем из репозитория PowerShell на GitHub.

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

Пример 4. Упрощенная отправка нескольких частей или форм-данных

Некоторые API требуют 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

Для формы профиля требуются следующие поля: firstName, lastName, email, avatar, birthdayи hobbies. API ожидает, что в avatar поле будет предоставлено изображение для изображения профиля пользователя. API также принимает несколько hobbies записей для отправки в одной форме.

При создании $Form HashTable имена ключей используются в качестве имен полей формы. По умолчанию значения HashTable будут преобразованы в строки. System.IO.FileInfo Если имеется значение, будет отправлено содержимое файла. Если коллекция, например массивы или списки, присутствует, поле формы будет отправлено несколько раз.

При использовании Get-Item в avatar ключе FileInfo объект будет задан в качестве значения. В результате будут отправлены данные изображения для jdoe.png .

При предоставлении списка в hobbies ключ hobbies поле будет присутствовать в отправке один раз для каждого элемента списка.

Пример 5. Передача нескольких заголовков

API часто требуют переданные заголовки для проверки подлинности или проверки. В этом примере показано, как передать несколько заголовков из в hash-table REST API.

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

Пример 6. Перечисление возвращенных элементов в конвейере

GitHub возвращает несколько объектов массива. Если передать выходные данные в другую команду, они отправляются в виде одного [Object[]]объекта.

Чтобы перечислить объекты в конвейер, передайте результаты Write-Output в или заключите командлет в круглые скобки. В следующем примере подсчитывается количество объектов, возвращаемых GitHub. Затем подсчитывает количество объектов, перечисленных в конвейере.

$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

Параметры

-AllowUnencryptedAuthentication

Позволяет отправлять учетные данные и секреты через незашифрованные подключения. По умолчанию предоставление учетных данных или любого параметра проверки подлинности с URI , который не начинается с https:// , приведет к ошибке, и запрос прервется, чтобы предотвратить непреднамеренное сообщение секретов в виде обычного текста через незашифрованные подключения. Чтобы переопределить это поведение на свой страх и риск, укажите параметр AllowUnencryptedAuthentication .

Предупреждение

Использование этого параметра не является безопасным и не рекомендуется. Он предоставляется только для обеспечения совместимости с устаревшими системами, которые не могут предоставлять зашифрованные подключения. Используйте на свой страх и риск.

Эта функция была добавлена в PowerShell 6.0.0.

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

-Authentication

Указывает явный тип проверки подлинности, используемый для запроса. Значение по умолчанию — None. Параметр Authentication нельзя использовать с параметром UseDefaultCredentials .

Доступные параметры проверки подлинности:

None: это параметр по умолчанию, если проверка подлинности не указана. Явная проверка подлинности не будет использоваться.
Basic: требуются учетные данные. Учетные данные будут использоваться для отправки заголовка обычной проверки подлинности Authorization: Basic RFC 7617 в формате base64(user:password).
Bearer: требуется параметр Token . Отправляет заголовок RFC 6750 Authorization: Bearer с предоставленным маркером.
OAuth: требуется параметр Token . Отправляет заголовок RFC 6750 Authorization: Bearer с предоставленным маркером.

Предоставление проверки подлинности переопределяет все Authorization заголовки , поставляемые в заголовки или включенные в WebSession.

Эта функция была добавлена в 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

Задает основной текст запроса. Основной текст — это содержимое запроса, идущее после заголовков. Вы также можете передать значение основного текста в Invoke-RestMethod.

Параметр Body используется для указания списка параметров запроса или указания содержимого ответа.

Если входные данные являются запросом GET и текстом IDictionary является (как правило, хэш-таблица), текст добавляется в универсальный код ресурса (URI) в качестве параметров запроса. Для других типов запросов (таких как POST) основной текст задается как значение основного текста запроса в стандартном формате имя=значение.

Если текст является формой или выходными данными другого Invoke-WebRequest вызова, PowerShell задает для содержимого запроса поля формы.

Параметр Body также может принимать объект System.Net.Http.MultipartFormDataContent . Это упростит multipart/form-data запросы. Когда объект MultipartFormDataContent предоставляется для body, все связанные с содержимым заголовки, предоставленные параметрам ContentType, Headers или WebSession , будут переопределены заголовками содержимого MultipartFormDataContent объекта. Эта функция была добавлена в PowerShell 6.0.0.

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

-Certificate

Задает сертификат клиента, который используется для выполнения защищенного веб-запроса. Введите переменную, которая содержит сертификат, или команду или выражение, которое возвращает сертификат.

Чтобы найти сертификат, используйте Get-PfxCertificate командлет Get-ChildItem на диске Сертификат (Cert:). Если сертификат недействителен или не имеет достаточных полномочий, команда завершается ошибкой.

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

-CertificateThumbprint

Задает цифровой сертификат с открытым ключом (X509) учетной записи пользователя, который располагает разрешением для отправки запроса. Введите отпечаток сертификата.

Сертификаты используются при проверке подлинности на основе сертификата клиента. Они могут сопоставляться только с учетными записями локальных пользователей и не работают с учетными записями доменов.

Чтобы получить отпечаток сертификата, используйте Get-Item команду или Get-ChildItem на диске PowerShell Cert: .

Примечание

В настоящее время эта функция поддерживается только на платформах ОС Windows.

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

-ContentType

Задает тип содержимого веб-запроса.

Если этот параметр опущен, а метод запроса — POST, Invoke-RestMethod присваивает типу контента значение application/x-www-form-urlencoded. В противном случае тип контента не указан в вызове .

ContentType будет переопределен при указании MultipartFormDataContent объекта для body.

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

-Credential

Указывает учетную запись пользователя, обладающую разрешением для отправки запроса. По умолчанию используется текущий пользователь.

Введите имя пользователя, например User01 или Domain01\User01, или введите объект PSCredential , созданный командлетом Get-Credential .

Учетные данные можно использовать отдельно или в сочетании с определенными параметрами параметров проверки подлинности . При использовании в одиночку он будет предоставлять учетные данные на удаленный сервер только в том случае, если удаленный сервер отправляет запрос проверки подлинности. При использовании с параметрами проверки подлинности учетные данные будут отправлены явным образом.

Учетные данные хранятся в объекте PSCredential , а пароль хранится как SecureString.

Примечание

Дополнительные сведения о защите данных SecureString см. в разделе Насколько безопасно SecureString?.

Type:	PSCredential
Position:	Named
Default value:	Current user
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-CustomMethod

Задает пользовательский метод, используемый для веб-запроса. Это можно использовать с параметром Request Method , необходимым для конечной точки, недоступен в методе . Метод иCustomMethod нельзя использовать вместе.

Пример

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

При этом выполняется TEST HTTP-запрос к API.

Эта функция была добавлена в PowerShell 6.0.0.

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

-DisableKeepAlive

Указывает, что командлет устанавливает значение KeepAlive в заголовке HTTP в значение False. По умолчанию KeepAlive имеет значение True. KeepAlive устанавливает постоянное подключение к серверу, чтобы упростить выполнение последующих запросов.

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

-FollowRelLink

Указывает, что командлет должен переходить по ссылкам для связи.

Некоторые ИНТЕРФЕЙСы REST API поддерживают разбиение на страницы по реляционным ссылкам для каждого RFC5988. Вместо синтаксического анализа заголовка, чтобы получить URL-адрес следующей страницы, вы можете заставить командлет сделать это за вас. Чтобы указать, сколько раз следует переходить по ссылкам, используйте параметр MaximumFollowRelLink .

При использовании этого параметра командлет возвращает коллекцию страниц результатов. Каждая страница результатов может содержать несколько элементов результатов.

Эта функция была добавлена в PowerShell 6.0.0.

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

-Form

Преобразует словарь в отправку multipart/form-data . Форма не может использоваться с текстом. Значение , если ContentType будет игнорироваться.

Ключи словаря будут использоваться в качестве имен полей формы. По умолчанию значения формы преобразуются в строковые значения.

Если значением является объект System.IO.FileInfo , будет отправлено содержимое двоичного файла. Имя файла будет отправлено как filename. MIME будет иметь значение application/octet-stream. Get-Item можно использовать для упрощения предоставления объекта System.IO.FileInfo .

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

Если значение является типом коллекции, например Array или List, поле for будет отправлено несколько раз. По умолчанию значения списка будут рассматриваться как строки. Если значением является объект System.IO.FileInfo , будет отправлено содержимое двоичного файла. Вложенные коллекции не поддерживаются.

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

В приведенном выше примере tags поле будет предоставлено три раза в форме, один раз для каждого из Vacation, Italyи 2017. Поле pictures также будет отправлено один раз для каждого файла в папке 2017-Italy . Двоичное содержимое файлов в этой папке будет отправлено в виде значений.

Эта функция была добавлена в PowerShell 6.1.0.

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

-Headers

Задает заголовки веб-запроса. Введите словарь или хэш-таблицу.

Чтобы задать заголовки UserAgent, используйте параметр UserAgent. Этот параметр нельзя использовать для указания User-Agent заголовков файлов cookie или .

Заголовки, связанные с содержимым, например Content-Type , будут переопределены при MultipartFormDataContent указании объекта для body.

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

-InFile

Получает содержимое веб-запроса из файла.

Введите путь и имя файла. Если путь не указан, по умолчанию используется текущее расположение.

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

-MaximumFollowRelLink

Указывает, сколько раз следует переходить по реляционным ссылкам при использовании FollowRelLink . Если API REST регулируется из-за слишком большого количества запросов, может потребоваться меньшее значение. Значение по умолчанию — [Int32]::MaxValue. Значение 0 (ноль) не позволяет переходить по связям.

Type:	Int32
Aliases:	ML
Position:	Named
Default value:	Int32.MaxValue
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MaximumRedirection

Указывает, сколько раз PowerShell перенаправляет подключение на альтернативный универсальный код ресурса (URI) до сбоя подключения. Значение по умолчанию — 5. Значение 0 (ноль) запрещает любые перенаправления.

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

-MaximumRetryCount

Указывает, сколько раз PowerShell повторяет подключение при получении кода сбоя от 400 до 599 включительно или 304. Также см . параметр RetryIntervalSec для указания количества повторных попыток.

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

-Method

Задает метод, используемый для веб-запроса. Допустимые значения для этого параметра:

Default
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace

Параметр CustomMethod можно использовать для методов запроса, не перечисленных выше.

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

Указывает, что командлет не будет использовать прокси-сервер для достижения назначения.

Если необходимо обойти прокси-сервер, настроенный в Обозреватель Интернета, или прокси-сервер, указанный в среде, используйте этот параметр.

Этот параметр появился в PowerShell 6.0.

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

-OutFile

Сохраняет основной текст ответа в указанный выходной файл. Введите путь и имя файла. Если путь не указан, по умолчанию используется текущее расположение. Имя обрабатывается как литеральный путь. Имена, содержащие квадратные скобки ([]), должны быть заключены в одинарные кавычки (').

По умолчанию Invoke-RestMethod возвращает результаты в конвейер.

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

-PassThru

Этот параметр активен, если в команде также используется параметр OutFile. Цель состоит в том, чтобы результаты записылись в файл и в конвейер.

Примечание

При использовании параметра PassThru выходные данные записываются в конвейер, но файл не создается. Дополнительные сведения см. в статье Проблема с PowerShell No 15409.

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

-PreserveAuthorizationOnRedirect

Указывает, что командлет должен сохранять Authorization заголовок при его наличии в перенаправлениях.

По умолчанию командлет удаляет Authorization заголовок перед перенаправлением. Указание этого параметра отключает эту логику в случаях, когда заголовок необходимо отправить в расположение перенаправления.

Эта функция была добавлена в PowerShell 6.0.0.

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

-Proxy

Использует прокси-сервер для запроса, а не напрямую подключаться к интернет-ресурсу. Введите универсальный код ресурса (URI) сетевого прокси-сервера.

Эта функция была добавлена в PowerShell 6.0.0.

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

-ProxyCredential

Указывает учетную запись пользователя, имеющую разрешение на использование прокси-сервера, который задается параметром Proxy. По умолчанию используется текущий пользователь.

Введите имя пользователя, например User01 или Domain01\User01, User@Domain.Comили введите PSCredential объект, например созданный командлетом Get-Credential .

Этот параметр действителен только в том случае, если параметр Proxy также используется в команде . В одной команде нельзя использовать параметры ProxyCredential и ProxyUseDefaultCredentials .

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

-ProxyUseDefaultCredentials

Указывает, что командлет использует учетные данные текущего пользователя для доступа к прокси-серверу, указанному параметром Proxy .

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

-ResponseHeadersVariable

Создает переменную, содержащую словарь заголовков ответов. Введите имя переменной без символа доллара ($). Ключи словаря содержат имена полей и значения заголовка ответа, возвращаемого веб-сервером.

Эта функция была добавлена в PowerShell 6.0.0.

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

-Resume

Выполняет все возможное, чтобы возобновить загрузку частичного файла. Для параметра Resume требуется параметр OutFile .

Функция Resume работает только с размером локального и удаленного файлов и не проверяет, совпадают ли локальные и удаленные файлы.

Если размер локального файла меньше размера удаленного файла, командлет попытается возобновить загрузку файла и добавить оставшиеся байты в конец файла.

Если размер локального файла совпадает с размером удаленного файла, никакие действия не выполняются и командлет предполагает, что скачивание уже завершено.

Если размер локального файла больше, чем размер удаленного файла, локальный файл будет перезаписан, а весь удаленный файл будет полностью загружен повторно. Это поведение аналогично использованию OutFile без resume.

Если удаленный сервер не поддерживает возобновление загрузки, локальный файл будет перезаписан, а весь удаленный файл будет полностью загружен повторно. Это поведение аналогично использованию OutFile без resume.

Если локальный файл не существует, локальный файл будет создан и весь удаленный файл будет полностью загружен. Это поведение аналогично использованию OutFile без resume.

Эта функция была добавлена в PowerShell 6.1.0.

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

-RetryIntervalSec

Указывает интервал между повторными попытками подключения при получении кода сбоя в диапазоне от 400 до 599 включительно или 304. См. также параметр MaximumRetryCount , чтобы указать количество повторных попыток.

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

-SessionVariable

Создает переменную, содержащую сеанс веб-запроса. Введите имя переменной без символа доллара ($).

При указании переменной Invoke-RestMethod сеанса создает объект сеанса веб-запроса и назначает его переменной с указанным именем в сеансе PowerShell. Переменную в сеансе можно использовать сразу после выполнения команды.

В отличие от удаленного сеанса, сеанс веб-запроса не является постоянным подключением. Это объект, содержащий сведения о подключении и запросе, включая файлы cookie, учетные данные, максимальное значение перенаправления и строку агента пользователя. Его можно использовать для обмена состоянием и данными между веб-запросами.

Чтобы использовать сеанс веб-запроса в последующих веб-запросах, укажите переменную сеанса в значении параметра WebSession. При установке нового подключения PowerShell использует данные в объекте сеанса веб-запроса. Чтобы переопределить значение в сеансе веб-запроса, используйте параметр командлета, такой как UserAgent или Credential. Значения параметров имеют приоритет над значениями в сеансе веб-запроса.

Параметры SessionVariable и WebSession нельзя использовать в одной команде.

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

-SkipCertificateCheck

Пропускает проверки сертификатов, которые включают все проверки, такие как срок действия, отзыв, доверенный корневой центр и т. д.

Предупреждение

Использование этого параметра не является безопасным и не рекомендуется. Этот параметр предназначен только для известных узлов, использующих самозаверяющий сертификат для тестирования. Используйте на свой страх и риск.

Эта функция была добавлена в PowerShell 6.0.0.

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

-SkipHeaderValidation

Указывает, что командлет должен добавлять заголовки в запрос без проверки.

Этот параметр следует использовать для сайтов, которым требуются значения заголовков, которые не соответствуют стандартам. При указании этого параметра проверка отключается, чтобы разрешить передавать значение без флажка. При указании все заголовки добавляются без проверки.

Это приведет к отключению проверки значений, передаваемых в параметры ContentType, Headers и UserAgent .

Эта функция была добавлена в PowerShell 6.0.0.

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

-SkipHttpErrorCheck

Этот параметр приводит к тому, что командлет игнорирует состояния ошибок HTTP и продолжает обрабатывать ответы. Ответы об ошибках записываются в конвейер так же, как если бы они были успешными.

Этот параметр появился в PowerShell 7.

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

-SslProtocol

Задает протоколы SSL/TLS, допустимые для веб-запроса. По умолчанию разрешены все протоколы SSL/TLS, поддерживаемые системой. SslProtocol позволяет ограничиться определенными протоколами для обеспечения соответствия требованиям.

Эти значения определяются как перечисление на основе флагов. С помощью этого параметра можно объединить несколько значений, чтобы задать несколько флагов. Значения могут передаваться в параметр SslProtocol в виде массива значений или в виде строки этих значений, разделенной запятыми. Командлет объединит значения с помощью операции binary-OR. Передача значений в виде массива является самым простым вариантом, а также позволяет использовать заполнение табуляции для значений. Возможно, вы не сможете указать несколько значений на всех платформах.

Примечание

На платформах, отличных от Windows, может быть невозможно предоставить Tls или Tls12 в качестве варианта. Tls13 Поддержка доступна не во всех операционных системах и должна быть проверена для каждой операционной системы.

Эта функция была добавлена в PowerShell 6.0.0, а поддержка Tls13 добавлена в 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

Создает переменную, содержащую результат кода состояния HTTP запроса. Введите имя переменной без символа доллара ($).

Параметр может определять сообщения об успешном выполнении или сбое при использовании с параметром SkipHttpErrorCheck .

Введите имя переменной параметра в виде строки, -StatusCodeVariable "scv"например .

Этот параметр появился в PowerShell 7.

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

-TimeoutSec

Указывает, как долго запрос может находиться в ожидании до истечения времени ожидания. Введите значение в секундах. Значение по умолчанию, равное 0, указывает неопределенное время ожидания.

Для возврата запроса системы доменных имен (DNS) может потребоваться до 15 секунд. Если запрос содержит имя узла, требующее разрешения, и для параметра TimeoutSec задано значение больше нуля, но менее 15 секунд, может потребоваться 15 секунд или более, прежде чем будет создано исключение WebException, а время ожидания запроса истекает.

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

-Token

Токен OAuth или Bearer для включения в запрос. Маркер требуется для определенных вариантов проверки подлинности . Его нельзя использовать отдельно.

Маркер принимает объект , SecureString содержащий маркер. Чтобы указать маркер, вручную используйте следующее:

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

Этот параметр появился в PowerShell 6.0.

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

-TransferEncoding

Задает значение для заголовка transfer-encoding ответа HTTP. Допустимые значения для этого параметра:

Фрагментированные
Сжать
Deflate
GZip
Идентификация

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

Указывает универсальный код ресурса (URI) интернет-ресурса, которому отправляется веб-запрос. Этот параметр поддерживает значения HTTP, HTTPS, FTP и FILE.

Это обязательный параметр. Имя параметра (URI) является необязательным.

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

-UseBasicParsing

Этот параметр устарел. Начиная с PowerShell 6.0.0 все веб-запросы используют только базовый анализ. Этот параметр включен только для обратной совместимости, и любое его использование не повлияет на работу командлета.

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

-UseDefaultCredentials

Указывает, что командлет использует учетные данные текущего пользователя для отправки веб-запроса. Это не может использоваться с проверкой подлинности или учетными данными и может поддерживаться не на всех платформах.

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

-UserAgent

Указывает строку агента пользователя для веб-запроса.

Агент пользователя по умолчанию похож на с Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0 небольшими различиями для каждой операционной системы и платформы.

Чтобы протестировать веб-сайт со стандартной строкой агента пользователя, используемой большинством браузеров, используйте свойства класса PSUserAgent , такие как Chrome, FireFox, InternetExplorer, Opera и Safari.

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

-WebSession

Указывает сеанс веб-запроса. Введите имя переменной, включая знак доллара ($).

Чтобы переопределить значение в сеансе веб-запроса, используйте параметр командлета, такой как UserAgent или Credential. Значения параметров имеют приоритет над значениями в сеансе веб-запроса. Заголовки, связанные с содержимым, такие как Content-Type, также будут переопределены при указании объекта MultipartFormDataContent для body.

Чтобы создать сеанс веб-запроса, введите имя переменной без знака доллара в значение параметра Invoke-RestMethodSessionVariable команды. Invoke-RestMethod создает сеанс и сохраняет его в переменной . В последующих командах используйте переменную в качестве значения параметра WebSession.

В одной команде нельзя использовать параметры SessionVariable и WebSession .

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

Входные данные

Object

Вы можете передать текст веб-запроса в Invoke-RestMethod.

Выходные данные

System.Int64, System.String, System.Xml.XmlDocument

Выходные данные командлета зависят от формата получаемого содержимого.

PSObject

Если запрос возвращает строки JSON, Invoke-RestMethod возвращает psObject , представляющий строки.

Примечания

Некоторые функции могут быть доступны не на всех платформах.

Из-за изменений в .NET Core 3.1 PowerShell 7.0 и более поздних версий использует свойство HttpClient.DefaultProxy для определения конфигурации прокси-сервера.

Это свойство имеет разные правила в зависимости от платформы:

Для Windows: считывает конфигурацию прокси-сервера из переменных среды или, если они не определены, из параметров прокси-сервера пользователя.
Для macOS: считывает конфигурацию прокси-сервера из переменных среды или, если они не определены, из параметров прокси-сервера системы.
Для Linux: считывает конфигурацию прокси-сервера из переменных среды или, если они не определены, это свойство инициализирует ненастроенный экземпляр, который обходит все адреса.

Переменные среды, используемые для инициализации DefaultProxy на платформах Windows и Unix:

HTTP_PROXY: имя узла или IP-адрес прокси-сервера, используемого в HTTP-запросах.
HTTPS_PROXY: имя узла или IP-адрес прокси-сервера, используемого в HTTPS-запросах.
ALL_PROXY: имя узла или IP-адрес прокси-сервера, используемого в HTTP- и HTTPS-запросах в случае HTTP_PROXY или HTTPS_PROXY не определены.
NO_PROXY: разделенный запятыми список имен узлов, которые следует исключить из прокси-сервера.

Поделиться через

Invoke-RestMethod

Синтаксис

Описание

Примеры

Пример 1. Получение RSS-канала PowerShell

Пример 2. Выполнение запроса POST

Пример 3. Переход по ссылкам на связь

Пример 4. Упрощенная отправка нескольких частей или форм-данных

Пример 5. Передача нескольких заголовков

Пример 6. Перечисление возвращенных элементов в конвейере

Параметры

-AllowUnencryptedAuthentication

-Authentication

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-CustomMethod

-DisableKeepAlive

-FollowRelLink

-Form

-Headers

-InFile

-MaximumFollowRelLink

-MaximumRedirection

-MaximumRetryCount

-Method

-NoProxy

-OutFile

-PassThru

-PreserveAuthorizationOnRedirect

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-ResponseHeadersVariable

-Resume

-RetryIntervalSec

-SessionVariable

-SkipCertificateCheck

-SkipHeaderValidation

-SkipHttpErrorCheck

-SslProtocol

-StatusCodeVariable

-TimeoutSec

-Token

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

Входные данные

Выходные данные

Примечания

Связанные ссылки

Дополнительные ресурсы