Invoke-WebRequest

モジュール:: Microsoft.PowerShell.Utility

インターネット上の Web ページからコンテンツを取得します。

構文

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 の要求を Web ページまたは Web サービスに送信します。さらに、応答を解析し、フォーム、リンク、画像、およびその他の重要な HTML 要素のコレクションを返します。

このコマンドレットは、Windows PowerShell 3.0 で導入されました。

注

既定では、ページを解析して ParsedHtml プロパティを設定するときに、Web ページのスクリプトコードを実行できます。これを抑制するには、 -UseBasicParsing スイッチを使用します。

例

例 1: Web 要求を送信する

このコマンドでは、 Invoke-WebRequest コマンドレットを使用して、Bing.com サイトに Web 要求を送信します。

$R = Invoke-WebRequest -URI https://www.bing.com?q=how+many+feet+in+a+mile
$R.AllElements | Where-Object {
    $_.name -like "* Value" -and $_.tagName -eq "INPUT"
} | Select-Object Name, Value

name       value
----       -----
From Value 1
To Value   5280

最初のコマンドは要求を発行し、応答を $R 変数に保存します。

2 番目のコマンドは、 AllElements プロパティ内のオブジェクトをフィルター処理します。このオブジェクトは、 name プロパティが "* Value" のようで、 tagName が "INPUT" のようです。フィルター処理された結果は Select-Object にパイプ処理され、 name および value プロパティが選択されます。

例 2: ステートフル Web サービスを使用する

この例では、Facebook などのステートフル Web サービスで Invoke-WebRequest コマンドレットを使用する方法を示します。

$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 コマンドレットを使用してサインイン要求を送信します。このコマンドは、 SessionVariable パラメーターの値に "FB" の値を指定し、結果を $R 変数に保存します。コマンドが完了すると、 $R 変数には HtmlWebResponseObject が含まれており、 $FB 変数には WebRequestSession オブジェクトが含まれます。

Invoke-WebRequest コマンドレットが facebook にサインインすると、変数の Web 応答オブジェクトの $R プロパティは、ユーザーが正常にサインインしたことを示します。

例 3: Web ページからリンクを取得する

このコマンドは、Web ページ内のリンクを取得します。

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

Invoke-WebRequest コマンドレットは、Web ページのコンテンツを取得します。次に、返された HtmlWebResponseObject の Links プロパティを使用して、各リンクの Href プロパティを表示します。

例 4: Invoke-WebRequest から成功以外のメッセージをキャッチする

Invoke-WebRequest が成功しない HTTP メッセージ (404、500 など) を検出すると、出力は返されません。終了エラーがスローされます。エラーをキャッチし、StatusCode を表示するには、try/catch ブロックで実行を囲むことができます。次の例は、これを実現する方法を示しています。

try
{
    $response = Invoke-WebRequest -Uri "www.microsoft.com/unkownhost" -ErrorAction Stop
    # This will only execute if the Invoke-WebRequest is successful.
    $StatusCode = $Response.StatusCode
}
catch
{
    $StatusCode = $_.Exception.Response.StatusCode.value__
}
$StatusCode

404

最初のコマンドは、ErrorAction を Stop にして Invoke-WebRequest を呼び出し、失敗した要求に対して Invoke-WebRequest に終了エラーをスローするように強制します。終了エラーは、Exception オブジェクトから StatusCode を取得する catch ブロックによってキャッチされます。

パラメーター

-Body

要求の本文を指定します。本文は、ヘッダーに続く要求の内容です。本文の値を Invoke-WebRequest にパイプすることもできます。

Body パラメーターを使用して、クエリパラメーターの一覧を指定したり、応答の内容を指定したりできます。

入力が GET 要求であり、本文が IDictionary (通常はハッシュテーブル) である場合、本文はクエリパラメーターとして URI に追加されます。その他の GET 要求の場合、本文は標準の 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
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	True
ワイルドカード文字を受け取る:	False

-Certificate

セキュア Web 要求に使用されるクライアント証明書を指定します。証明書を含む変数、または証明書を取得するコマンドまたは式を入力します。

