次の方法で共有


Invoke-RestMethod

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

構文

Default (既定)

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 データでは許可されません。

Warnung

既定では、 Invoke-RestMethod は Web ページのコンテンツを解析します。 Web ページのスクリプト コードは、ページの解析時に実行される場合があります。 スクリプト コードの実行を回避するには、 -UseBasicParsing スイッチを使用します。

このコマンドレットは、Windows PowerShell 3.0 で導入されています。 このコマンドは、 irm エイリアスを使用して実行できます。

例 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 形式で要求本文の値として設定されます。

Warnung

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

パラメーターのプロパティ

型:Object
規定値:None
ワイルドカードのサポート:False
DontShow:False

パラメーター セット

(All)
配置:Named
必須:False
パイプラインからの値:True
プロパティ名別のパイプラインからの値:False
残りの引数からの値:False

-Certificate

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

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

パラメーターのプロパティ

型:X509Certificate
規定値:None
ワイルドカードのサポート:False
DontShow:False

パラメーター セット

(All)
配置:Named
必須:False
パイプラインからの値:False
プロパティ名別のパイプラインからの値:False
残りの引数からの値:False

-CertificateThumbprint

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

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

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

パラメーターのプロパティ

型:String
規定値:None
ワイルドカードのサポート:False
DontShow:False

パラメーター セット

(All)
配置:Named
必須:False
パイプラインからの値: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
規定値:None
ワイルドカードのサポート:False
DontShow:False

パラメーター セット

(All)
配置:Named
必須:False
パイプラインからの値:False
プロパティ名別のパイプラインからの値:False
残りの引数からの値:False

-Credential

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

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

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

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

パラメーターのプロパティ

型:PSCredential
規定値:Current user
ワイルドカードのサポート:False
DontShow:False

パラメーター セット

(All)
配置:Named
必須:False
パイプラインからの値:False
プロパティ名別のパイプラインからの値:False
残りの引数からの値:False

-DisableKeepAlive

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

パラメーターのプロパティ

型:SwitchParameter
規定値:False
ワイルドカードのサポート:False
DontShow:False

パラメーター セット

(All)
配置:Named
必須:False
パイプラインからの値:False
プロパティ名別のパイプラインからの値:False
残りの引数からの値:False

-Headers

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

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

パラメーターのプロパティ

型:IDictionary
規定値:None
ワイルドカードのサポート:False
DontShow:False

パラメーター セット

(All)
配置:Named
必須:False
パイプラインからの値:False
プロパティ名別のパイプラインからの値:False
残りの引数からの値:False

-InFile

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

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

パラメーターのプロパティ

型:String
規定値:None
ワイルドカードのサポート:False
DontShow:False

パラメーター セット

(All)
配置:Named
必須:False
パイプラインからの値:False
プロパティ名別のパイプラインからの値:False
残りの引数からの値:False

-MaximumRedirection

接続が失敗するまでに、Windows PowerShell が代替 Uniform Resource Identifier (URI) に接続をリダイレクトする回数を決定します。 既定値は 5 です。 値が 0 (ゼロ) の場合、すべてのリダイレクトが禁止されます。

パラメーターのプロパティ

型:Int32
規定値:5
ワイルドカードのサポート:False
DontShow:False

パラメーター セット

(All)
配置:Named
必須:False
パイプラインからの値:False
プロパティ名別のパイプラインからの値:False
残りの引数からの値:False

-Method

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

  • Default
  • Delete
  • Get
  • Head
  • Merge
  • Options
  • Patch
  • Post
  • Put
  • Trace

パラメーターのプロパティ

型:WebRequestMethod
規定値:Default
指定可能な値:Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
ワイルドカードのサポート:False
DontShow:False

パラメーター セット

(All)
配置:Named
必須:False
パイプラインからの値:False
プロパティ名別のパイプラインからの値:False
残りの引数からの値:False

-OutFile

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

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

パラメーターのプロパティ

型:String
規定値:None
ワイルドカードのサポート:False
DontShow:False

パラメーター セット

(All)
配置:Named
必須:False
パイプラインからの値:False
プロパティ名別のパイプラインからの値:False
残りの引数からの値:False

-PassThru

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

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

パラメーターのプロパティ

