Invoke-RestMethod

Ссылка

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

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

Синтаксис

Invoke-RestMethod
      [-Method <WebRequestMethod>]
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [<CommonParameters>]

Описание

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

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

Заметка

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

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

Заметка

По умолчанию код скрипта на веб-странице может выполняться при синтаксическом анализе страницы для заполнения свойства ParsedHtml. Используйте UseBasicParsing, чтобы отключить это.

Примеры

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

Invoke-RestMethod -Uri https://devblogs.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

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

Пример 2

В следующем примере пользователь запускает Invoke-RestMethod для выполнения запроса POST на веб-сайте интрасети в организации пользователя.

$Cred = Get-Credential

# Next, allow the use of self-signed SSL certificates.

[System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $true }

# Create variables to store the values consumed by the Invoke-RestMethod command.
# The search variable contents are later embedded in the body variable.

$Server = 'server.contoso.com'
$Url = "https://${server}:8089/services/search/jobs/export"
$Search = "search index=_internal | reverse | table index,host,source,sourcetype,_raw"

# The cmdlet handles URL encoding. The body variable describes the search criteria, specifies CSV as
# the output mode, and specifies a time period for returned data that starts two days ago and ends
# one day ago. The body variable specifies values for parameters that apply to the particular REST
# API with which Invoke-RestMethod is communicating.

$Body = @{
    search = $Search
    output_mode = "csv"
    earliest_time = "-2d@d"
    latest_time = "-1d@d"
}

# Now, run the Invoke-RestMethod command with all variables in place, specifying a path and file
# name for the resulting CSV output file.

Invoke-RestMethod -Method Post -Uri $url -Credential $Cred -Body $body -OutFile output.csv

{"preview":true,"offset":0,"result":{"sourcetype":"contoso1","count":"9624"}}

{"preview":true,"offset":1,"result":{"sourcetype":"contoso2","count":"152"}}

{"preview":true,"offset":2,"result":{"sourcetype":"contoso3","count":"88494"}}

{"preview":true,"offset":3,"result":{"sourcetype":"contoso4","count":"15277"}}

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

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

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

API'и часто требуют переданных заголовков для аутентификации, валидации и т. д.

Пример 3. Отправка данных формы

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

Например:

$R = Invoke-WebRequest https://website.com/login.aspx
$R.Forms[0].Name = "MyName"
$R.Forms[0].Password = "MyPassword"
Invoke-RestMethod https://website.com/service.aspx -Body $R.Forms[0]

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

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

Параметры

-Body

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

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

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

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

Подробные выходные данные текста POST заканчиваются with -1-byte payload, несмотря на то, что размер тела известен и отправляется в заголовке HTTP Content-Length.

Тип:	Object
Position:	Named
Default value:	None
Обязательно:	False
Принять входные данные конвейера:	True
Принять подстановочные знаки:	False

-Certificate

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

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

Тип:	X509Certificate
Position:	Named
Default value:	None
Обязательно:	False
Принять входные данные конвейера:	False
Принять подстановочные знаки:	False

-CertificateThumbprint

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

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

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

Тип:	String
Position:	Named
Default value:	None
Обязательно:	False
Принять входные данные конвейера:	False
Принять подстановочные знаки:	False

-ContentType

Указывает тип контента веб-запроса.

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

Если параметр не указан, тип контента может отличаться в зависимости от используемого метода HTTP:

Для метода POST тип контента application/x-www-form-urlencoded
Для метода PUT тип контента application/json
Для других методов тип контента не указан в запросе.

Если для отправки файла используется параметр InFile, необходимо задать тип контента. Обычно тип должен быть application/octet-stream. Однако необходимо задать тип контента на основе требований конечной точки.

Тип:	String
Position:	Named
Default value:	None
Обязательно:	False
Принять входные данные конвейера:	False
Принять подстановочные знаки:	False

-Credential

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

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

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

Заметка

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

Тип:	PSCredential
Position:	Named
Default value:	Current user
Обязательно:	False
Принять входные данные конвейера:	False
Принять подстановочные знаки:	False

-DisableKeepAlive

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

Тип:	SwitchParameter
Position:	Named
Default value:	False
Обязательно:	False
Принять входные данные конвейера:	False
Принять подстановочные знаки:	False

