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

Invoke-WebRequest

  • Ссылка
Модуль:
Microsoft.PowerShell.Utility

Получает содержимое из веб-страницы в Интернете.

Синтаксис

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-Type text/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.

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

-AllowUnencryptedAuthentication

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

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

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

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

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

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

Тип:WebAuthenticationType
Допустимые значения:None, Basic, Bearer, OAuth
Position:Named
Default value:None
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-Body

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

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

Если входные данные являются запросом 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.

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

-Certificate

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

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

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

-CertificateThumbprint

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

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

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

Примечание.

Эта функция поддерживается только на платформах ОС Windows.

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

-ConnectionTimeoutSeconds

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

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

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

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

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

-Credential

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

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

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

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

Примечание.

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

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

-CustomMethod

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

В этом примере TEST выполняется HTTP-запрос к API:

Invoke-WebRequest -uri 'https://api.contoso.com/widget/' -CustomMethod 'TEST'

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

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

-DisableKeepAlive

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

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

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

-Headers

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

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

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

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

-HttpVersion

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

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

  • 1.0
  • 1,1
  • 2.0
  • 3.0
Тип:Version
Position:Named
Default value:1.1
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-InFile

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

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

-MaximumRedirection

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

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

-MaximumRetryCount

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

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

-Method

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

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

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

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

-NoProxy

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

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

-OperationTimeoutSeconds

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

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

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

-OutFile

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

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

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

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

-PassThru

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

Примечание.

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

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

-PreserveAuthorizationOnRedirect

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

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

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

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

-PreserveHttpMethodOnRedirect

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

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

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

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

-Proxy

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

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

-ProxyCredential

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

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

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

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

-ProxyUseDefaultCredentials

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

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

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

-Resume

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

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

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

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

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

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

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

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

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

-RetryIntervalSec

Указывает интервал между повторными попытками подключения при получении кода сбоя от 400 до 599 включительно или 304. Также см . параметр MaximumRetryCount для указания количества повторных попыток. Значение должно быть между 1 и [int]::MaxValue.

Если код сбоя равен 429, а ответ включает свойство Retry-After в заголовках, командлет использует это значение для интервала повтора, даже если этот параметр указан.

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

-SessionVariable

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

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

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

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

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

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

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

-SkipCertificateCheck

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

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

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

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

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

-SkipHeaderValidation

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

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

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

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

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

-SkipHttpErrorCheck

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

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

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

-SslProtocol

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

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

Примечание.

На платформах, отличных от Windows, возможно, невозможно предоставить Tls или Tls12 как вариант. Tls13 Поддержка не доступна во всех операционных системах и должна быть проверена на основе каждой операционной системы.

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

Тип:WebSslProtocol
Допустимые значения:Default, Tls, Tls11, Tls12
Position:Named
Default value:None
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-Token

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

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

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

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

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

-TransferEncoding

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

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

-UnixSocket

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

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

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

-Uri

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

Этот параметр является обязательным. Uri имени параметра является необязательным .

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

-UseBasicParsing

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

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

-UseDefaultCredentials

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

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

-UserAgent

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

Агент пользователя по умолчанию аналогичен Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0 небольшим вариациям для каждой операционной системы и платформы.

Чтобы протестировать веб-сайт со стандартной строкой агента пользователя, используемой большинством интернет-браузеров, используйте свойства класса PSUserAgent , такие как Chrome, FireFox, InternetExplorer, Opera и Safari.

Например, следующая команда использует строку агента пользователя для Internet Explorer: Invoke-WebRequest -Uri https://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)

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

-WebSession

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

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

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

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

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

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

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

Object

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

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

BasicHtmlWebResponseObject

Этот командлет возвращает объект ответа, представляющий результат веб-запроса.

Примечания

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.