型:SwitchParameter
規定値:No output
ワイルドカードのサポート:False
DontShow:False

パラメーター セット

(All)
配置:Named
必須:False
パイプラインからの値:False
プロパティ名別のパイプラインからの値:False
残りの引数からの値:False

-Proxy

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

パラメーターのプロパティ

型:Uri
規定値:None
ワイルドカードのサポート:False
DontShow:False

パラメーター セット

(All)
配置:Named
必須:False
パイプラインからの値:False
プロパティ名別のパイプラインからの値:False
残りの引数からの値:False

-ProxyCredential

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

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

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

パラメーターのプロパティ

型:PSCredential
規定値:Current user
ワイルドカードのサポート:False
DontShow:False

パラメーター セット

(All)
配置:Named
必須:False
パイプラインからの値:False
プロパティ名別のパイプラインからの値:False
残りの引数からの値:False

-ProxyUseDefaultCredentials

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

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

パラメーターのプロパティ

型:SwitchParameter
規定値:None
ワイルドカードのサポート:False
DontShow:False

パラメーター セット

(All)
配置:Named
必須:False
パイプラインからの値:False
プロパティ名別のパイプラインからの値:False
残りの引数からの値:False

-SessionVariable

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

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

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

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

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

パラメーターのプロパティ

型:String
規定値:None
ワイルドカードのサポート:False
DontShow:False
Aliases:SV

パラメーター セット

(All)
配置:Named
必須:False
パイプラインからの値:False
プロパティ名別のパイプラインからの値:False
残りの引数からの値:False

-TimeoutSec

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

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

パラメーターのプロパティ

型:Int32
規定値:0
ワイルドカードのサポート:False
DontShow:False

パラメーター セット

(All)
配置:Named
必須:False
パイプラインからの値:False
プロパティ名別のパイプラインからの値:False
残りの引数からの値:False

-TransferEncoding

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

  • Chunked
  • Compress
  • Deflate
  • GZip
  • Identity

パラメーターのプロパティ

型:String
規定値:None
指定可能な値:chunked, compress, deflate, gzip, identity
ワイルドカードのサポート:False
DontShow:False

パラメーター セット

(All)
配置:Named
必須:False
パイプラインからの値:False
プロパティ名別のパイプラインからの値:False
残りの引数からの値:False

-Uri

Web 要求の送信先となるインターネット リソースの URI (Uniform Resource Identifier) を指定します。 このパラメーターは、HTTP、HTTPS、FTP、および FILE の値をサポートします。

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

パラメーターのプロパティ

型:Uri
規定値:None
ワイルドカードのサポート:False
DontShow:False

パラメーター セット

(All)
配置:0
必須:True
パイプラインからの値:False
プロパティ名別のパイプラインからの値:False
残りの引数からの値:False

-UseBasicParsing

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

パラメーターのプロパティ

型:SwitchParameter
規定値:None
ワイルドカードのサポート:False
DontShow:False

パラメーター セット

(All)
配置:Named
必須:False
パイプラインからの値:False
プロパティ名別のパイプラインからの値:False
残りの引数からの値:False

-UseDefaultCredentials

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

パラメーターのプロパティ

型:SwitchParameter
規定値:None
ワイルドカードのサポート:False
DontShow:False

パラメーター セット

(All)
配置:Named
必須:False
パイプラインからの値: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
規定値:None
ワイルドカードのサポート:False
DontShow:False

パラメーター セット

(All)
配置:Named
必須:False
パイプラインからの値:False
プロパティ名別のパイプラインからの値:False
残りの引数からの値:False

-WebSession

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

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

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

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

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

パラメーターのプロパティ

型:WebRequestSession
規定値:None
ワイルドカードのサポート:False
DontShow:False

パラメーター セット

(All)
配置:Named
必須:False
パイプラインからの値:False
プロパティ名別のパイプラインからの値:False
残りの引数からの値:False

CommonParameters

このコマンドレットでは、一般的なパラメーター -Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction、-WarningVariable の各パラメーターがサポートされています。 詳細については、about_CommonParametersを参照してください。

入力

Object

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

出力

Int64

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

String

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

XmlDocument

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

PSObject

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

メモ

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

  • irm

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