Invoke-RestMethod

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

Синтаксис

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

Описание

Командлет Invoke-RestMethod отправляет HTTP-запросы и HTTPS в веб-службы передачи репрезентативного состояния (REST), возвращающие полно структурированные данные.

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

Примечание.

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

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

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

Начиная с PowerShell 7.4 кодировка символов для запросов по умолчанию в UTF-8 вместо ASCII. Если вам нужна другая кодировка, необходимо задать charset атрибут в заголовке Content-Type .

Примеры

Пример 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 в качестве выходного режима и задает период времени для возвращаемых данных, который начинается два дня назад и заканчивается один день назад. Переменная тела задает значения параметров, применяемых к конкретному 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-Itemavatar ключ, 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

Пример 7. Пропуск проверки заголовка

По умолчанию Invoke-RestMethod командлет проверяет значения известных заголовков, имеющих стандартный формат значений. В следующем примере показано, как эта проверка может вызвать ошибку и как можно использовать параметр SkipHeaderValidation , чтобы избежать проверки значений конечных точек, допускающих недопустимое форматирование значений.

$Uri = 'https://httpbin.org/headers'
$InvalidHeaders = @{
    'If-Match' = '12345'
}

Invoke-RestMethod -Uri $Uri -Headers $InvalidHeaders

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

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

headers : @{Host=httpbin.org; If-Match=12345; User-Agent=Mozilla/5.0 (Windows NT 10.0; Microsoft Windows
          10.0.19044; en-US) PowerShell/7.2.5;  X-Amzn-Trace-Id=Root=1-62f150a6-27754fd4226f31b43a3d2874}

httpbin.org — это служба, которая возвращает сведения о веб-запросах и ответах для устранения неполадок. Переменная $Uri назначается /headers конечной точке службы, которая возвращает заголовки запроса в качестве содержимого в ответе.

Заголовок If-Match запроса определен в разделе 3.1 RFC-7232 и требует определения этого заголовка с окружающими кавычками. Переменная $InvalidHeaders назначается хэш-таблица, в которой значение If-Match недопустимо, так как оно определено как 12345 не "12345"так.

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

Вызов Invoke-RestMethod с параметром SkipHeaderValidation игнорирует сбой проверки и отправляет запрос в конечную точку. Так как конечная точка допускает несоответствующие значения заголовков, командлет возвращает объект ответа без ошибок.

Пример 8. Отправка запроса с помощью HTTP 2.0

В этом примере запрашивается проблема с GitHub с помощью протокола HTTP 2.0.

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

Пример 9. Отправка запроса в приложение сокета Unix

Некоторые приложения, такие как Docker, предоставляют сокет Unix для обмена данными. В этом примере запрашивается список образов Docker с помощью API Docker. Командлет подключается к управляющей программе Docker с помощью сокета Unix.

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

Параметры

-AllowInsecureRedirect

Разрешает перенаправление с HTTPS на HTTP. По умолчанию любой запрос, перенаправленный из HTTPS в HTTP, приводит к ошибке, и запрос прерван, чтобы предотвратить непреднамеренное взаимодействие с обычным текстом через незашифрованные подключения. Чтобы переопределить это поведение по вашему собственному риску, используйте параметр AllowInsecureRedirect .

Этот параметр добавлен в PowerShell 7.4.

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

-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. Параметр проверки подлинности нельзя использовать с параметром UseDefaultCredentials .

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

  • None: это параметр по умолчанию, если проверка подлинности не предоставлена. Не будет использоваться явная проверка подлинности.
  • Basic: требуется учетные данные. Учетные данные будут использоваться для отправки заголовка базовой проверки подлинности Authorization: Basic RFC 7617 в формате base64(user:password).
  • Bearer: требуется параметр токена. Отправляет заголовок RFC 6750 Authorization: Bearer с предоставленным маркером.
  • OAuth: требуется параметр токена. Отправляет заголовок 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 можно использовать для указания списка параметров запроса или указания содержимого ответа.

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

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

Если входные данные являются объектом System.Xml.XmlNode и объявлением XML указывает кодировку, кодирование используется для данных в запросе, если не переопределяется параметром ContentType .

Если текст является формой или выходными данными другого 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-PfxCertificateGet-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 команду, чтобы найти сертификат в Cert:\CurrentUser\My.

Примечание.

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

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

-ConnectionTimeoutSeconds

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

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

Этот параметр заменил параметр TimeoutSec в PowerShell 7.4. TimeoutSec можно использовать в качестве псевдонима для Подключение ionTimeoutSeconds.

