Invoke-RestMethod

リファレンス

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

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

構文

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 、高度に構造化されたデータを返す Representational State Transfer (REST) Web サービスに HTTP 要求と HTTPS 要求を送信します。

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

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

注意

既定では、Web ページ内のスクリプトコードは、プロパティを設定 ParsedHtml するためにページが解析されるときに実行される場合があります。これを抑制するには、 -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

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

$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 など) の場合、本文は標準的な "名前=値" の形式で要求本文の値として設定されます。

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

本文がフォームの場合、または別Invoke-WebRequestの呼び出しの出力である場合は、要求の内容をフォームフィールドに設定Windows 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.Forms[0]

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

-Certificate

セキュリティで保護された Web 要求に使用するクライアント証明書を指定します。証明書が格納されている変数を入力するか、証明書を取得するコマンドまたは式を入力します。

証明書を見つけるには、証明書 (Cert:) ドライブでコマンドレットを使用Get-PfxCertificateまたは使用Get-ChildItemします。証明書が無効な場合、または証明書に十分な権限がない場合、コマンドは失敗します。

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

-CertificateThumbprint

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

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

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

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

-ContentType

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

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

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

-Credential

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

「User01」や「Domain01\User01」のようなユーザー名を入力するか、コマンドレットで生成されるような Get-Credential オブジェクトを入力します。

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

-DisableKeepAlive

HTTP ヘッダーの KeepAlive 値を False に設定します。既定では、KeepAlive は True です。 KeepAlive は、後続の要求を容易にするために、サーバーへの永続的な接続を確立します。

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

-Headers

Web 要求のヘッダーを指定します。ハッシュテーブルまたは辞書を入力します。

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

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

-InFile

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

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

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

-MaximumRedirection

接続を失敗させる前に Windows PowerShell が代替 Uniform Resource Identifier (URI) に接続をリダイレクトする回数を指定します。既定値は 5 です。値 0 (ゼロ) を指定した場合、リダイレクトはまったく行われません。

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

-Method

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

Default
削除
取得
Head
マージする
オプション
修正プログラム
投稿
Put
Trace

Type:	WebRequestMethod
Accepted values:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Position:	Named
Default value:	Default
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-OutFile

指定した出力ファイルに応答本文を保存します。パスとファイル名を入力します。パスを省略した場合、既定値は現在のディレクトリです。

既定では、 Invoke-RestMethod 結果をパイプラインに返します。結果をファイルとパイプラインに送信するには、パラメーターを -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:	No output
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」のようなユーザー名を入力するか、コマンドレットで生成されるような 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:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SessionVariable

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

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

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

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

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

Type:	String
Aliases:	SV
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-TimeoutSec

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

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

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

-TransferEncoding

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

チャンク
圧縮
Deflate
GZip
ID

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

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

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

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

-UseBasicParsing

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

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

-UseDefaultCredentials

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

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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 クラスのプロパティを使用します。

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

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

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

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

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