Invoke-WebRequest

Модуль:

Microsoft.PowerShell.Utility Module

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

Синтаксис

Default (По умолчанию)

Invoke-WebRequest
    [-UseBasicParsing]
    [-Uri] <Uri>
    [-WebSession <WebRequestSession>]
    [-SessionVariable <String>]
    [-Credential <PSCredential>]
    [-UseDefaultCredentials]
    [-CertificateThumbprint <String>]
    [-Certificate <X509Certificate>]
    [-UserAgent <String>]
    [-DisableKeepAlive]
    [-TimeoutSec <Int32>]
    [-Headers <IDictionary>]
    [-MaximumRedirection <Int32>]
    [-Method <WebRequestMethod>]
    [-Proxy <Uri>]
    [-ProxyCredential <PSCredential>]
    [-ProxyUseDefaultCredentials]
    [-Body <Object>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [<CommonParameters>]

Описание

Командлет Invoke-WebRequest отправляет запросы HTTP, HTTPS, FTP и FILE на веб-страницу или веб-службу. Он анализирует ответ и возвращает коллекции форм, ссылок, изображений и других важных ЭЛЕМЕНТОВ HTML.

Этот командлет был введён в Windows PowerShell 3.0.

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

По умолчанию Invoke-WebRequest анализирует содержимое веб-страницы. Код скрипта на веб-странице может выполняться при синтаксическом анализе страницы. -UseBasicParsing Используйте параметр, чтобы избежать выполнения кода скрипта.

Эта команда может выполняться с помощью iwrпсевдонимов или wget ,curl.

Примеры

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

В этом примере командлет используется Invoke-WebRequest для отправки веб-запроса на сайт Bing.com.

$Response = Invoke-WebRequest -UseBasicParsing -Uri https://www.bing.com?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

Данные, возвращаемые Invoke-WebRequest переменной, хранятся в переменной $Response . Свойство InputFields ответа содержит поля формы. Where-Object используется для фильтрации полей формы на те, где свойство имени похоже на "* Значение". Отфильтрованные результаты передаются для Select-Object выбора свойств "Имя" и "Значение".

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

В этом примере показано, как использовать командлет Invoke-WebRequest с веб-службой с отслеживанием состояния, например Facebook.

$R = Invoke-WebRequest https://www.facebook.com/login.php -SessionVariable fb
# This command stores the first form in the Forms property of the $R variable in the $Form variable.
$Form = $R.Forms[0]
# This command shows the fields available in the form.
$Form.Fields

Key                     Value
---                     -----
...
email
pass
...

# These commands populate the username and password of the respective form fields.
$Form.Fields["email"]="User01@Fabrikam.com"
$Form.Fields["pass"]="P@ssw0rd"
# This command creates the Uri that will be used to log in to facebook.
# The value of the Uri parameter is the value of the Action property of the form.
$Uri = "https://www.facebook.com" + $Form.Action
# Now the Invoke-WebRequest cmdlet is used to sign into the Facebook web service.
# The WebRequestSession object in the $FB variable is passed as the value of the WebSession parameter.
# The value of the Body parameter is the hash table in the Fields property of the form.
# The value of the *Method* parameter is POST. The command saves the output in the $R variable.
$R = Invoke-WebRequest -Uri $Uri -WebSession $FB -Method Post -Body $Form.Fields
$R.StatusDescription

Первая команда использует командлет Invoke-WebRequest для отправки запроса на вход. Команда задает значение FB для значения параметра SessionVariable и сохраняет результат в переменной $R. По завершении команды переменная $R содержит HtmlWebResponseObject, а переменная $FB содержит объект WebRequestSession.

После входа командлета Invoke-WebRequest в facebook StatusDescription свойство объекта веб-ответа в переменной $R указывает, что пользователь успешно вошел в систему.

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

Эта команда получает ссылки на веб-странице.

(Invoke-WebRequest -Uri "https://devblogs.microsoft.com/powershell/").Links.Href

Командлет Invoke-WebRequest получает содержимое веб-страницы. Затем свойство Links возвращаемого HtmlWebResponseObj ect используется для отображения свойства Href каждой ссылки.

Пример 4. Перехват сообщений об успешном выполнении из 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 , который извлекает StatusCode из объекта Exception .

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

Командлет 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
}

