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] объекты.

Примечание.

Когда конечная точка 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 командлет для отображения значений свойств Title и 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) основной текст задается как значение основного текста запроса в стандартном формате имя=значение.

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

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

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.

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

-ContentType

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

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

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

-DisableKeepAlive

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

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

-Headers

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

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

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

-InFile

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

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

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

-MaximumRedirection

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

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

-Method

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

Default
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace

Type:	WebRequestMethod
Accepted values:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Position:	Named
Default value:	Default
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-OutFile

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

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

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

-PassThru

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

Примечание.

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

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

-Proxy

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

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

-ProxyCredential

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

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

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

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

-ProxyUseDefaultCredentials

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

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

-SessionVariable

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

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

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

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

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

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

-TimeoutSec

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

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

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

-TransferEncoding

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

Chunked
Compress
Deflate
GZip
Identity

Type:	String
Accepted values:	chunked, compress, deflate, gzip, identity
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Uri

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

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

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

-UseBasicParsing

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

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

-UseDefaultCredentials

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

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

-UserAgent

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

По умолчанию агент пользователя аналогичен Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US) WindowsPowerShell/3.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. Значения параметров имеют приоритет над значениями в сеансе веб-запроса.

В отличие от удаленного сеанса сеанс веб-запроса не является постоянным подключением. Это объект, содержащий сведения о подключении и запросе, включая файлы 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 , представляющий данные.

Примечания

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

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

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

Примечания

Обратная связь

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

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

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

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

Примечания

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

Обратная связь

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