Invoke-RestMethod

構文

Invoke-RestMethod
      [-FollowRelLink]
      [-MaximumFollowRelLink <Int32>]
      [-ResponseHeadersVariable <String>]
      [-StatusCodeVariable <String>]
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-HttpVersion <Version>]
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-ConnectionTimeoutSeconds <Int32>]
      [-OperationTimeoutSeconds <Int32>]
      [-Headers <IDictionary>]
      [-SkipHeaderValidation]
      [-AllowInsecureRedirect]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-PreserveAuthorizationOnRedirect]
      [-RetryIntervalSec <Int32>]
      [-Method <WebRequestMethod>]
      [-PreserveHttpMethodOnRedirect]
      [-UnixSocket <UnixDomainSocketEndPoint>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [<CommonParameters>]

Invoke-RestMethod
      [-FollowRelLink]
      [-MaximumFollowRelLink <Int32>]
      [-ResponseHeadersVariable <String>]
      [-StatusCodeVariable <String>]
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-HttpVersion <Version>]
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-ConnectionTimeoutSeconds <Int32>]
      [-OperationTimeoutSeconds <Int32>]
      [-Headers <IDictionary>]
      [-SkipHeaderValidation]
      [-AllowInsecureRedirect]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-PreserveAuthorizationOnRedirect]
      [-RetryIntervalSec <Int32>]
      [-Method <WebRequestMethod>]
      [-PreserveHttpMethodOnRedirect]
      [-UnixSocket <UnixDomainSocketEndPoint>]
      [-NoProxy]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [<CommonParameters>]

Invoke-RestMethod
      [-FollowRelLink]
      [-MaximumFollowRelLink <Int32>]
      [-ResponseHeadersVariable <String>]
      [-StatusCodeVariable <String>]
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-HttpVersion <Version>]
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-ConnectionTimeoutSeconds <Int32>]
      [-OperationTimeoutSeconds <Int32>]
      [-Headers <IDictionary>]
      [-SkipHeaderValidation]
      [-AllowInsecureRedirect]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-PreserveAuthorizationOnRedirect]
      [-RetryIntervalSec <Int32>]
      -CustomMethod <String>
      [-PreserveHttpMethodOnRedirect]
      [-UnixSocket <UnixDomainSocketEndPoint>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [<CommonParameters>]

Invoke-RestMethod
      [-FollowRelLink]
      [-MaximumFollowRelLink <Int32>]
      [-ResponseHeadersVariable <String>]
      [-StatusCodeVariable <String>]
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-HttpVersion <Version>]
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-ConnectionTimeoutSeconds <Int32>]
      [-OperationTimeoutSeconds <Int32>]
      [-Headers <IDictionary>]
      [-SkipHeaderValidation]
      [-AllowInsecureRedirect]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-PreserveAuthorizationOnRedirect]
      [-RetryIntervalSec <Int32>]
      -CustomMethod <String>
      [-PreserveHttpMethodOnRedirect]
      [-UnixSocket <UnixDomainSocketEndPoint>]
      [-NoProxy]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [<CommonParameters>]

説明

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

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

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

PowerShell 7.0 以降では、 Invoke-RestMethod は環境変数によって定義されたプロキシ構成をサポートしています。 この記事の「 Notes 」セクションを参照してください。

PowerShell 7.4 以降では、要求の文字エンコードは既定で ASCII ではなく UTF-8 に設定されています。 別のエンコードが必要な場合は、Content-Type ヘッダーにcharset属性を設定する必要があります。

例

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

この例では、 Invoke-RestMethod コマンドレットを使用して、PowerShell ブログ RSS フィードから情報を取得します。 このコマンドは、 Format-Table コマンドレットを使用して、テーブル内の各ブログの Title プロパティと pubDate プロパティの値を表示します。

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

例 2: POST 要求を実行する

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

$Cred = Get-Credential
$Url = "https://server.contoso.com:8089/services/search/jobs/export"
$Body = @{
    search = "search index=_internal | reverse | table index,host,source,sourcetype,_raw"
    output_mode = "csv"
    earliest_time = "-2d@d"
    latest_time = "-1d@d"
}
Invoke-RestMethod -Method 'Post' -Uri $url -Credential $Cred -Body $body -OutFile output.csv

