Invoke-RestMethod
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
既定では、Web ページ内のスクリプト コードは、プロパティを設定 ParsedHtml
するためにページが解析されるときに実行される場合があります。 これを抑制するには、 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 など) の場合、本文は標準的な "名前=値" の形式で要求本文の値として設定されます。
警告
本文のサイズが既知であり、HTTP ヘッダーでwith -1-byte payload
Content-Length
送信されている場合でも、POST 本文の詳細出力は終了します。
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) を指定します。 証明書の拇印を入力します。
証明書は、クライアント証明書ベースの認証で使用されます。 証明書はローカル ユーザー アカウントにのみマップでき、メインアカウントにはマップできません。
証明書の拇印を表示するには、またはGet-ChildItem
コマンドをGet-Item
使用して証明書Cert:\CurrentUser\My
を検索します。
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 や Doメイン01\User01 などのユーザー名を入力するか、コマンドレットによって生成された PSCredential オブジェクトをGet-Credential
入力します。
資格情報は PSCredential オブジェクトに格納され、パスワードは SecureString として格納されます。
Note
SecureString データ保護の詳細については、「SecureString のセキュリティ保護方法」を参照してください。
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
Delete
Get
Head
Merge
Options
Patch
Post
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
結果をパイプラインに返します。
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" や "Doメイン01\User01" などのユーザー名を入力するか、PSCredential オブジェクト (コマンドレットによって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 パラメーターで指定されたプロキシ サーバーにアクセスします。
このパラメーターは、Proxy パラメーターがコマンドでも使用されている場合にのみ有効です。 同じコマンドで ProxyCredential パラメーターと ProxyUseDefaultCredentials パラメーターを使用することはできません。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SessionVariable
Web 要求セッションを含む変数を作成します。 ドル記号 ($
) 記号を使用せずに変数名を入力します。
セッション変数を指定する場合は、 Invoke-RestMethod
Web 要求セッション オブジェクトを作成し、PowerShell セッションで指定した名前の変数に割り当てます。 コマンドが完了すると、すぐに変数をセッションで使用できます。
リモート セッションとは異なり、Web 要求セッションは永続的な接続ではありません。 これは、Cookie、資格情報、最大リダイレクト値、ユーザー エージェント文字列など、接続と要求に関する情報を含むオブジェクトです。 Web 要求セッションを使用して、Web 要求の間で状態とデータを共有することができます。
後続の Web 要求で Web 要求セッションを使用するには、WebSession パラメーターの値にセッション変数を指定します。 PowerShell では、新しい接続を確立するときに、Web 要求セッション オブジェクトのデータが使用されます。 Web 要求セッションの値をオーバーライドするには、UserAgent や Credential などのコマンドレット パラメーターを使用します。 パラメーターの値は、Web 要求セッションの値よりも優先されます。
同じコマンドで SessionVariable パラメーターと WebSession パラメーターを使用することはできません。
Type: | String |
Aliases: | SV |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-TimeoutSec
タイムアウトするまでの要求の保留期間を指定します。値を秒単位で入力します。 既定値は 0 で、無制限のタイムアウトを意味しています。
Doメイン Name System (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 応答ヘッダーの値を指定します。 このパラメーターの有効値は、次のとおりです。
Chunked
Compress
Deflate
GZip
Identity
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 エクスプローラー、Opera、Safari などの PSUserAgent クラスのプロパティを使用します。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-WebSession
Web 要求セッションを指定します。 ドル記号 ($
) を含む変数名を入力します。
Web 要求セッションの値をオーバーライドするには、UserAgent や Credential などのコマンドレット パラメーターを使用します。 パラメーターの値は、Web 要求セッションの値よりも優先されます。
リモート セッションとは異なり、Web 要求セッションは永続的な接続ではありません。 Web 要求セッションは、Cookie、資格情報、リダイレクトの最大値、ユーザー エージェント文字列などの、接続と要求に関する情報を含むオブジェクトです。 Web 要求セッションを使用して、Web 要求の間で状態とデータを共有することができます。
Web 要求セッションを作成するには、コマンドの SessionVariable パラメーターの値に変数名 (ドル記号なし) をInvoke-RestMethod
入力します。 Invoke-RestMethod
はセッションを作成し、変数に保存します。 後続のコマンドでは、変数を WebSession パラメーターの値として使用します。
同じコマンドで SessionVariable パラメーターと WebSession パラメーターを使用することはできません。
Type: | WebRequestSession |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
入力
Web 要求の本文をこのコマンドレットにパイプできます。
出力
要求から整数が返されると、このコマンドレットはその整数を返します。
要求が文字列を返すと、このコマンドレットはその文字列を返します。
要求が有効な XML を返すと、このコマンドレットは XMLDocument として 返します。
PSObject
要求が JSON 文字列を返すと、このコマンドレットはデータを 表す PSObject を 返します。
メモ
Windows PowerShell には、次のエイリアスが Invoke-RestMethod
含まれています。
irm
関連リンク
PowerShell
フィードバック
https://aka.ms/ContentUserFeedback」を参照してください。
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「フィードバックの送信と表示