Invoke-RestMethod

Синтаксис

StandardMethod (по умолчанию)

Invoke-RestMethod
    [-Uri] <Uri>
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-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>]

StandardMethodNoProxy

Invoke-RestMethod
    [-Uri] <Uri>
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-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>]

CustomMethod

Invoke-RestMethod
    [-Uri] <Uri>
    -CustomMethod <String>
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-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>]
    [-PreserveHttpMethodOnRedirect]
    [-UnixSocket <UnixDomainSocketEndPoint>]
    [-Proxy <Uri>]
    [-ProxyCredential <PSCredential>]
    [-ProxyUseDefaultCredentials]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [<CommonParameters>]

CustomMethodNoProxy

Invoke-RestMethod
    [-Uri] <Uri>
    -CustomMethod <String>
    [-FollowRelLink]
    [-MaximumFollowRelLink <Int32>]
    [-ResponseHeadersVariable <String>]
    [-StatusCodeVariable <String>]
    [-UseBasicParsing]
    [-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>]
    [-PreserveHttpMethodOnRedirect]
    [-UnixSocket <UnixDomainSocketEndPoint>]
    [-NoProxy]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [<CommonParameters>]

Описание

Примеры

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

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

$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

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

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

Пример 4: Упрощенная 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

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

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

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

$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. Пропуск проверки заголовка

$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}

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

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

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

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

Параметры

-AllowInsecureRedirect

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

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

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

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

-AllowUnencryptedAuthentication

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

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

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

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

-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.

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

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

-Body

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

Параметр body можно использовать для указания списка параметров запроса или указания содержимого ответа. Для параметров запроса командлет использует метод метода System.Net.WebUtility.UrlEncode для кодирования пар "ключ-значение". Дополнительные сведения о строках кодирования для URL-адресов см. в справочнике по методу UrlEncode().

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

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

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

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

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

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

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

-Certificate

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

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

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

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

-CertificateThumbprint

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

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

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

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

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

-ConnectionTimeoutSeconds

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

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

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

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

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

-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. Однако необходимо задать тип контента на основе требований конечной точки.

ContentType переопределяется, когда body является объектом MultipartFormDataContent.

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

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

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

-Credential

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

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

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

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

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

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

-CustomMethod

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

Пример:

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

Это делает TEST HTTP-запрос к API.

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

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

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

-DisableKeepAlive

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

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

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

-FollowRelLink

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

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

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

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

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

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

-Form

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

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

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

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

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

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

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

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

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

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

-Headers

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

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

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

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

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

-HttpVersion

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

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

• 1.0
• 1.1
• 2.0
• 3.0

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

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

-InFile

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

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

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

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

-MaximumFollowRelLink

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

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

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

-MaximumRedirection

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

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

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

-MaximumRetryCount

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

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

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

-Method

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

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

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

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

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

-NoProxy

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

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

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

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

-OperationTimeoutSeconds

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

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

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

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

-OutFile

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

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

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

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

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

-PassThru

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

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

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

-PreserveAuthorizationOnRedirect

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

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

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

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

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

-PreserveHttpMethodOnRedirect

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

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

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

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

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

-Proxy

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

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

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

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

-ProxyCredential

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

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

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

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

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

-ProxyUseDefaultCredentials

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

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

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

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

-ResponseHeadersVariable

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

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

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

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

-Resume

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

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

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

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

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

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

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

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

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

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

-RetryIntervalSec

Указывает интервал между повторными попытками подключения при получении кода сбоя от 400 до 599 включительно или 304. Значение должно находиться между 1 и [int]::MaxValue. Если код сбоя равен 429, а ответ включает свойство Retry-After в заголовках, командлет использует это значение для интервала повтора, даже если этот параметр указан.

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

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

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

-SessionVariable

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

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

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

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

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

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

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

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

-SkipCertificateCheck

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

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

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

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

-SkipHeaderValidation

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

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

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

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

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

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

-SkipHttpErrorCheck

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

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

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

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

-SslProtocol

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

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

Эта функция была добавлена в PowerShell 6.0.0. Добавлена поддержка Tls13 в PowerShell 7.1.

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

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

-StatusCodeVariable

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

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

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

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

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

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

-Token

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

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

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

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

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

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

-TransferEncoding

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

• Разделенные на части
• Сжимать
• Выкачивать
• GZip
• Идентичность

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

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

-UnixSocket

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

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

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

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

-Uri

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

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

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

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

-UseBasicParsing

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

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

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

-UseDefaultCredentials

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

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

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

-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.

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

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

-WebSession

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

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

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

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

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

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

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

CommonParameters

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

Object

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

Int64

String

XmlDocument

PSObject

Примечания

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

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