Invoke-RestMethod

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

HTTP または HTTPS 要求を RESTful Web サービスに送信します。

構文

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

説明

Invoke-RestMethod コマンドレットは、HTTP 要求と HTTPS 要求を Representational State Transfer (REST) Web サービスに送信し、その要求はリッチに構造化されたデータを返します。

Windows PowerShell は、データ型に基づいて応答を書式設定します。 RSS フィードまたは ATOM フィードの場合、Windows PowerShell は Item XML ノードまたは Entry XML ノードを返します。 JavaScript Object Notation (JSON) または XML の場合、Windows PowerShell はコンテンツをオブジェクトに変換 (または逆シリアル化) します。

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

注

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

例

例 1: PowerShell RSS フィードを取得する

Invoke-RestMethod -Uri https://blogs.msdn.microsoft.com/powershell/feed/ |
  Format-Table -Property Title, pubDate

Title                                                                pubDate
-----                                                                -------
Join the PowerShell 10th Anniversary Celebration!                    Tue, 08 Nov 2016 23:00:04 +0000
DSC Resource Kit November 2016 Release                               Thu, 03 Nov 2016 00:19:07 +0000
PSScriptAnalyzer Community Call - Oct 18, 2016                       Thu, 13 Oct 2016 17:52:35 +0000
New Home for In-Box DSC Resources                                    Sat, 08 Oct 2016 07:13:10 +0000
New Social Features on Gallery                                       Fri, 30 Sep 2016 23:04:34 +0000
PowerShellGet and PackageManagement in PowerShell Gallery and GitHub Thu, 29 Sep 2016 22:21:42 +0000
PowerShell Security at DerbyCon                                      Wed, 28 Sep 2016 01:13:19 +0000
DSC Resource Kit September Release                                   Thu, 22 Sep 2016 00:25:37 +0000
PowerShell DSC and implicit remoting broken in KB3176934             Tue, 23 Aug 2016 15:07:50 +0000
PowerShell on Linux and Open Source!                                 Thu, 18 Aug 2016 15:32:02 +0000

このコマンドでは、Invoke-RestMethod コマンドレットを使用して、PowerShell ブログ RSS フィードから情報を取得します。このコマンドでは、Format-Table コマンドレットを使用して、各ブログの Title および pubDate プロパティの値をテーブルに表示します。

例 2

次の例では、ユーザーが Invoke-RestMethod を実行して、ユーザーの組織内のイントラネット Web サイトで POST 要求を実行します。

$Cred = Get-Credential

# Next, allow the use of self-signed SSL certificates.

[System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $True }

# Create variables to store the values consumed by the Invoke-RestMethod command.
# The search variable contents are later embedded in the body variable.

$Server = 'server.contoso.com'
$Url = "https://${server}:8089/services/search/jobs/export"
$Search = "search index=_internal | reverse | table index,host,source,sourcetype,_raw"

# The cmdlet handles URL encoding. The body variable describes the search criteria, specifies CSV as the output mode, and specifies a time period for returned data that starts two days ago and ends one day ago. The body variable specifies values for parameters that apply to the particular REST API with which Invoke-RestMethod is communicating.

$Body = @{
    search = $Search
    output_mode = "csv"
    earliest_time = "-2d@d"
    latest_time = "-1d@d"
}

# Now, run the Invoke-RestMethod command with all variables in place, specifying a path and file name for the resulting CSV output file.

Invoke-RestMethod -Method Post -Uri $url -Credential $Cred -Body $body -OutFile output.csv

{"preview":true,"offset":0,"result":{"sourcetype":"contoso1","count":"9624"}}

{"preview":true,"offset":1,"result":{"sourcetype":"contoso2","count":"152"}}

{"preview":true,"offset":2,"result":{"sourcetype":"contoso3","count":"88494"}}

{"preview":true,"offset":3,"result":{"sourcetype":"contoso4","count":"15277"}}

例 3: 複数のヘッダーを渡す

$headers = @{
    'userId' = 'UserIDValue'
    'token' = 'TokenValue'
}
Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $body

API では、多くの場合、認証や検証などに渡されたヘッダーが必要です。

この例では、hash-table から REST API に複数のヘッダーを渡す方法を示します。

パラメーター

-Body

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

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

入力が GET 要求で、本文が IDictionary (通常はハッシュテーブル) の場合、本文はクエリパラメーターとして URI に追加されます。その他の要求の種類 (POST など) の場合、本文は標準の name=value 形式で要求本文の値として設定されます。

警告: POST 本文の詳細な出力は、本文のサイズが既知であり、Content-Length HTTP ヘッダーで送信されていても、with -1-byte payload で終わります。

本文がフォームの場合、または別の Invoke-WebRequest 呼び出しの出力である場合、Windows PowerShell は要求の内容をフォームフィールドに設定します。

例えば次が挙げられます。

$R = Invoke-WebRequest https://website.com/login.aspx $R.Forms[0] です。Name = "MyName" $R.Forms[0] です。パスワード = "MyPassword" Invoke-RestMethod https://website.com/service.aspx -Body $R.Forms[0]

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

-Certificate

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

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

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

-CertificateThumbprint

要求を送信するアクセス許可を持つユーザーアカウントのデジタル公開キー証明書 (X509) を指定します。証明書の拇印を入力します。

証明書は、クライアント証明書ベースの認証で使用されます。これらはローカルユーザーアカウントにのみマップできます。ドメインアカウントでは機能しません。

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

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

-ContentType

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

このパラメータを省略し、リクエストメソッドが POST の場合、 Invoke-RestMethod はコンテンツタイプを "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

接続が失敗するまでに、Windows 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-RestMethod は結果をパイプラインに返します。結果をファイルおよびパイプラインに送信するには、 -Passthru パラメーターを使用します。

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

-PassThru

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

型:	SwitchParameter
配置:	Named
規定値:	No output
必須:	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-RestMethod は Web 要求セッションオブジェクトを作成し、それを Windows PowerShell セッション内の指定された名前の変数に割り当てます。この変数は、コマンドが完了するとすぐにセッションで使用できます。

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

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

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

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

-TimeoutSec

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

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

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

-TransferEncoding

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

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

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

-Uri

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

このパラメーターは必須です。パラメーター名 (-Uri) は省略可能です。

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

-UseBasicParsing

コマンドレットが基本的な解析を使用することを示します。このコマンドレットは、String オブジェクト内の生の HTML を返します。

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

-UseDefaultCredentials

現在のユーザーの資格情報を使用して Web 要求を送信します。

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

-UserAgent

Web 要求のユーザーエージェント文字列を指定します。

デフォルトのユーザーエージェントは、「Mozilla/5.0 (Windows NT;Windows NT 6.1;en-US) WindowsPowerShell/3.0」は、オペレーティングシステムとプラットフォームごとに若干の違いがあります。

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

たとえば、次のコマンドでは、Internet のユーザーエージェント文字列を使用します

Invoke-WebRequest -Uri https://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)

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

-WebSession

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

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

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