資格情報の入力を求められた後、 $Cred に格納され、アクセスする URL が $Urlで定義されます。

$Body変数は検索条件を記述し、CSV を出力モードとして指定し、2 日前に開始して 1 日前に終了する返されるデータの期間を指定します。 body 変数は、 Invoke-RestMethod が通信している特定の REST API に適用されるパラメーターの値を指定します。

Invoke-RestMethod コマンドは、結果の CSV 出力ファイルのパスとファイル名を指定して、すべての変数を配置して実行されます。

例 3: 関係リンクに従う

一部の REST API では、 RFC5988ごとの Relation Links による改ページがサポートされています。 ヘッダーを解析して次のページの URL を取得する代わりに、コマンドレットでこれを行うことができます。 この例では、PowerShell GitHub リポジトリから最初の 2 ページの問題を返します。

$url = 'https://api.github.com/repos/powershell/powershell/issues'
Invoke-RestMethod $url -FollowRelLink -MaximumFollowRelLink 2

例 4: 簡略化されたマルチパート/フォーム データ送信

一部の API では、ファイルと混合コンテンツをアップロードするために multipart/form-data 送信が必要です。 この例では、ユーザーのプロファイルを更新する方法を示します。

$Uri = 'https://api.contoso.com/v2/profile'
$Form = @{
    firstName  = 'John'
    lastName   = 'Doe'
    email      = 'john.doe@contoso.com'
    avatar     = Get-Item -Path 'c:\Pictures\jdoe.png'
    birthday   = '1980-10-15'
    hobbies    = 'Hiking','Fishing','Jogging'
}
$Result = Invoke-RestMethod -Uri $Uri -Method Post -Form $Form

プロファイル フォームには、 firstName、 lastName、 email、 avatar、 birthday、 hobbiesの各フィールドが必要です。 API では、ユーザー プロファイルの画像が avatar フィールドに提供されることを想定しています。 API は、同じ形式で送信される複数の hobbies エントリも受け入れます。

$Form HashTable を作成するときに、キー名がフォーム フィールド名として使用されます。 既定では、HashTable の値は文字列に変換されます。 System.IO.FileInfo値が存在する場合は、ファイルの内容が送信されます。 配列やリストなどのコレクションが存在する場合、フォーム フィールドは複数回送信されます。

avatar キーでGet-Itemを使用すると、FileInfo オブジェクトが値として設定されます。 その結果、 jdoe.png の画像データが送信されます。

hobbies キーにリストを指定すると、hobbies フィールドがリスト アイテムごとに 1 回送信に表示されます。

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

API では、多くの場合、認証または検証に渡されたヘッダーが必要です。 この例では、 hash-table から REST API に複数のヘッダーを渡す方法を示します。

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

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

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

例 7: ヘッダー検証のスキップ

既定では、 Invoke-RestMethod コマンドレットは、標準で定義された値形式を持つ既知のヘッダーの値を検証します。 次の例は、この検証でエラーが発生する方法と、 SkipHeaderValidation パラメーターを使用して、無効に書式設定された値を許容するエンドポイントの値の検証を回避する方法を示しています。

$Uri = 'https://httpbin.org/headers'
$InvalidHeaders = @{
    'If-Match' = '12345'
}

Invoke-RestMethod -Uri $Uri -Headers $InvalidHeaders

Invoke-RestMethod -Uri $Uri -Headers $InvalidHeaders -SkipHeaderValidation |
    Format-List

Invoke-RestMethod: The format of value '12345' is invalid.

headers : @{Host=httpbin.org; If-Match=12345; User-Agent=Mozilla/5.0 (Windows NT 10.0; Microsoft Windows
          10.0.19044; en-US) PowerShell/7.2.5;  X-Amzn-Trace-Id=Root=1-62f150a6-27754fd4226f31b43a3d2874}

httpbin.org は、トラブルシューティングのために Web 要求と応答に関する情報を返すサービスです。 $Uri変数はサービスの/headers エンドポイントに割り当てられ、要求のヘッダーが応答の内容として返されます。