-Headers

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

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

Тип:	IDictionary
Position:	Named
Default value:	None
Обязательно:	False
Принять входные данные конвейера:	False
Принять подстановочные знаки:	False

-InFile

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

Кроме того, необходимо задать тип контента запроса. Например, чтобы отправить файл, необходимо задать тип контента. Обычно тип должен быть application/octet-stream. Однако необходимо задать тип контента на основе требований конечной точки.

Тип:	String
Position:	Named
Default value:	None
Обязательно:	False
Принять входные данные конвейера:	False
Принять подстановочные знаки:	False

-MaximumRedirection

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

Тип:	Int32
Position:	Named
Default value:	5
Обязательно:	False
Принять входные данные конвейера:	False
Принять подстановочные знаки:	False

-Method

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

Default
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace

Тип:	WebRequestMethod
Допустимые значения:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Position:	Named
Default value:	Default
Обязательно:	False
Принять входные данные конвейера:	False
Принять подстановочные знаки:	False

-OutFile

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

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

Тип:	String
Position:	Named
Default value:	None
Обязательно:	False
Принять входные данные конвейера:	False
Принять подстановочные знаки:	False

-PassThru

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

Заметка

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

Тип:	SwitchParameter
Position:	Named
Default value:	No output
Обязательно:	False
Принять входные данные конвейера:	False
Принять подстановочные знаки:	False

-Proxy

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

Тип:	Uri
Position:	Named
Default value:	None
Обязательно:	False
Принять входные данные конвейера:	False
Принять подстановочные знаки:	False

-ProxyCredential

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

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

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

Тип:	PSCredential
Position:	Named
Default value:	Current user
Обязательно:	False
Принять входные данные конвейера:	False
Принять подстановочные знаки:	False

-ProxyUseDefaultCredentials

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

Тип:	SwitchParameter
Position:	Named
Default value:	None
Обязательно:	False
Принять входные данные конвейера:	False
Принять подстановочные знаки:	False

-SessionVariable

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

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

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

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

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

Тип:	String
Aliases:	SV
Position:	Named
Default value:	None
Обязательно:	False
Принять входные данные конвейера:	False
Принять подстановочные знаки:	False

-TimeoutSec

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

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

Тип:	Int32
Position:	Named
Default value:	0
Обязательно:	False
Принять входные данные конвейера:	False
Принять подстановочные знаки:	False

-TransferEncoding

Задает значение заголовка ОТВЕТА HTTP для кодировки передачи. Допустимые значения для этого параметра:

Chunked
Compress
Deflate
GZip
Identity

Тип:	String
Допустимые значения:	chunked, compress, deflate, gzip, identity
Position:	Named
Default value:	None
Обязательно:	False
Принять входные данные конвейера:	False
Принять подстановочные знаки:	False

-Uri

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

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

Тип:	Uri
Position:	0
Default value:	None
Обязательно:	True
Принять входные данные конвейера:	False
Принять подстановочные знаки:	False

-UseBasicParsing

Указывает, что командлет использует базовый синтаксический анализ. Командлет возвращает объект строки с необработанным HTML-кодом.

Тип:	SwitchParameter
Position:	Named
Default value:	None
Обязательно:	False
Принять входные данные конвейера:	False
Принять подстановочные знаки:	False

-UseDefaultCredentials

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

Тип:	SwitchParameter
Position:	Named
Default value:	None
Обязательно:	False
Принять входные данные конвейера:	False
Принять подстановочные знаки:	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.

Тип:	String
Position:	Named
Default value:	None
Обязательно:	False
Принять входные данные конвейера:	False
Принять подстановочные знаки:	False

-WebSession

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

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

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

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

Тип:	WebRequestSession
Position:	Named
Default value:	None
Обязательно:	False
Принять входные данные конвейера:	False
Принять подстановочные знаки:	False

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

Object

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

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

Int64

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

String

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

XmlDocument

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

PSObject

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

Примечания

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

irm

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

Invoke-RestMethod

Синтаксис

Описание

Примеры

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

Пример 2

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

Пример 3. Отправка данных формы

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

Параметры

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

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

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

Примечания

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