証明書を検索するには、Get-PfxCertificateを使用するか、証明書 (Cert:) ドライブの Get-ChildItem コマンドレットを使用します。証明書が有効でない場合、または十分な権限を持っていない場合、コマンドは失敗します。

型:	X509Certificate
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-CertificateThumbprint

要求を送信するアクセス許可を持つユーザーアカウントのデジタル公開キー証明書 (X509) を指定します。証明書の拇印を入力します。証明書は、クライアント証明書ベースの認証で使用されます。これらはローカルユーザーアカウントにのみマップできます。ドメインアカウントでは機能しません。

証明書の拇印を取得するには、PowerShell Get-Item ドライブの Get-ChildItem または Cert: コマンドを使用します。

型:	String
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-ContentType

Web 要求のコンテンツタイプを指定します。

このパラメータを省略し、リクエストメソッドが POST の場合、 Invoke-WebRequest はコンテンツタイプを application/x-www-form-urlencoded に設定します。それ以外の場合、コンテンツ・タイプは呼び出しで指定されません。

型:	String
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-Credential

要求を送信するアクセス許可を持つユーザーアカウントを指定します。既定値は現在のユーザーです。

User01 や Domain01\User01などのユーザー名を入力するか、PSCredential オブジェクト (Get-Credential コマンドレットによって生成されたものなど) を入力します。

型:	PSCredential
配置:	Named
規定値:	Current user
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-DisableKeepAlive

コマンドレットが HTTP ヘッダーの KeepAlive 値を False に設定することを示します。既定では、KeepAlive は true です。 KeepAlive は、後続の要求を容易にするために、サーバーへの永続的な接続を確立します。

型:	SwitchParameter
配置:	Named
規定値:	KeepAlive
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-Headers

Web 要求のヘッダーを指定します。ハッシュテーブルまたはディクショナリを入力します。

UserAgent ヘッダーを設定するには、UserAgent パラメーターを使用します。このパラメーターを使用して、 UserAgent または Cookie ヘッダーを指定することはできません。

型:	IDictionary
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-InFile

ファイルから Web 要求の内容を取得します。

パスとファイル名を入力します。パスを省略した場合、既定値は現在の場所です。

型:	String
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-MaximumRedirection

接続が失敗するまでに、PowerShell が代替 Uniform Resource Identifier (URI) に接続をリダイレクトする回数を指定します。既定値は 5 です。値が 0 (ゼロ) の場合、すべてのリダイレクトが禁止されます。

型:	Int32
配置:	Named
規定値:	5
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-Method

Web 要求に使用するメソッドを指定します。このパラメーターに使用できる値は次のとおりです。

既定値
削除
取得
頭
統合
オプション
パッチ
投稿
置く
トレース

型:	WebRequestMethod
指定可能な値:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
配置:	Named
規定値:	Default
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-OutFile

このコマンドレットが応答本文を保存する出力ファイルを指定します。パスとファイル名を入力します。パスを省略した場合、既定値は現在の場所です。

既定では、Invoke-WebRequest は結果をパイプラインに返します。結果をファイルおよびパイプラインに送信するには、 Passthru パラメーターを使用します。

型:	String
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-PassThru

ファイルに書き込むだけでなく、コマンドレットによって結果が返されることを示します。このパラメーターは、OutFile パラメーターがコマンドでも使用されている場合にのみ有効です。

型:	SwitchParameter
配置:	Named
規定値:	False
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-Proxy

インターネットリソースに直接接続するのではなく、要求のプロキシサーバーを指定します。ネットワークプロキシサーバーの URI を入力します。

型:	Uri
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-ProxyCredential

Proxy パラメーターで指定されたプロキシサーバーを使用するアクセス許可を持つユーザーアカウントを指定します。既定値は現在のユーザーです。

このパラメーターは、Proxy パラメーターもコマンドで使用されている場合にのみ有効です。 ProxyCredential パラメーターと ProxyUseDefaultCredentials パラメーターを同じコマンドで使用することはできません。

型:	PSCredential
配置:	Named
規定値:	Current user
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-ProxyUseDefaultCredentials

コマンドレットが現在のユーザーの資格情報を使用して、Proxy パラメーターで指定されたプロキシサーバーにアクセスすることを示します。