Замечание

Чтобы использовать Start-ThreadJob командлет, необходимо установить модуль ThreadJob из коллекция PowerShell.

Параметры

-Body

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

Параметр body можно использовать для указания списка параметров запроса или указания содержимого ответа.

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

Если текст является формой или выходными данными вызова Invoke-WebRequest, PowerShell задает содержимое запроса полям формы. Рассмотрим пример.

$r = Invoke-WebRequest https://website.com/login.aspx $r.Forms[0].Name = "MyName" $r.Forms[0].Password = "MyPassword" Invoke-RestMethod https://website.com/service.aspx -Body $r

• или -

Invoke-RestMethod https://website.com/service.aspx -Body $r.Forms[0]

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

Тип:	Object
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

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

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	True
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-Certificate

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

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

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

Тип:	X509Certificate
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

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

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-CertificateThumbprint

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

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

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

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

Тип:	String
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

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

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-ContentType

Указывает тип контента веб-запроса.

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

Если параметр не указан, тип контента может отличаться в зависимости от используемого метода HTTP:

• Для метода POST тип контента application/x-www-form-urlencoded
• Для метода PUT тип контента application/json
• Для других методов тип контента не указан в запросе.

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

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

Тип:	String
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

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

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-Credential

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

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

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

Замечание

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

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

Тип:	PSCredential
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

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

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-DisableKeepAlive

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

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

Тип:	SwitchParameter
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

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

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-Headers

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

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

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

Тип:	IDictionary
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

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

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-InFile

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

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

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

Тип:	String
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

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

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-MaximumRedirection

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

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

Тип:	Int32
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

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

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-Method

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

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

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

Тип:	WebRequestMethod
Default value:	None
Допустимые значения:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Поддерживаются подстановочные знаки:	False
DontShow:	False

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

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-OutFile

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

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

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

Тип:	String
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

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

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-PassThru

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

Замечание

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

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

Тип:	SwitchParameter
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

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

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-Proxy

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

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

Тип:	Uri
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

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

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-ProxyCredential

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

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

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

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

Тип:	PSCredential
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

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

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-ProxyUseDefaultCredentials

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

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

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

Тип:	SwitchParameter
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

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

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-SessionVariable

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

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

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

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

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

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

Тип:	String
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False
Aliases:	SV

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

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-TimeoutSec

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

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

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

Тип:	Int32
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

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

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-TransferEncoding

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

• Chunked
• Compress
• Deflate
• GZip
• Identity

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

Тип:	String
Default value:	None
Допустимые значения:	chunked, compress, deflate, gzip, identity
Поддерживаются подстановочные знаки:	False
DontShow:	False

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

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-Uri

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

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

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

Тип:	Uri
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

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

(All)

Position:	0
Обязательно:	True
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-UseBasicParsing

Указывает, что командлет использует объект ответа для HTML-содержимого без синтаксического анализа объектной модели документа (DOM). Этот параметр требуется, если Internet Explorer не установлен на компьютерах, например на установке основных серверных компонентов операционной системы Windows Server.

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

Тип:	SwitchParameter
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

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

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-UseDefaultCredentials

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

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

Тип:	SwitchParameter
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

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

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-UserAgent

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

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

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

Тип:	String
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

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

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-WebSession

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

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

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

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

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

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

Тип:	WebRequestSession
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

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

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

CommonParameters

Этот командлет поддерживает общие параметры: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction и -WarningVariable. Дополнительные сведения см. в разделе about_CommonParameters.

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

Object

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

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

HtmlWebResponseObject

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

Примечания

Windows PowerShell включает следующие псевдонимы для Invoke-WebRequest:

• iwr
• curl
• wget

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

• Invoke-RestMethod
• ConvertFrom-Json
• ConvertTo-Json