Type:Int32
Aliases:TimeoutSec
Position:Named
Default value:0
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ContentType

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

Если значение ContentType содержит формат кодирования (как charset), командлет использует этот формат для кодирования текста веб-запроса. Если ContentType не задает формат кодирования, вместо него используется формат кодирования по умолчанию. Пример ContentType с форматом кодировки, text/plain; charset=iso-8859-5который задает алфавит латинской или кириллицы.

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

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

Начиная с PowerShell 7.4, при использовании этого параметра и параметра Заголовков для определения Content-Type заголовка используется значение, указанное в параметре ContentType .

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

Задает пользовательский метод, используемый для веб-запроса. Это можно использовать с методом запроса, необходимым для конечной точки, недоступен для метода. Метод и 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

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

Некоторые ИНТЕРФЕЙСы 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 = @{ резюме = Get-Item 'c:\Users\jdoe\Documents\John Doe.pdf' }

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

$Form = @{ теги = "Отпуск", "Италия", "2017" фотографии = 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

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

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

Начиная с PowerShell 7.4, если этот параметр используется для определения заголовка Content-Type и использования параметра ContentType, используется значение, указанное в параметре ContentType.

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

-HttpVersion

Указывает версию HTTP, используемую для запроса. Значение по умолчанию — 1.1.

Допустимые значения:

  • 1.0
  • 1,1
  • 2.0
  • 3.0
Type:Version
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-InFile

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

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

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

Указывает, сколько раз следует следовать ссылкам реляционной связи, если используется FollowRelLink . Меньшее значение может потребоваться, если REST API регулируется из-за слишком большого количества запросов. Значение по умолчанию — [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

-OperationTimeoutSeconds

Это время ожидания применяется к данным, считываемым в потоке, а не к времени потока в целом. Значение по умолчанию 0 указывает неопределенное время ожидания.

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

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

-OutFile

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

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

Начиная с PowerShell 7.4, можно указать путь к папке без имени файла. При выполнении имя файла взято из последнего сегмента разрешенного URI после любых перенаправлений. При указании пути к папке для OutFile нельзя использовать параметр Resume .

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

-PassThru

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

Примечание.

При использовании параметра PassThru выходные данные записываются в конвейер, но файл не создается. Дополнительные сведения см. в статье о проблеме PowerShell #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

-PreserveHttpMethodOnRedirect

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

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

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

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 .

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

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 .

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

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

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

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

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

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

Эта функция была добавлена в 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. Значение должно быть между 1 и [int]::MaxValue. Если код сбоя равен 429, а ответ включает свойство Retry-After в заголовках, командлет использует это значение для интервала повтора, даже если этот параметр указан.

Кроме того, см . параметр MaximumRetryCount для указания количества повторных попыток.

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

-SessionVariable

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

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

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

Начиная с PowerShell 7.4 сеанс веб-запроса сохраняется, пока свойства сеанса не переопределяются в последующем запросе. При их создании командлет повторно создает сеанс с новыми значениями. Постоянные сеансы снижают затраты на повторяющиеся запросы, что делает их гораздо быстрее.

Чтобы использовать сеанс веб-запроса в последующих веб-запросах, укажите переменную сеанса в значении параметра 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

-Token

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

Маркер принимает маркер 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

-UnixSocket

Указывает имя сокета Unix для подключения. Этот параметр поддерживается в системах unix и Windows версии 1803 и более поздних версиях. Дополнительные сведения о поддержке сокетов Unix в Windows см. в записи блога AF_UNIX взаимодействия Windows/WSL.

Этот параметр добавлен в PowerShell 7.4.

Type:UnixDomainSocketEndPoint
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, Internet Обозреватель, 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.

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

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

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

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

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

Object

Текст веб-запроса можно передать в этот командлет.

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

Int64

Когда запрос возвращает целое число, этот командлет возвращает это целое число.

String

Когда запрос возвращает строку, этот командлет возвращает эту строку.

XmlDocument

Когда запрос возвращает допустимый XML, этот командлет возвращает его в виде XmlDocument.

PSObject

Когда запрос возвращает строки JSON, этот командлет возвращает PSObject , представляющий данные.

Примечания

PowerShell включает следующие псевдонимы для Invoke-RestMethod:

  • Все платформы:
    • irm

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

Из-за изменений в .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: список имен узлов, разделенных запятыми, которые следует исключить из прокси-сервера.

PowerShell 7.4 добавила поддержку алгоритма сжатия Brotli.