型:	SwitchParameter
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-SessionVariable

このコマンドレットが Web 要求セッションを作成し、値に保存する変数を指定します。ドル記号 ($) 記号を使用せずに変数名を入力します。

セッション変数を指定すると、Invoke-WebRequest Web 要求セッションオブジェクトが作成され、PowerShell セッションで指定した名前の変数に割り当てられます。この変数は、コマンドが完了するとすぐにセッションで使用できます。

リモートセッションとは異なり、Web 要求セッションは永続的な接続ではありません。 Web 要求セッションは、Cookie、資格情報、リダイレクトの最大値、ユーザーエージェント文字列などの、接続と要求に関する情報を含むオブジェクトです。これを使用して、Web 要求間で状態とデータを共有できます。

後続の Web 要求で Web 要求セッションを使用するには、WebSession パラメーターの値にセッション変数を指定します。 PowerShell では、新しい接続を確立するときに、Web 要求セッションオブジェクトのデータが使用されます。 Web 要求セッションの値をオーバーライドするには、UserAgent や資格情報などのコマンドレットパラメーターを使用します。パラメーター値は、Web 要求セッションの値よりも優先されます。

SessionVariable パラメータと WebSession パラメータを同じコマンドで使用することはできません。

型:	String
Aliases:	SV
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-TimeoutSec

タイムアウトするまでの要求の保留期間を指定します。値を秒単位で入力します。既定値の 0 は、無期限のタイムアウトを指定します。

ドメインネームシステム (DNS) クエリの戻りまたはタイムアウトには最大 15 秒かかることがあります。要求に解決が必要なホスト名が含まれており、 TimeoutSec を 0 より大きい値に設定したが 15 秒未満の場合、 WebException がスローされて要求がタイムアウトするまでに 15 秒以上かかることがあります。

型:	Int32
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-TransferEncoding

転送エンコード HTTP 応答ヘッダーの値を指定します。このパラメーターに使用できる値は次のとおりです。

チャンク化された
圧縮する
空気を抜く
ジージープ
アイデンティティ

型:	String
指定可能な値:	chunked, compress, deflate, gzip, identity
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-Uri

Web 要求の送信先の Uniform Resource Identifier (URI) を指定します。 URI を入力します。このパラメーターは、HTTP、HTTPS、FTP、および FILE の値をサポートします。

このパラメーターは必須です。

型:	Uri
配置:	0
規定値:	None
必須:	True
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-UseBasicParsing

コマンドレットがドキュメントオブジェクトモデル (DOM) 解析なしで HTML コンテンツに応答オブジェクトを使用することを示します。このパラメーターは、Windows Server オペレーティングシステムの Server Core インストールなど、コンピューターに Internet Explorer がインストールされていない場合に必要です。

型:	SwitchParameter
配置:	Named
規定値:	False
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-UseDefaultCredentials

cmdet が現在のユーザーの資格情報を使用して Web 要求を送信することを示します。

型:	SwitchParameter
配置:	Named
規定値:	False
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-UserAgent

Web 要求のユーザーエージェント文字列を指定します。既定のユーザーエージェントは、オペレーティングシステムとプラットフォームごとに若干のバリエーションがある Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US) WindowsPowerShell/3.0 に似ています。

ほとんどのインターネットブラウザーで使用される標準のユーザーエージェント文字列を使用して Web サイトをテストするには、Chrome、FireFox、InternetExplorer、Opera、Safari などの PSUserAgent クラスのプロパティを使用します。たとえば、次のコマンドでは、Internet Explorer のユーザーエージェント文字列を使用します

型:	String
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-WebSession

Web 要求セッションを指定します。ドル記号 ($) を含む変数名を入力します。

Web 要求セッションの値をオーバーライドするには、UserAgent や資格情報などのコマンドレットパラメーターを使用します。パラメーター値は、Web 要求セッションの値よりも優先されます。

Web 要求セッションを作成するには、Invoke-WebRequest コマンドの SessionVariable パラメーターの値に変数名 (ドル記号なし) を入力します。 Invoke-WebRequest セッションを作成し、変数に保存します。後続のコマンドでは、変数を WebSession パラメーターの値として使用します。