PowerShellで新しいREST APIを学ぶ
スクリプトを拡張するためにREST APIを使用することは、実装するための便利な機能です。新しい機能にアクセスでき、より高度な新しいスクリプトを作成する可能性が広がります。
しかし、多くの人がスクリプトでREST APIを使用し始めるときの体験は、非常に不器用で不自然に感じることです。この投稿では、以下について議論します：
- REST APIとは何か
- 最も一般的な形式の文書を読む方法
- PowerShellでREST APIを使用する方法
- 簡単でより良い体験にするためのいくつかのヒントとコツ
RESTとは何ですか？
REST、またはRESTful APIとは、HTTPリクエストを使用して異なるサービスのデータを取得、追加、削除、または操作するAPIです。
データに対して何をしたいかは、通常、使用するHTTPメソッドによって決まります。以下は、REST APIにおけるHTTPメソッドの要約リストとその用途です:
- GET---読む
- POST---作成
- パッチ---部分的な更新/修正
- PUT---更新/置き換え
- 削除---取り除く
REST APIから返されるデータは通常、JSON形式で返されます。
さあ、最初のAPIコールを始めましょう！
ドキュメントを読む
異なるREST APIのドキュメントを読むことと解釈することを学ぶことは、それらを使用するために不可欠です。幸運なことに、一つのスタイルのドキュメントを読む方法を知っていれば、他のドキュメントを読む方法も迅速に学ぶことができます。
この記事では、現実の世界でよく見かける人気のSwaggerフレームワークを使用しているpetstore.swagger.ioを使用します。
前の画像はREST APIエンドポイントに関する最も重要な情報を示しています:
- HTTPメソッド---GET/POST/DELETEなど
- REST APIエンドポイントへの相対URL（基本URLは通常、ドキュメントページの上部に表示されます）
- 簡単な説明
詳細に入る
ドキュメントの最初のページは素晴らしく、通常、その情報を使用してHTTP GETメソッドを必要とするほとんどの呼び出しを実行できます。しかし、POSTやSETのようなメソッドは、通常、より多くの情報を得るために行をクリックして展開する必要があります。
行の一つをクリックすると、次のような情報が表示されます:
ここでは、新しいペットオブジェクトを作成できるRESTエンドポイントを示しています。それは、POSTのボディに提供されたJSONの外観と、受け入れるコンテンツのタイプを指定しています。他のRESTエンドポイントは、その異なるパラメータ、必要なデータ型などを指定しています。
それがドキュメントを読むための基本です。これで明確になったので、PowerShellを使ってREST APIを利用し始める時間です。
最初のデータを取得する
PowerShellでREST APIを使用するのは通常非常に簡単で、組み込みコマンドレットを使用しているので追加のモジュールは必要ありません。/pet/{petId}エンドポイントでGETメソッドを使用してデータを取得します。
ドキュメントの /pet/{petId} エンドポイントを展開すると、{petId} は実際には整数を受け取るパラメーターであることがわかります。
それにより、ID 1のペットオブジェクトを取得するためのURLは次のようになります： https://petstore.swagger.io/v2/pet/1
SWAGGER REST APIのドキュメントは通常、ページの最上部にベースURLを表示します。
さあ、PowerShellを始めましょう。ターミナルウィンドウを開いて、次のことを入力してください。
PS51 > Invoke-RestMethod -Method GET -ContentType "application/json" -Uri "https://petstore.swagger.io/v2/pet/1"
id : 1
category : @{id=0; name=string}
name : doggie
photoUrls : {string}
tags : {@{id=0; name=string}}
status : availableInvoke-RestMethod は、サーバーからの応答でコンテンツタイプ「application/json」が返されるため、返された JSON を自動的にオブジェクトに変換します。
エラー 404 - 見つかりませんは通常、オブジェクトが見つからないことを意味し、URLが間違っているわけではありません。
あなたは今、最初のREST API呼び出しに成功しました。しかし、データを取得するだけではかなり制限がありますので、POSTメソッドを使って何かを作成しましょう。
POSTメソッドでオブジェクトを作成する
POSTメソッドは主にユーザーやエントリなどを作成するために使用されます。POSTリクエストは、通常JSON形式でRESTエンドポイントに情報を含むBODYを送信しますが、URLエンコードされたフォームとして送信することもできます。
あなたは、/petエンドポイントにPOSTできるJSONオブジェクトを作成する方法を学ぶことになります。
ドキュメントのPOST /pet行を展開すれば、JSONがどのようになっているべきかを見ることができます。
まず、後でJSONオブジェクトに変換できるハッシュテーブルを作成しましょう。生のJSONは、PowerShellスクリプトでの機能を制限するため、避けるべきです。
$Body = @{
id = 19
category = @{
id = 45
name = "Whatever"
}
name = "Dawg"
photoUrls = @(
"string"
)
tags = @(
@{
id = 0
name = "string"
}
)
status = "available"
}もし、望むJSONに変換できるハッシュテーブルを作成するのが難しい場合は、PsdKitモジュールをインストールし、コマンドを使用してください：
$JsonString | ConvertTo-Psd
これで、ハッシュテーブルをJSON文字列に変換して/petエンドポイントにPOSTできるようになりました。
$JsonBody = $Body | ConvertTo-Json
$Uri = "https://petstore.swagger.io/v2/pet"
Invoke-RestMethod -ContentType "application/json" -Uri $Uri -Method Post -Body $JsonBody
id : 19
category : @{id=45; name=Whatever}
name : Dawg
photoUrls : {string}
tags : {@{id=0; name=string}}
status : availableオブジェクトが作成されると、通常は確認のために作成されたオブジェクトを受け取ります。
DELETEを使用する
DELETEメソッドはデータを削除し、その方法はここで示されているようにGETメソッドに非常に似ています:
PS51 > Invoke-RestMethod -Method DELETE -ContentType "application/json" -Uri "https://petstore.swagger.io/v2/pet/1"必要になるかもしれないものを削除しないように注意してください。
PUTを使用する
PUTメソッドは既存のデータを更新します。これは、POSTメソッドと同様に、完全または部分的なJSONオブジェクトを送信することによって行われます:
PS51> $Body = [PSCustomObject]@{
id = 19
name = "Dawg with a new name"
}
PS51> $JsonBody = $Body | ConvertTo-Json
PS51> $Uri = "https://petstore.swagger.io/v2/pet"
PS51> Invoke-RestMethod -ContentType "application/json" -Uri $Uri -Method PUT -Body $JsonBody
id name photoUrls tags
-- ---- --------- ----
19 Dawg with a new name {} {}通常、REST APIは使用されたデータおよび/または更新されたデータを含むJSONオブジェクトを返します。このオブジェクトが更新されたことを確認するには、それに対してGETメソッドを使用します:
PS 51> Invoke-RestMethod -ContentType "application/json" -Uri "https://petstore.swagger.io/v2/pet/19"
id : 19
category : @{id=45; name=Whatever}
name : Dawg with a new name
photoUrls : {string}
tags : {@{id=0; name=string}}
status : available関数を作成する
これらのコマンドをそのまま書き出すのは、かなり面倒になり、実際には拡張性がありません。エンドポイントを複数回呼び出す場合は、それ用の関数を作成してください。これは非常に簡単で、数行だけで済みます。
Function Get-PetstorePet {
[cmdletbinding()]
param(
Id of the pet
[Parameter(Mandatory,ValueFromPipeline)]
[int]$Id
)
Begin{}
Process{
$RestMethodParams = @{
Uri = "https://petstore.swagger.io/v2/pet/$Id"
ContentType = "application/json"
Method = "GET"
}
Invoke-RestMethod @RestMethodParams
}
End{}
}関数を作成した後、スクリプト内でそれを呼び出すことができます。
PS51> Get-PetstorePet -Id 1
id name photoUrls tags
-- ---- --------- ----
1 Doggie {http://picture.url} {} ペットストアで新しいペットを作成するためにも、このPOSTメソッドを使用できます:
Function Add-PetstorePet {
[cmdletbinding()]
param(
Id of the pet
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[int]$Id,
Name of the pet
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[string]$Name,
Status of the pet (available, sold etc)
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[string]$Status,
Id of the pet category
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[int]$CategoryId,
Name of the pet category
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[string]$CategoryName,
URLs to photos of the pet
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[string[]]$PhotoUrls,
Tags of the pets as hashtable array: @{Id=1;Name="Dog"}
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[Hashtable[]]$Tags
)
Begin{}
Process{
$Body = @{
id = $Id
category = @{
id = $CategoryId
name = $CategoryName
}
name = $Name
photoUrls = $PhotoUrls
tags = $Tags
status = $Status
}
$BodyJson = $Body | ConvertTo-Json
$RestMethodParams = @{
Uri = "https://petstore.swagger.io/v2/pet/"
ContentType = "application/json"
Method = "Post"
Body = $BodyJson
}
Invoke-RestMethod @RestMethodParams
}
End{}
}そして、その後このPowerShell関数を呼び出すことで、この非常に長い作業がずっと簡単になります:
PS51> $AddPetStorePetsParams = @{
Id = 44
Name = "Birdie"
Status = "available"
CategoryId = 50
CategoryName = "Hawks"
PhotoUrls = "https://images.contoso.com/hawk.jpg"
Tags = @(
@{
Id=10
Name="Not eagles"
}
)
}
PS51> Add-PetStorePet @AddPetStorePetsParams
id : 44
category : @{id=50; name=Hawks}
name : Birdie
photoUrls : {https://images.contoso.com/hawk.jpg}
tags : {@{id=0}}
status : availableあなたが日常的に使用する多くのモジュールは、バックグラウンドでREST APIのみを使用する関数で構成されている可能性が高いです。
要約
REST APIの使い方を学ぶことは、主にドキュメントを読む方法を学ぶことです。この記事では、SWAGGERベースのドキュメントを使用しましたが、これは他のスタイルのドキュメントがどのように見えるかを示しています。
さらに、API呼び出しを関数に変換することで、多くの時間を節約し、作業を容易にし、スクリプトをクリーンに保つことができます。