Invoke-RestMethod

Модуль:

Microsoft.PowerShell.Utility Module

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

Синтаксис

Default (По умолчанию)

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.

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

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

Этот командлет введён в Windows PowerShell версии 3.0. Эта команда может выполняться с помощью псевдонима irm .

Примеры

Пример 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 для отображения в таблице значений свойств заголовка и pubDate каждого блога.

Пример 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
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	True
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-Certificate

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

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

Свойства параметров

Тип:	X509Certificate
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-CertificateThumbprint

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

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

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

Свойства параметров

Тип:	String
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

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

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-Credential

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

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

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

Замечание

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

Свойства параметров

Тип:	PSCredential
Default value:	Current user
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-DisableKeepAlive

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

Свойства параметров

Тип:	SwitchParameter
Default value:	False
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-Headers

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

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

Свойства параметров

Тип:	IDictionary
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-InFile

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

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

Свойства параметров

Тип:	String
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-MaximumRedirection

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

Свойства параметров

Тип:	Int32
Default value:	5
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-Method

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

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

Свойства параметров

Тип:	WebRequestMethod
Default value:	Default
Допустимые значения:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-OutFile

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

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

Свойства параметров

Тип:	String
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-PassThru

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

Замечание

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

Свойства параметров

Тип:	SwitchParameter
Default value:	No output
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-Proxy

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

Свойства параметров

Тип:	Uri
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-ProxyCredential

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

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

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

Свойства параметров

Тип:	PSCredential
Default value:	Current user
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-ProxyUseDefaultCredentials

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

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

Свойства параметров

Тип:	SwitchParameter
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-SessionVariable

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

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

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

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

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

Свойства параметров

Тип:	String
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False
Aliases:	SV

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-TimeoutSec

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

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

Свойства параметров

Тип:	Int32
Default value:	0
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-TransferEncoding

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

• Chunked
• Compress
• Deflate
• GZip
• Identity

Свойства параметров

Тип:	String
Default value:	None
Допустимые значения:	chunked, compress, deflate, gzip, identity
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-Uri

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

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

Свойства параметров

Тип:	Uri
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	0
Обязательно:	True
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-UseBasicParsing

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

Свойства параметров

Тип:	SwitchParameter
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-UseDefaultCredentials

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

Свойства параметров

Тип:	SwitchParameter
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

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

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-WebSession

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

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

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

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

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

Свойства параметров

Тип:	WebRequestSession
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

CommonParameters

Этот командлет поддерживает общие параметры: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction и -WarningVariable. Дополнительные сведения см. в разделе about_CommonParameters.

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

Object

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

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

Int64

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

String

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

XmlDocument

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

PSObject

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

Примечания

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

• irm

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

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

• ConvertTo-Json
• ConvertFrom-Json
• Invoke-WebRequest (вызов веб-запроса)