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 要求を送信します。

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

Note

REST エンドポイントが複数のオブジェクトを返すと、オブジェクトは配列として受け取ります。 Invoke-RestMethodから別のコマンドに出力をパイプすると、1 つの[Object[]] オブジェクトとして送信されます。その配列の内容は、パイプラインの次のコマンドには列挙されません。

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

Note

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

例

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

Invoke-RestMethod -Uri https://devblogs.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: 複数のヘッダーを渡す

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

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

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

例 3: フォームデータの送信

本文がフォームの場合、または別の 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.Forms[0]

例 4: パイプラインで返された項目を列挙する

GitHub は複数のオブジェクトを配列として返します。出力を別のコマンドにパイプすると、1 つの [Object[]]オブジェクトとして送信されます。

パイプラインにオブジェクトを列挙するには、結果をパイプ処理して Write-Output するか、コマンドレットをかっこで囲みます。次の例では、GitHub によって返されるオブジェクトの数をカウントします。次に、パイプラインに列挙されたオブジェクトの数をカウントします。

$uri = 'https://api.github.com/repos/microsoftdocs/powershell-docs/issues'
$x = 0
Invoke-RestMethod -Uri $uri | ForEach-Object { $x++ }
$x
1

$x = 0
(Invoke-RestMethod -Uri $uri) | ForEach-Object { $x++ }
$x
30

$x = 0
Invoke-RestMethod -Uri $uri | Write-Output | ForEach-Object { $x++ }
$x
30

パラメーター

-Body

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

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

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

警告

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

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

-Certificate

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

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

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

-CertificateThumbprint

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

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

証明書の拇印を表示するには、 Get-Item または Get-ChildItem コマンドを使用して、 Cert:\CurrentUser\Myで証明書を検索します。

型:	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 などのユーザー名を入力するか、Get-Credential コマンドレットによって生成されたPSCredential オブジェクトを入力します。

資格情報は PSCredential オブジェクトに格納され、パスワードは SecureString として格納されます。

Note

SecureString データ保護の詳細については、「 SecureString のセキュリティ保護方法」を参照してください。

型:	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 要求に使用するメソッドを指定します。このパラメーターの有効値は、次のとおりです。

Default
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace

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

-OutFile

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

既定では、 Invoke-RestMethod は結果をパイプラインに返します。

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

-PassThru

このパラメーターは、コマンドで OutFile パラメーターが使用されている場合にのみ有効です。目的は、結果をファイルとパイプラインに書き込むという目的です。

Note

PassThru パラメーターを使用すると、出力はパイプラインに書き込まれますが、ファイルは空です。詳細については、 PowerShell の問題 #15409 を参照してください。

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

-Proxy

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

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

-ProxyCredential

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

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

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

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

-ProxyUseDefaultCredentials

現在のユーザーの資格情報を使用して、 Proxy パラメーターで指定されたプロキシサーバーにアクセスします。

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

-SessionVariable

Web 要求セッションを含む変数を作成します。ドル記号 ($) 記号を使用せずに変数名を入力します。

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

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

後続の Web 要求で Web 要求セッションを使用するには、 WebSession パラメーターの値にセッション変数を指定します。 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 応答ヘッダーの値を指定します。このパラメーターの有効値は、次のとおりです。

Chunked
Compress
Deflate
GZip
Identity

型:	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 クラスのプロパティを使用します。

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

-WebSession

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

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

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

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

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

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

入力

Object

Web 要求の本文をこのコマンドレットにパイプできます。

出力

Int64

要求から整数が返されると、このコマンドレットはその整数を返します。

String

要求が文字列を返すと、このコマンドレットはその文字列を返します。

XmlDocument

要求が有効な XML を返すと、このコマンドレットは xmldocument として返。

PSObject

要求が JSON 文字列を返すと、このコマンドレットはデータを表す PSObject を返します。

メモ

Windows PowerShell には、 Invoke-RestMethodの次のエイリアスが含まれています。

irm

次の方法で共有

Invoke-RestMethod

構文

説明

例

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

例 2

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

例 3: フォームデータの送信

例 4: パイプラインで返された項目を列挙する

パラメーター

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

入力

出力

メモ

その他のリソース

次の方法で共有

Invoke-RestMethod

構文

説明

例

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

例 2

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

例 3: フォーム データの送信

例 4: パイプラインで返された項目を列挙する

パラメーター

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

入力

出力

メモ

関連リンク

その他のリソース

例 3: フォームデータの送信