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]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-RetryIntervalSec <Int32>]
      [-Method <WebRequestMethod>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [-PreserveAuthorizationOnRedirect]
      [-SkipHeaderValidation]
      [<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]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-RetryIntervalSec <Int32>]
      [-Method <WebRequestMethod>]
      -NoProxy
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [-PreserveAuthorizationOnRedirect]
      [-SkipHeaderValidation]
      [<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]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-RetryIntervalSec <Int32>]
      -CustomMethod <String>
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [-PreserveAuthorizationOnRedirect]
      [-SkipHeaderValidation]
      [<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]
      [-TimeoutSec <Int32>]
      [-Headers <IDictionary>]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-RetryIntervalSec <Int32>]
      -CustomMethod <String>
      -NoProxy
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [-PreserveAuthorizationOnRedirect]
      [-SkipHeaderValidation]
      [<CommonParameters>]

Описание

Командлет Invoke-WebRequest отправляет HTTP- и HTTPS-запросы на веб-страницу или веб-службу. Анализирует ответ и возвращает коллекции ссылок, изображений и других значимых HTML-элементов.

Этот командлет появился в PowerShell 3.0.

Начиная с PowerShell 7.0, поддерживает конфигурацию прокси-сервера, Invoke-WebRequest определяемую переменными среды. См. раздел Примечания этой статьи.

Важно!

Примеры в этой статье ссылались на узлы в домене contoso.com . Это вымышленный домен, используемый корпорацией Майкрософт в качестве примеров. В примерах показано, как использовать командлеты. Однако, так как contoso.com сайты не существуют, примеры не работают. Адаптируйте примеры к узлам в вашей среде.

Примеры

Пример 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 . После выполнения команды переменная содержит объект BasicHtmlWebResponseObject, $LoginResponse а $Session переменная — WebRequestSession объект . При этом пользователь регистрируется на сайте.

Второй вызов для Invoke-WebRequest получения профиля пользователя, который требует, чтобы пользователь вошел на сайт. Данные сеанса, хранящиеся в переменной $Session , предоставляют файлы cookie сеанса сайту, созданному во время входа.

Пример 3. Получение ссылок с веб-страницы

В этом примере возвращаются ссылки на веб-странице. Для получения содержимого веб-страницы Invoke-WebRequest используется командлет . Затем используется свойство Links возвращаемого объекта BasicHtmlWebResponseObjectInvoke-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 для записи содержимого ответа в файл. Свойство Encoding объекта ответа используется для задания кодировки для файла.

Последние несколько команд записывают свойство Content в файл, а затем удаляют StreamWriter.

Обратите внимание, что свойство Encoding имеет значение NULL, если веб-запрос не возвращает текстовое содержимое.

Пример 5. Отправка файла multipart/form-data

В этом примере командлет 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 имена ключей используются в качестве имен полей формы. По умолчанию значения HashTable преобразуются в строки. Если имеется значение System.IO.FileInfo , содержимое файла отправляется. Если коллекция, например массивы или списки, присутствует, поле формы отправляется несколько раз.

При использовании Get-Item в avatar ключе FileInfo объект задается в качестве значения . В результате данные изображения для jdoe.png будут отправлены.

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

Пример 7. Перехват сообщений об успешном выполнении из Invoke-WebRequest

При Invoke-WebRequest обнаружении сообщения HTTP, которое не является успешным (404, 500 и т. д.), оно не возвращает выходные данные и выдает завершающую ошибку. Чтобы поймать ошибку и просмотреть StatusCode , можно заключить выполнение в 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 , который извлекает Код состояния из объекта 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 возвращаемого объекта BasicHtmlWebResponseObjectInvoke-WebRequest и свойство Href каждой ссылки.

(Invoke-WebRequest -Uri 'https://aka.ms/pscore6-docs' -HttpVersion 2.0).Links.Href

Параметры

-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. Параметр Authentication нельзя использовать с параметром UseDefaultCredentials .

Доступные параметры проверки подлинности:

None: это параметр по умолчанию, если проверка подлинности не указана. Явная проверка подлинности не используется.
Basic: требуются учетные данные. Учетные данные отправляются в виде заголовка обычной проверки подлинности Authorization: Basic RFC 7617 в формате base64(user:password).
Bearer: требуется параметр Token . Отправляет заголовок RFC 6750 Authorization: Bearer с предоставленным маркером.
OAuth: требуется параметр Token . Отправляет заголовок RFC 6750 Authorization: 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-PfxCertificate или используйте Get-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

-ContentType

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

Если значение ContentType содержит формат кодирования (как charset), командлет использует этот формат для кодирования текста веб-запроса. Если в ContentType не указан формат кодирования, вместо него используется формат кодирования по умолчанию. Примером ContentType с форматом кодирования является text/plain; charset=iso-8859-5, который указывает латинский/кириллический алфавит.

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

ContentType переопределяется при указании объекта MultipartFormDataContent для текста.

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 см. в разделе Как безопасно secure is 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 , то отправляется содержимое двоичного файла. Имя файла отправляется в качестве свойства filename . Тип MIME имеет значение application/octet-stream. Get-Item можно использовать для упрощения предоставления объекта System.IO.FileInfo .

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

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

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

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

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

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

-Headers

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

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

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

-HttpVersion

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

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

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

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

Default
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace

Параметр 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

-OutFile

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

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

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

-Proxy

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

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

-ProxyCredential

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

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

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

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

-ProxyUseDefaultCredentials

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

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

-Resume

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

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

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

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

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

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

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

Эта функция была добавлена в 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.

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

-TimeoutSec

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

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

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

-Token

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

Маркер принимает объект , 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. Допустимые значения для этого параметра:

Chunked
Compress
Deflate
GZip
Identity

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

-Uri

Указывает универсальный код ресурса (URI) интернет-ресурса, которому отправляется веб-запрос. Введите 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, InternetExplorer, 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-WebRequestSessionVariable команды. Invoke-WebRequest создает сеанс и сохраняет его в переменной . В последующих командах используйте переменную в качестве значения параметра WebSession.

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

Type:	WebRequestSession
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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: разделенный запятыми список имен узлов, которые следует исключить из прокси-сервера.

Share via

Invoke-WebRequest

Синтаксис

Описание

Примеры

Пример 1. Отправка веб-запроса

Пример 2. Использование веб-службы с отслеживанием состояния

Пример 3. Получение ссылок с веб-страницы

Пример 4. Запись содержимого ответа в файл с использованием кодировки, определенной на запрошенной странице

Пример 5. Отправка файла multipart/form-data

Пример 6. Упрощенная отправка нескольких частей или форм-данных

Пример 7. Перехват сообщений об успешном выполнении из Invoke-WebRequest

Пример 8. Одновременное скачивание нескольких файлов

Пример 9. Пропуск проверки заголовка

Пример 10. Отправка запроса по протоколу HTTP 2.0

Параметры

-AllowUnencryptedAuthentication

-Authentication

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-CustomMethod

-DisableKeepAlive

-Form

-Headers

-HttpVersion

-InFile

-MaximumRedirection

-MaximumRetryCount

-Method

-NoProxy

-OutFile

-PassThru

-PreserveAuthorizationOnRedirect

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-Resume

-RetryIntervalSec

-SessionVariable

-SkipCertificateCheck

-SkipHeaderValidation

-SkipHttpErrorCheck

-SslProtocol

-TimeoutSec

-Token

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

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

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

Примечания

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

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