Invoke-WebRequest
Получает содержимое из веб-страницы в Интернете.
Синтаксис
Invoke-WebRequest
[-UseBasicParsing]
[-Uri] <Uri>
[-HttpVersion <Version>]
[-WebSession <WebRequestSession>]
[-SessionVariable <String>]
[-AllowUnencryptedAuthentication]
[-Authentication <WebAuthenticationType>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-CertificateThumbprint <String>]
[-Certificate <X509Certificate>]
[-SkipCertificateCheck]
[-SslProtocol <WebSslProtocol>]
[-Token <SecureString>]
[-UserAgent <String>]
[-DisableKeepAlive]
[-ConnectionTimeoutSeconds <Int32>]
[-OperationTimeoutSeconds <Int32>]
[-Headers <IDictionary>]
[-SkipHeaderValidation]
[-AllowInsecureRedirect]
[-MaximumRedirection <Int32>]
[-MaximumRetryCount <Int32>]
[-PreserveAuthorizationOnRedirect]
[-RetryIntervalSec <Int32>]
[-Method <WebRequestMethod>]
[-PreserveHttpMethodOnRedirect]
[-UnixSocket <UnixDomainSocketEndPoint>]
[-Proxy <Uri>]
[-ProxyCredential <PSCredential>]
[-ProxyUseDefaultCredentials]
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[<CommonParameters>] Invoke-WebRequest
[-UseBasicParsing]
[-Uri] <Uri>
[-HttpVersion <Version>]
[-WebSession <WebRequestSession>]
[-SessionVariable <String>]
[-AllowUnencryptedAuthentication]
[-Authentication <WebAuthenticationType>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-CertificateThumbprint <String>]
[-Certificate <X509Certificate>]
[-SkipCertificateCheck]
[-SslProtocol <WebSslProtocol>]
[-Token <SecureString>]
[-UserAgent <String>]
[-DisableKeepAlive]
[-ConnectionTimeoutSeconds <Int32>]
[-OperationTimeoutSeconds <Int32>]
[-Headers <IDictionary>]
[-SkipHeaderValidation]
[-AllowInsecureRedirect]
[-MaximumRedirection <Int32>]
[-MaximumRetryCount <Int32>]
[-PreserveAuthorizationOnRedirect]
[-RetryIntervalSec <Int32>]
[-Method <WebRequestMethod>]
[-PreserveHttpMethodOnRedirect]
[-UnixSocket <UnixDomainSocketEndPoint>]
[-NoProxy]
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[<CommonParameters>] Invoke-WebRequest
[-UseBasicParsing]
[-Uri] <Uri>
[-HttpVersion <Version>]
[-WebSession <WebRequestSession>]
[-SessionVariable <String>]
[-AllowUnencryptedAuthentication]
[-Authentication <WebAuthenticationType>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-CertificateThumbprint <String>]
[-Certificate <X509Certificate>]
[-SkipCertificateCheck]
[-SslProtocol <WebSslProtocol>]
[-Token <SecureString>]
[-UserAgent <String>]
[-DisableKeepAlive]
[-ConnectionTimeoutSeconds <Int32>]
[-OperationTimeoutSeconds <Int32>]
[-Headers <IDictionary>]
[-SkipHeaderValidation]
[-AllowInsecureRedirect]
[-MaximumRedirection <Int32>]
[-MaximumRetryCount <Int32>]
[-PreserveAuthorizationOnRedirect]
[-RetryIntervalSec <Int32>]
-CustomMethod <String>
[-PreserveHttpMethodOnRedirect]
[-UnixSocket <UnixDomainSocketEndPoint>]
[-Proxy <Uri>]
[-ProxyCredential <PSCredential>]
[-ProxyUseDefaultCredentials]
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[<CommonParameters>] Invoke-WebRequest
[-UseBasicParsing]
[-Uri] <Uri>
[-HttpVersion <Version>]
[-WebSession <WebRequestSession>]
[-SessionVariable <String>]
[-AllowUnencryptedAuthentication]
[-Authentication <WebAuthenticationType>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-CertificateThumbprint <String>]
[-Certificate <X509Certificate>]
[-SkipCertificateCheck]
[-SslProtocol <WebSslProtocol>]
[-Token <SecureString>]
[-UserAgent <String>]
[-DisableKeepAlive]
[-ConnectionTimeoutSeconds <Int32>]
[-OperationTimeoutSeconds <Int32>]
[-Headers <IDictionary>]
[-SkipHeaderValidation]
[-AllowInsecureRedirect]
[-MaximumRedirection <Int32>]
[-MaximumRetryCount <Int32>]
[-PreserveAuthorizationOnRedirect]
[-RetryIntervalSec <Int32>]
-CustomMethod <String>
[-PreserveHttpMethodOnRedirect]
[-UnixSocket <UnixDomainSocketEndPoint>]
[-NoProxy]
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[<CommonParameters>] Описание
Командлет Invoke-WebRequest отправляет HTTP-запросы и HTTPS на веб-страницу или веб-службу. Анализирует ответ и возвращает коллекции ссылок, изображений и других значимых HTML-элементов.
Этот командлет появился в PowerShell 3.0.
Начиная с PowerShell 7.0, поддерживает конфигурацию прокси-сервера, Invoke-WebRequest определенную переменными среды. См. раздел " Заметки " этой статьи.
Внимание
Примеры в этой статье ссылались на узлы в домене contoso.com . Это вымышленный домен, используемый корпорацией Майкрософт, например. В примерах показано, как использовать командлеты.
Тем не менее, так как contoso.com сайты не существуют, примеры не работают. Адаптируйте примеры к узлам в вашей среде.
Начиная с PowerShell 7.4 кодировка символов для запросов по умолчанию в UTF-8 вместо ASCII. Если вам нужна другая кодировка, необходимо задать charset атрибут в заголовке Content-Type .
Примеры
Пример 1. Отправка веб-запроса
В этом примере командлет используется Invoke-WebRequest для отправки веб-запроса на сайт Bing.com.
$Response = Invoke-WebRequest -URI https://www.bing.com/search?q=how+many+feet+in+a+mile
$Response.InputFields | Where-Object {
$_.name -like "* Value*"
} | Select-Object Name, Value
name value
---- -----
From Value 1
To Value 5280Первая команда выдает запрос и сохраняет ответ в переменной $Response .
Вторая команда получает любой InputField, где свойство Name похоже."* Value" Отфильтрованные результаты передаются для Select-Object выбора свойств "Имя" и "Значение".
Пример 2. Использование веб-службы с отслеживанием состояния
В этом примере показано, как использовать Invoke-WebRequest командлет с веб-службой с отслеживанием состояния.
$LoginParameters = @{
Uri = 'https://www.contoso.com/login/'
SessionVariable = 'Session'
Method = 'POST'
Body = @{
User = 'jdoe'
Password = 'P@S$w0rd!'
}
}
$LoginResponse = Invoke-WebRequest @LoginParameters
$ProfileResponse = Invoke-WebRequest 'https://www.contoso.com/profile/' -WebSession $SessionПервый вызов для Invoke-WebRequest отправки запроса на вход. Команда задает значение значения Sessionпараметра SessionVariable . По завершении $LoginResponse команды переменная содержит объект BasicHtmlWebResponseObject , а $Session переменная содержит WebRequestSession объект. Это регистрирует пользователя на сайте.
Второй вызов получения профиля пользователя, который требует, чтобы Invoke-WebRequest пользователь вошел на сайт. Данные сеанса, хранящиеся в переменной $Session , предоставляют файлы cookie сеанса сайту, созданному во время входа.
Пример 3. Получение ссылок с веб-страницы
Этот пример получает ссылки на веб-странице. Он использует Invoke-WebRequest командлет для получения содержимого веб-страницы. Затем он использует свойство Links объекта BasicHtmlWebResponseObject , которое Invoke-WebRequest возвращает, и свойство Href каждой ссылки.
(Invoke-WebRequest -Uri "https://aka.ms/pscore6-docs").Links.HrefПример 4. Запись содержимого ответа в файл с помощью кодировки, определенной на запрошенной странице
В этом примере командлет используется Invoke-WebRequest для получения содержимого веб-страницы страницы документации PowerShell.
$Response = Invoke-WebRequest -Uri "https://aka.ms/pscore6-docs"
$Stream = [System.IO.StreamWriter]::new('.\docspage.html', $false, $Response.Encoding)
try {
$Stream.Write($Response.Content)
} finally {
$Stream.Dispose()
}Первая команда извлекает страницу и сохраняет объект ответа в переменной $Response .
Вторая команда создает StreamWriter для записи содержимого ответа в файл. Свойство кодирования объекта ответа используется для задания кодировки для файла.
Последние несколько команд записывают свойство Content в файл, а затем удаляет StreamWriter.
Обратите внимание, что свойство кодировки имеет значение NULL, если веб-запрос не возвращает текстовое содержимое.
Пример 5. Отправка файла с несколькими частями или формами данных
В этом примере Invoke-WebRequest командлет отправляет файл в качестве отправки multipart/form-data . Файл c:\document.txt отправляется в качестве поля document формы с полем Content-Typetext/plainформы.
$FilePath = 'c:\document.txt'
$FieldName = 'document'
$ContentType = 'text/plain'
$FileStream = [System.IO.FileStream]::new($filePath, [System.IO.FileMode]::Open)
$FileHeader = [System.Net.Http.Headers.ContentDispositionHeaderValue]::new('form-data')
$FileHeader.Name = $FieldName
$FileHeader.FileName = Split-Path -leaf $FilePath
$FileContent = [System.Net.Http.StreamContent]::new($FileStream)
$FileContent.Headers.ContentDisposition = $FileHeader
$FileContent.Headers.ContentType = [System.Net.Http.Headers.MediaTypeHeaderValue]::Parse($ContentType)
$MultipartContent = [System.Net.Http.MultipartFormDataContent]::new()
$MultipartContent.Add($FileContent)
$Response = Invoke-WebRequest -Body $MultipartContent -Method 'POST' -Uri 'https://api.contoso.com/upload'Пример 6. Упрощенная многопартийная отправка данных
Некоторые API требуют multipart/form-data отправки файлов и смешанного содержимого. В этом примере показано обновление профиля пользователя.
$Uri = 'https://api.contoso.com/v2/profile'
$Form = @{
firstName = 'John'
lastName = 'Doe'
email = 'john.doe@contoso.com'
avatar = Get-Item -Path 'c:\Pictures\jdoe.png'
birthday = '1980-10-15'
hobbies = 'Hiking','Fishing','Jogging'
}
$Result = Invoke-WebRequest -Uri $Uri -Method Post -Form $FormДля формы профиля требуются следующие поля: firstName, lastName, email, avatar, birthdayи hobbies. API ожидает, что изображение для изображения профиля пользователя будет предоставлено avatar в поле. API также принимает несколько hobbies записей, которые будут отправляться в одной форме.
При создании $Form HashTable имена ключей используются в качестве имен полей формы. По умолчанию значения хэш-таблицы преобразуются в строки. Если значение System.IO.FileInfo присутствует, содержимое файла отправляется. Если коллекция, например массивы или списки, присутствует, поле формы отправляется несколько раз.
avatar Используя Get-Item ключ, FileInfo объект задается в качестве значения. Результатом является то, что данные изображения для jdoe.png отправки.
Указав список hobbies в ключ, hobbies поле присутствует в отправке один раз для каждого элемента списка.
Пример 7. Перехват сообщений об успешном выполнении из Invoke-WebRequest
При Invoke-WebRequest обнаружении сообщения HTTP, отличного от успешного выполнения (404, 500 и т. д.), он не возвращает выходные данные и выдает завершающее ошибку. Чтобы поймать ошибку и просмотреть Код состояния , можно заключить выполнение в try/catch блок.
try
{
$Response = Invoke-WebRequest -Uri "www.microsoft.com/unkownhost"
# This will only execute if the Invoke-WebRequest is successful.
$StatusCode = $Response.StatusCode
} catch {
$StatusCode = $_.Exception.Response.StatusCode.value__
}
$StatusCode
404Завершающая ошибка перехвата блоком catch , который извлекает StatusCode из объекта Exception .
Пример 8. Скачивание нескольких файлов одновременно
Командлет Invoke-WebRequest может одновременно скачать только один файл. В следующем примере используется Start-ThreadJob для создания нескольких заданий потоков для одновременного скачивания нескольких файлов.
$baseUri = 'https://github.com/PowerShell/PowerShell/releases/download'
$files = @(
@{
Uri = "$baseUri/v7.3.0-preview.5/PowerShell-7.3.0-preview.5-win-x64.msi"
OutFile = 'PowerShell-7.3.0-preview.5-win-x64.msi'
},
@{
Uri = "$baseUri/v7.3.0-preview.5/PowerShell-7.3.0-preview.5-win-x64.zip"
OutFile = 'PowerShell-7.3.0-preview.5-win-x64.zip'
},
@{
Uri = "$baseUri/v7.2.5/PowerShell-7.2.5-win-x64.msi"
OutFile = 'PowerShell-7.2.5-win-x64.msi'
},
@{
Uri = "$baseUri/v7.2.5/PowerShell-7.2.5-win-x64.zip"
OutFile = 'PowerShell-7.2.5-win-x64.zip'
}
)
$jobs = @()
foreach ($file in $files) {
$jobs += Start-ThreadJob -Name $file.OutFile -ScriptBlock {
$params = $using:file
Invoke-WebRequest @params
}
}
Write-Host "Downloads started..."
Wait-Job -Job $jobs
foreach ($job in $jobs) {
Receive-Job -Job $job
}Пример 9. Пропуск проверки заголовка
По умолчанию Invoke-WebRequest командлет проверяет значения известных заголовков, имеющих стандартный формат значений. В следующем примере показано, как эта проверка может вызвать ошибку и как можно использовать параметр SkipHeaderValidation , чтобы избежать проверки значений конечных точек, допускающих недопустимое форматирование значений.
$Uri = 'https://httpbin.org/headers'
$InvalidHeaders = @{
'If-Match' = '12345'
}
Invoke-WebRequest -Uri $Uri -Headers $InvalidHeaders
Invoke-WebRequest -Uri $Uri -Headers $InvalidHeaders -SkipHeaderValidation
Invoke-WebRequest: The format of value '12345' is invalid.
StatusCode : 200
StatusDescription : OK
Content : {
"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": �
RawContent : HTTP/1.1 200 OK
Date: Mon, 08 Aug 2022 16:24:24 GMT
Connection: keep-alive
Server: gunicorn/19.9.0
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
Content-Type: application�
Headers : {[Date, System.String[]], [Connection, System.String[]], [Server, System.String[]], [Access-Control-Allow-Origin, System.String[]]�}
Images : {}
InputFields : {}
Links : {}
RawContentLength : 249
RelationLink : {} httpbin.org — это служба, которая возвращает сведения о веб-запросах и ответах для устранения неполадок. Переменная $Uri назначается /headers конечной точке службы, которая возвращает заголовки запроса в качестве содержимого в ответе.
Заголовок If-Match запроса определен в разделе 3.1 RFC-7232 и требует определения этого заголовка с окружающими кавычками. Переменная $InvalidHeaders назначается хэш-таблица, в которой значение If-Match недопустимо, так как оно определено как 12345 не "12345"так.
Вызов Invoke-WebRequest с недопустимыми заголовками возвращает сообщение об ошибке, указывающее, что форматируемое значение недопустимо. Запрос не отправляется в конечную точку.
Вызов Invoke-WebRequest с параметром SkipHeaderValidation игнорирует сбой проверки и отправляет запрос в конечную точку. Так как конечная точка допускает несоответствующие значения заголовков, командлет возвращает объект ответа без ошибок.
Пример 10. Отправка запроса с помощью HTTP 2.0
Этот пример получает ссылки на веб-странице с помощью протокола HTTP 2.0. Он использует Invoke-WebRequest командлет для получения содержимого веб-страницы. Затем он использует свойство Links объекта BasicHtmlWebResponseObject , которое Invoke-WebRequest возвращает, и свойство Href каждой ссылки.
(Invoke-WebRequest -Uri 'https://aka.ms/pscore6-docs' -HttpVersion 2.0).Links.HrefПример 11. Отправка запроса в приложение сокета Unix
Некоторые приложения, такие как Docker, предоставляют сокет Unix для обмена данными. В этом примере запрашивается список образов Docker с помощью API Docker. Командлет подключается к управляющей программе Docker с помощью сокета Unix.
Invoke-WebRequest -Uri "http://localhost/v1.40/images/json/" -UnixSocket "/var/run/docker.sock"Параметры
-AllowInsecureRedirect
Разрешает перенаправление с HTTPS на HTTP. По умолчанию любой запрос, перенаправленный из HTTPS в HTTP, приводит к ошибке, и запрос прерван, чтобы предотвратить непреднамеренное взаимодействие с обычным текстом через незашифрованные подключения. Чтобы переопределить это поведение по вашему собственному риску, используйте параметр AllowInsecureRedirect .
Этот параметр добавлен в PowerShell 7.4.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-AllowUnencryptedAuthentication
Позволяет отправлять учетные данные и секреты через незашифрованные подключения. По умолчанию укажите учетные данные или любой параметр проверки подлинности с помощью URI , который не начинается с https:// ошибки, и запрос прерван, чтобы предотвратить непреднамеренные передачи секретов в виде обычного текста через незашифрованные подключения. Чтобы переопределить это поведение по вашему собственному риску, укажите параметр AllowUnencryptedAuthentication .
Предупреждение
Использование этого параметра не является безопасным и не рекомендуется. Он предоставляется только для совместимости с устаревшими системами, которые не могут предоставлять зашифрованные подключения. Используйте свой собственный риск.
Эта функция была добавлена в PowerShell 6.0.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Authentication
Указывает явный тип проверки подлинности, используемый для запроса. Значение по умолчанию — None. Параметр проверки подлинности нельзя использовать с параметром UseDefaultCredentials .
Доступные параметры проверки подлинности:
None: это параметр по умолчанию, если проверка подлинности не предоставляется. Не используется явная проверка подлинности.Basic: требуется учетные данные. Учетные данные отправляются в виде заголовка базовой проверки подлинностиAuthorization: BasicRFC 7617 в форматеbase64(user:password).Bearer: требуется параметр токена. Отправляет заголовок RFC 6750Authorization: Bearerс предоставленным маркером.OAuth: требуется параметр токена. Отправляет заголовок RFC 6750Authorization: Bearerс предоставленным маркером.
Предоставление проверки подлинности переопределяет все Authorization заголовки, предоставленные заголовкам или включенным в WebSession.
Эта функция была добавлена в PowerShell 6.0.0.
| Type: | WebAuthenticationType |
| Accepted values: | None, Basic, Bearer, OAuth |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Body
Задает основной текст запроса. Основной текст — это содержимое запроса, идущее после заголовков.
Можно также передать значение Invoke-WebRequestтекста в .
Параметр Body можно использовать для указания списка параметров запроса или указания содержимого ответа.
Если входные данные являются запросом POST, а текст является строкой, значение слева от первого знака равенства (=) задается в качестве ключа в данных формы, а оставшийся текст задается в качестве значения. Чтобы указать несколько ключей, используйте объект IDictionary , например хэш-таблицу для body.
Если входные данные являются запросом GET, а текст является IDictionary (обычно хэш-таблицей), текст добавляется в URI в качестве параметров запроса. Для других типов запросов (например, PATCH) текст задается в качестве значения текста запроса в стандартном name=value формате со значениями, закодированными URL-адресом.
Если входные данные являются объектом System.Xml.XmlNode и объявлением XML указывает кодировку, кодирование используется для данных в запросе, если не переопределяется параметром ContentType .
Параметр Body также принимает System.Net.Http.MultipartFormDataContent объект. Это упрощает multipart/form-data запросы. Если объект MultipartFormDataContent предоставляется для Body, все связанные с контентом заголовки, предоставленные параметрам ContentType, Headers или WebSession, переопределяются заголовками Content объекта MultipartFormDataContent. Эта функция была добавлена в PowerShell 6.0.0.
| Type: | Object |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Certificate
Указывает сертификат клиента, используемый для безопасного веб-запроса. Введите переменную, которая содержит сертификат, или команду или выражение, которое возвращает сертификат.
Чтобы найти сертификат, используйте Get-PfxCertificateGet-ChildItem командлет на диске сертификата (Cert:). Если сертификат недействителен или не имеет достаточного центра, команда завершается ошибкой.
| Type: | X509Certificate |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-CertificateThumbprint
Задает цифровой сертификат с открытым ключом (X509) учетной записи пользователя, который располагает разрешением для отправки запроса. Введите отпечаток сертификата.
Сертификаты используются при проверке подлинности на основе сертификата клиента. Сертификаты можно сопоставить только с локальными учетными записями пользователей, а не с учетными записями домена.
Чтобы просмотреть отпечаток сертификата, используйте Get-Item команду или Get-ChildItem команду, чтобы найти сертификат в Cert:\CurrentUser\My.
Примечание.
Эта функция поддерживается только на платформах ОС Windows.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ConnectionTimeoutSeconds
Указывает время ожидания запроса до истечения времени ожидания. Введите значение в секундах. Значение по умолчанию, равное 0, указывает неопределенное время ожидания.
Запрос системы доменных имен (DNS) может занять до 15 секунд для возврата или истечения времени ожидания. Если ваш запрос содержит имя узла, требующее разрешения, и вы задали Подключение ionTimeoutSeconds значением больше нуля, но менее 15 секунд, оно может занять 15 секунд или более до того, как webException будет создан, и время ожидания запроса истекает.
Этот параметр заменил параметр TimeoutSec в PowerShell 7.4. TimeoutSec можно использовать в качестве псевдонима для Подключение ionTimeoutSeconds.
| Type: | Int32 |
| Aliases: | TimeoutSec |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ContentType
Задает тип содержимого веб-запроса.
Если значение ContentType содержит формат кодирования (как charset), командлет использует этот формат для кодирования текста веб-запроса. Если ContentType не задает формат кодирования, вместо него используется формат кодирования по умолчанию. Пример ContentType с форматом кодировки, text/plain; charset=iso-8859-5который задает алфавит латинской или кириллицы.
Если этот параметр опущен, а метод запроса — POST или PUT, Invoke-WebRequest задает для типа контента значение application/x-www-form-urlencoded. В противном случае тип контента не указан в вызове.
ContentType переопределяется при указании объекта MultipartFormDataContent для Body.
Начиная с PowerShell 7.4, при использовании этого параметра и параметра Заголовков для определения Content-Type заголовка используется значение, указанное в параметре ContentType .
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Credential
Указывает учетную запись пользователя, обладающую разрешением для отправки запроса. По умолчанию используется текущий пользователь.
Введите имя пользователя, например User01 или Domain01\User01, или введите объект PSCredential, созданный командлетомGet-Credential.
Учетные данные можно использовать отдельно или в сочетании с определенными параметрами параметра проверки подлинности . При использовании только для удаленного сервера предоставляются учетные данные, если удаленный сервер отправляет запрос на проверку подлинности. При использовании с параметрами проверки подлинности учетные данные отправляются явным образом.
Учетные данные хранятся в объекте PSCredential , а пароль хранится как SecureString.
Примечание.
Дополнительные сведения о защите данных SecureString см. в разделе "Как безопасна Защита SecureString?".
| Type: | PSCredential |
| Position: | Named |
| Default value: | Current user |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-CustomMethod
Задает пользовательский метод, используемый для веб-запроса. Это можно использовать, если метод запроса, необходимый конечной точкой, недоступен для метода. Метод и CustomMethod нельзя использовать вместе.
В этом примере TEST выполняется HTTP-запрос к API:
Invoke-WebRequest -uri 'https://api.contoso.com/widget/' -CustomMethod 'TEST'
Эта функция была добавлена в PowerShell 6.0.0.
| Type: | String |
| Aliases: | CM |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-DisableKeepAlive
Указывает, что командлет задает значение KeepAlive в заголовке HTTP значение False. По умолчанию Значение KeepAlive имеет значение True. KeepAlive устанавливает постоянное подключение к серверу для упрощения последующих запросов.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Form
Преобразует словарь в отправку multipart/form-data . Форма не может использоваться с текстом.
Если используется ContentType , он игнорируется.
Ключи словаря используются в качестве имен полей формы. По умолчанию значения формы преобразуются в строковые значения.
Если значение является объектом System.IO.FileInfo , то отправляется содержимое двоичного файла. Имя файла отправляется в качестве свойства имени файла. Тип MIME задается как application/octet-stream. Get-Item можно использовать для упрощения предоставления объекта System.IO.FileInfo .
$Form = @{ резюме = Get-Item 'c:\Users\jdoe\Documents\John Doe.pdf' }
Если значение является типом коллекции, такими массивами или списками, поле для поля отправляется несколько раз. Значения списка обрабатываются как строки по умолчанию. Если значение является объектом System.IO.FileInfo , то отправляется содержимое двоичного файла. Вложенные коллекции не поддерживаются.
$Form = @{ теги = "Отпуск", "Италия", "2017" фотографии = Get-ChildItem 'c:\Users\jdoe\Pictures\2017-Italy' }
В приведенном выше примере tags поле предоставляется три раза в форме, один раз для каждого из Vacationних Italyи 2017. Поле pictures также отправляется один раз для каждого файла в папке 2017-Italy . Двоичное содержимое файлов в этой папке отправляется в виде значений.
Эта функция была добавлена в PowerShell 6.1.0.
| Type: | IDictionary |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Headers
Задает заголовки веб-запроса. Введите словарь или хэш-таблицу.
Связанные с содержимым заголовки, например Content-Type переопределяются при указании объекта MultipartFormDataContent для Body.
Начиная с PowerShell 7.4, если этот параметр используется для определения заголовка Content-Type и использования параметра ContentType, используется значение, указанное в параметре ContentType.
| Type: | IDictionary |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-HttpVersion
Указывает версию HTTP, используемую для запроса. Значение по умолчанию — 1.1.
Допустимые значения:
- 1.0
- 1,1
- 2.0
- 3.0
| Type: | Version |
| Position: | Named |
| Default value: | 1.1 |
| 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
Указывает, сколько раз PowerShell перенаправляет подключение к альтернативному универсальному идентификатору ресурса (URI) до сбоя подключения. Значение по умолчанию равно 5. Значение 0 (ноль) запрещает любые перенаправления.
| Type: | Int32 |
| Position: | Named |
| Default value: | 5 |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MaximumRetryCount
Указывает, сколько раз PowerShell повторяет подключение при получении кода сбоя от 400 до 599 включительно или 304. Также см . параметр RetryIntervalSec для указания количества повторных попыток.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Method
Задает метод, используемый для веб-запроса. Допустимые значения для этого параметра:
DefaultDeleteGetHeadMergeOptionsPatchPostPutTrace
Параметр CustomMethod можно использовать для методов запроса, не перечисленных выше.
| Type: | WebRequestMethod |
| Accepted values: | Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-NoProxy
Указывает, что командлет не должен использовать прокси-сервер для достижения назначения. Если необходимо обойти прокси-сервер, настроенный в среде, используйте этот параметр. Эта функция была добавлена в PowerShell 6.0.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-OperationTimeoutSeconds
Это время ожидания применяется к данным, считываемым в потоке, а не к времени потока в целом. Значение по умолчанию 0 указывает неопределенное время ожидания.
Установка значения в 30 секунд означает, что любая задержка в течение 30 секунд между данными в потоке завершает запрос. Большой файл, который занимает несколько минут для скачивания, не завершится, если поток не застопорится более 30 секунд.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-OutFile
Указывает выходной файл, для которого этот командлет сохраняет текст ответа. Введите путь и имя файла.
Если путь не указан, по умолчанию используется текущее расположение. Имя рассматривается как литеральный путь.
Имена, содержащие скобки ([]) должны быть заключены в одинарные кавычки (').
По умолчанию Invoke-WebRequest возвращает результаты конвейера. Чтобы отправить результаты в файл и конвейер, используйте параметр Passthru .
Начиная с PowerShell 7.4, можно указать путь к папке без имени файла. При выполнении имя файла взято из последнего сегмента разрешенного URI после любых перенаправлений. При указании пути к папке для OutFile нельзя использовать параметр Resume .
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PassThru
Указывает, что командлет возвращает результаты, а также записывает их в файл. Этот параметр действителен, только если параметр OutFile также используется в команде.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PreserveAuthorizationOnRedirect
Указывает, что командлет должен сохранять Authorization заголовок при наличии между перенаправлениями.
По умолчанию командлет удаляет Authorization заголовок перед перенаправлением. Указание этого параметра отключает эту логику в случаях, когда заголовок должен быть отправлен в расположение перенаправления.
Эта функция была добавлена в PowerShell 6.0.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PreserveHttpMethodOnRedirect
Указывает, что командлет должен сохранять метод запроса во время перенаправления.
По умолчанию командлет изменяет метод GET при перенаправлении. Указание этого параметра отключает эту логику, чтобы гарантировать, что предполагаемый метод можно использовать с перенаправлением.
Эта функция была добавлена в PowerShell 7.4.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Proxy
Указывает прокси-сервер для запроса, а не подключение непосредственно к интернет-ресурсу. Введите URI сетевого прокси-сервера.
| 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 .
Этот параметр действителен, только если параметр Proxy также используется в команде. Параметры ProxyCredential и ProxyUseDefaultCredentials нельзя использовать в той же команде.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Resume
Выполняет лучшую попытку возобновить скачивание частичного файла. Для возобновления требуется OutFile.
Возобновление работает только с размером локального файла и удаленного файла и не выполняет никакой другой проверки того, что локальный файл и удаленный файл совпадают.
Если размер локального файла меньше размера удаленного файла, командлет пытается возобновить загрузку файла и добавить оставшиеся байты в конец файла.
Если размер локального файла совпадает с размером удаленного файла, то действие не выполняется, а командлет предполагает, что скачивание уже завершено.
Если размер локального файла превышает размер удаленного файла, локальный файл перезаписывается, а весь удаленный файл повторно скачан. Это поведение совпадает с использованием OutFile без возобновления.
Если удаленный сервер не поддерживает возобновление загрузки, локальный файл перезаписывается, а весь удаленный файл повторно скачан. Это поведение совпадает с использованием OutFile без возобновления.
Если локальный файл не существует, создается локальный файл, а весь удаленный файл скачан. Это поведение совпадает с использованием OutFile без возобновления.
Эта функция была добавлена в PowerShell 6.1.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-RetryIntervalSec
Указывает интервал между повторными попытками подключения при получении кода сбоя от 400 до 599 включительно или 304. Также см . параметр MaximumRetryCount для указания количества повторных попыток. Значение должно быть между 1 и [int]::MaxValue.
Если код сбоя равен 429, а ответ включает свойство Retry-After в заголовках, командлет использует это значение для интервала повтора, даже если этот параметр указан.
| Type: | Int32 |
| Position: | Named |
| Default value: | 5 |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SessionVariable
Указывает переменную, для которой этот командлет создает сеанс веб-запроса и сохраняет его в значении.
Введите имя переменной без символа знака доллара ($).
При указании переменной сеанса создает объект сеанса веб-запроса и назначает его переменной Invoke-WebRequest с указанным именем в сеансе PowerShell. Переменную в сеансе можно использовать сразу после выполнения команды.
Перед PowerShell 7.4 сеанс веб-запроса не является постоянным подключением. Это объект, содержащий сведения о подключении и запросе, включая файлы cookie, учетные данные, максимальное значение перенаправления и строку агента пользователя. Его можно использовать для обмена состоянием и данными между веб-запросами.
Начиная с PowerShell 7.4 сеанс веб-запроса сохраняется, пока свойства сеанса не переопределяются в последующем запросе. При их создании командлет повторно создает сеанс с новыми значениями. Постоянные сеансы снижают затраты на повторяющиеся запросы, что делает их гораздо быстрее.
Чтобы использовать сеанс веб-запроса в последующих веб-запросах, укажите переменную сеанса в значении параметра WebSession . PowerShell использует данные в объекте сеанса веб-запроса при установке нового подключения. Чтобы переопределить значение в сеансе веб-запроса, используйте параметр командлета, например UserAgent или Credential. Значения параметров имеют приоритет над значениями в сеансе веб-запроса.
Параметры SessionVariable и WebSession нельзя использовать в той же команде.
| Type: | String |
| Aliases: | SV |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SkipCertificateCheck
Пропускает проверку сертификатов проверка. Сюда входят все проверки, такие как истечение срока действия, отзыв, доверенный корневой центр и т. д.
Предупреждение
Использование этого параметра не является безопасным и не рекомендуется. Этот параметр предназначен только для использования для известных узлов с помощью самозаверяющего сертификата для тестирования. Используйте свой собственный риск.
Эта функция была добавлена в PowerShell 6.0.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SkipHeaderValidation
Указывает, что командлет должен добавлять заголовки в запрос без проверки.
Этот параметр следует использовать для сайтов, требующих значений заголовков, которые не соответствуют стандартам. При указании этого параметра проверка отключается, чтобы разрешить передавать значение без проверка. При указании все заголовки добавляются без проверки.
Этот параметр отключает проверку значений, передаваемых параметрам ContentType, Headers и UserAgent .
Эта функция была добавлена в PowerShell 6.0.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SkipHttpErrorCheck
Этот параметр приводит к тому, что командлет игнорирует состояния ошибки HTTP и продолжает обрабатывать ответы. Ответы на ошибки записываются в конвейер так же, как если бы они были успешными.
Этот параметр появился в PowerShell 7.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SslProtocol
Задает протоколы SSL/TLS, допустимые для веб-запроса. По умолчанию разрешены протоколы SSL/TLS, поддерживаемые системой. SslProtocol позволяет ограничить определенные протоколы в целях соответствия требованиям.
Эти значения определяются как перечисление на основе флага. Можно объединить несколько значений, чтобы задать несколько флагов с помощью этого параметра. Значения можно передать в параметр SslProtocol в виде массива значений или в виде строки, разделенной запятыми этих значений. Командлет объединяет значения с помощью операции binary-OR. Передача значений в виде массива является самым простым параметром, а также позволяет использовать завершение табуляции для значений. Возможно, вы не сможете определить несколько параметров на всех платформах.
Примечание.
На платформах, отличных от Windows, возможно, невозможно предоставить Tls или Tls12 как вариант. Tls13 Поддержка не доступна во всех операционных системах и должна быть проверена на основе каждой операционной системы.
Эта функция была добавлена в PowerShell 6.0.0 и добавлена поддержка Tls13 в PowerShell 7.1.
| Type: | WebSslProtocol |
| Accepted values: | Default, Tls, Tls11, Tls12 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Token
Маркер OAuth или носителя для включения в запрос. Маркер требуется определенными параметрами проверки подлинности . Его нельзя использовать независимо.
Маркер принимает содержащий SecureString маркер. Чтобы предоставить маркер вручную, используйте следующее:
Invoke-WebRequest -Uri $uri -Authentication OAuth -Token (Read-Host -AsSecureString)
Этот параметр появился в PowerShell 6.0.
| Type: | SecureString |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-TransferEncoding
Задает значение для заголовка transfer-encoding ответа HTTP. Допустимые значения для этого параметра:
ChunkedCompressDeflateGZipIdentity
| Type: | String |
| Accepted values: | chunked, compress, deflate, gzip, identity |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UnixSocket
Указывает имя сокета Unix для подключения. Этот параметр поддерживается в системах unix и Windows версии 1803 и более поздних версиях. Дополнительные сведения о поддержке сокетов Unix в Windows см. в записи блога AF_UNIX взаимодействия Windows/WSL.
Этот параметр добавлен в PowerShell 7.4.
| Type: | UnixDomainSocketEndPoint |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Uri
Указывает универсальный идентификатор ресурса (URI) ресурса Интернета, в который отправляется веб-запрос. Введите URI. Этот параметр поддерживает только HTTP или HTTPS.
Этот параметр является обязательным. Uri имени параметра является необязательным .
| Type: | Uri |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UseBasicParsing
Этот параметр устарел. Начиная с PowerShell 6.0.0, все веб-запросы используют только базовый анализ. Этот параметр включен только для обратной совместимости, и любое использование этого параметра не влияет на работу командлета.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UseDefaultCredentials
Указывает, что командлет использует учетные данные текущего пользователя для отправки веб-запроса. Это нельзя использовать с проверкой подлинности или учетными данными и не поддерживается на всех платформах.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UserAgent
Указывает строку агента пользователя для веб-запроса.
Агент пользователя по умолчанию аналогичен Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0 небольшим вариациям для каждой операционной системы и платформы.
Чтобы протестировать веб-сайт со стандартной строкой агента пользователя, используемой большинством интернет-браузеров, используйте свойства класса PSUserAgent, например Chrome, FireFox, Internet Обозреватель, Opera и Safari.
Например, следующая команда использует строку агента пользователя для Обозреватель Интернета:Invoke-WebRequest -Uri https://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-WebSession
Указывает сеанс веб-запроса. Введите имя переменной, включая знак доллара ($).
Чтобы переопределить значение в сеансе веб-запроса, используйте параметр командлета, например UserAgent или Credential. Значения параметров имеют приоритет над значениями в сеансе веб-запроса. Связанные с содержимым заголовки, такие как Content-Type, также переопределяются при указании объекта MultipartFormDataContent для Body.
В отличие от удаленного сеанса, сеанс веб-запроса не является постоянным подключением. Это объект, содержащий сведения о подключении и запросе, включая файлы cookie, учетные данные, максимальное значение перенаправления и строку агента пользователя. Его можно использовать для обмена состоянием и данными между веб-запросами.
Чтобы создать сеанс веб-запроса, введите имя переменной без знака доллара в значении параметра Invoke-WebRequest SessionVariable команды. Invoke-WebRequest создает сеанс и сохраняет его в переменной. В последующих командах используйте переменную в качестве значения параметра WebSession .
Параметры SessionVariable и WebSession нельзя использовать в той же команде.
| Type: | WebRequestSession |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Входные данные
Текст веб-запроса можно передать в этот командлет.
Выходные данные
Этот командлет возвращает объект ответа, представляющий результат веб-запроса.
Примечания
PowerShell включает следующие псевдонимы для Invoke-WebRequest:
- Все платформы:
iwr
Начиная с PowerShell 6.0.0 Invoke-WebRequest , поддерживает только базовый анализ.
Дополнительные сведения см. в разделе BasicHtmlWebResponseObject.
Из-за изменений в .NET Core 3.1 PowerShell 7.0 и более поздних версий используйте свойство HttpClient.DefaultProxy для определения конфигурации прокси-сервера.
Значение этого свойства определяется платформой:
- Для Windows: считывает конфигурацию прокси-сервера из переменных среды. Если эти переменные не определены, свойство является производным от параметров прокси-сервера пользователя.
- Для macOS: считывает конфигурацию прокси-сервера из переменных среды. Если эти переменные не определены, свойство является производным от параметров прокси-сервера системы.
- Для Linux: считывает конфигурацию прокси-сервера из переменных среды. Если эти переменные не определены, свойство инициализирует не настроенный экземпляр, который проходит все адреса.
Переменные среды, используемые для DefaultProxy инициализации на платформах под управлением Windows и Unix, являются следующими:
HTTP_PROXY: имя узла или IP-адрес прокси-сервера, используемого в HTTP-запросах.HTTPS_PROXY: имя узла или IP-адрес прокси-сервера, используемого в HTTPS-запросах.ALL_PROXY: имя узла или IP-адрес прокси-сервера, используемого в http-запросах и HTTPS в случаеHTTP_PROXYилиHTTPS_PROXYне определено.NO_PROXY: список имен узлов, разделенных запятыми, которые следует исключить из прокси-сервера.
PowerShell 7.4 добавила поддержку алгоритма сжатия Brotli.
Связанные ссылки
PowerShell
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по