Invoke-WebRequest

Ссылка

Модуль:: Microsoft.PowerShell.Utility

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

Синтаксис

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.

Примечание.

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

Внимание

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

Примеры

Пример 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 возвращаемого HtmlWebResponseObject используется для отображения свойства Href каждой ссылки.

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

Примечание.

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

-Certificate

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

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

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

-CertificateThumbprint

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

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

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

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

-Credential

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

Введите имя пользователя, например User01 или

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

Примечание.

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

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

-DisableKeepAlive

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

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

-Headers

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

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

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

-InFile

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

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

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

-MaximumRedirection

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

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

-Method

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

Default
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace

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

-OutFile

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

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

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

-PassThru

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

Примечание.

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

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

-ProxyUseDefaultCredentials

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

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

-SessionVariable

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

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

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

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

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

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

-TimeoutSec

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

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

Тип:	Int32
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

-Uri

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

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

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

-UseBasicParsing

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

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

-UseDefaultCredentials

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

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

-WebSession

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

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

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

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

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

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

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

Object

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

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

HtmlWebResponseObject

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

Примечания

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

iwr

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

Invoke-WebRequest

Синтаксис

Описание

Примеры

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

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

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

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

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

Параметры

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

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

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

Примечания

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