If-Match要求ヘッダーは、RFC-7232 セクション 3.1 で定義されておりそのヘッダーの値を周囲の引用符で定義する必要があります。 $InvalidHeaders変数には、"12345"ではなく12345として定義されているため、If-Matchの値が無効なハッシュ テーブルが割り当てられます。

ヘッダーが無効な Invoke-RestMethod を呼び出すと、書式設定された値が無効であることを示すエラーが返されます。 要求はエンドポイントに送信されません。

SkipHeaderValidation パラメーターを使用してInvoke-RestMethodを呼び出すと、検証エラーが無視され、エンドポイントに要求が送信されます。 エンドポイントは準拠していないヘッダー値を許容するため、コマンドレットはエラーなしで応答オブジェクトを返します。

例 8: HTTP 2.0 を使用して要求を送信する

この例では、HTTP 2.0 プロトコルを使用して GitHub の問題を照会します。

$uri = 'https://api.github.com/repos/microsoftdocs/powershell-docs/issues'
Invoke-RestMethod -Uri $uri -HttpVersion 2.0 -SkipCertificateCheck

例 9: Unix ソケット アプリケーションに要求を送信する

Docker などの一部のアプリケーションでは、通信用の Unix ソケットが公開されています。 この例では、Docker API を使用して Docker イメージの一覧を照会します。 このコマンドレットは、Unix ソケットを使用して Docker デーモンに接続します。

Invoke-RestMethod -Uri "http://localhost/v1.40/images/json/" -UnixSocket "/var/run/docker.sock"

パラメーター

-AllowInsecureRedirect

-AllowUnencryptedAuthentication

-Authentication

-Body

-Certificate

-CertificateThumbprint

-ConnectionTimeoutSeconds

-ContentType

-Credential

-CustomMethod

-DisableKeepAlive

-FollowRelLink

-Form

-Headers

-HttpVersion

-InFile

-MaximumFollowRelLink

-MaximumRedirection

-MaximumRetryCount

-Method

-NoProxy

-OperationTimeoutSeconds

-OutFile

-PassThru

-PreserveAuthorizationOnRedirect

-PreserveHttpMethodOnRedirect

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-ResponseHeadersVariable

-Resume

-RetryIntervalSec

-SessionVariable

-SkipCertificateCheck

-SkipHeaderValidation

-SkipHttpErrorCheck

-SslProtocol

-StatusCodeVariable

-Token

-TransferEncoding

-UnixSocket

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

入力

Object

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

出力

Int64

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

String

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

XmlDocument

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

PSObject

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

メモ

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

• すべてのプラットフォーム:
  • irm

一部の機能は、すべてのプラットフォームで利用できない場合があります。

.NET Core 3.1 の変更により、PowerShell 7.0 以降では HttpClient.DefaultProxy プロパティを使用してプロキシ構成を決定します。

このプロパティの値は、プラットフォームによって異なる規則です。

• Windows の場合: 環境変数からプロキシ構成を読み取るか、それらが定義されていない場合はユーザーのプロキシ設定から読み取ります。
• macOS の場合: 環境変数からプロキシ構成を読み取るか、それらが定義されていない場合はシステムのプロキシ設定から読み取ります。
• Linux の場合: 環境変数からプロキシ構成を読み取ります。または、それらが定義されていない場合、このプロパティはすべてのアドレスをバイパスする未構成のインスタンスを初期化します。

Windows と Unix ベースのプラットフォームで DefaultProxy の初期化に使用される環境変数は、次のとおりです。

• HTTP_PROXY: HTTP 要求で使用されるプロキシ サーバーのホスト名または IP アドレス。
• HTTPS_PROXY: HTTPS 要求で使用されるプロキシ サーバーのホスト名または IP アドレス。
• ALL_PROXY: HTTP_PROXY または HTTPS_PROXY が定義されていない場合に、HTTP および HTTPS 要求で使用されるプロキシ サーバーのホスト名または IP アドレス。
• NO_PROXY: プロキシから除外するホスト名のコンマ区切りの一覧。

PowerShell 7.4 では、Brotli 圧縮アルゴリズムのサポートが追加されました。

関連リンク

• ConvertTo-Json
• ConvertFrom-Json
• Invoke-WebRequest