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

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

手記

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

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

手記

既定では、ページを解析して 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 など) の場合、本文は標準の name=value 形式で要求本文の値として設定されます。

警告

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

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

-Certificate

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

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

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

-CertificateThumbprint

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

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

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

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

-ContentType

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

ContentType の値にエンコード形式 (charset) が含まれている場合、コマンドレットはその形式を使用して Web 要求の本文をエンコードします。 ContentType でエンコード形式が指定されていない場合は、代わりに既定のエンコード形式が使用されます。エンコード形式の ContentType の例として、text/plain; charset=iso-8859-5 アルファベットを指定するがあります。

パラメーターを省略すると、使用する HTTP メソッドに基づいてコンテンツタイプが異なる場合があります。

POST メソッドの場合、コンテンツタイプは application/x-www-form-urlencoded
PUT メソッドの場合、コンテンツタイプは application/json
その他のメソッドの場合、要求でコンテンツタイプが指定されていません

InFile パラメーターを使用してファイルをアップロードする場合は、コンテンツタイプを設定する必要があります。通常、型は application/octet-streamする必要があります。ただし、エンドポイントの要件に基づいてコンテンツタイプを設定する必要があります。

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

-Credential

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

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

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

手記

SecureString データ保護 の詳細については、「SecureString はどの程度安全ですか？」を参照してください。.

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

-DisableKeepAlive

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

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

-Headers

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

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

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

-InFile

Web 要求本文の内容をファイルから取得します。パスとファイル名を入力します。パスを省略した場合、既定値は現在の場所です。

また、要求のコンテンツタイプを設定する必要があります。たとえば、ファイルをアップロードするには、コンテンツタイプを設定する必要があります。通常、型は application/octet-streamする必要があります。ただし、エンドポイントの要件に基づいてコンテンツタイプを設定する必要があります。

型:	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 パラメーターがコマンドでも使用されている場合にのみ有効です。目的は、結果をファイルとパイプラインに書き込むという目的です。

手記

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

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

-Proxy

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

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

-ProxyCredential

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

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

このパラメーターは、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 要求セッションを使用するには、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
規定値:	0
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-TransferEncoding

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

Chunked
Compress
Deflate
GZip
Identity

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

-Uri

Web 要求の送信先となるインターネットリソースの URI (Uniform Resource Identifier) を指定します。このパラメーターは、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 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0 に似ています。

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

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

-WebSession

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

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

Web 要求セッションを作成するには、コマンドの Invoke-RestMethod パラメーターの値に、ドル記号なしで変数名を入力します。 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: フォームデータの送信