PowerShell で Web API をハンドリングする

Web API と言うと、ざっくり分けて REST API と SOAP API の2種類になるのですが、世の中で言う Web API はほぼ REST API だと思います(個人的感覚ですけど)

PowerShell は REST も SOAP も両方使えるので、REST API の一般的なハンドリング方法を解説します
(以降 API は REST API と読み替えて下さい)

SOAP は末尾に解説しているリンクを張っていますので、そちらからどうぞ

API の動作を確認したい場合、Web サービスであれば Postman が有名ですが、Web UI をチマチマ操作するのも面倒なので、僕はもっぱら PowerShell を使っています

大量の引数も、PowerShell であればテキストエディタや VS Code で書けば良いので効率よくテスト出来ます

Windows PowerShell でも、マルチプラットフォームの PowerShell のどちらでもテストできるので、ちょっとしたコツがわかれば、結構便利に使えます

API のパラメーター

API で使用する重要なバラメーターは以下となります

パラメーター	意味	例
エンドポイント	API を受け取る URL	https://api.example.com/customer/regist
メソッド	API の動作	GET POST
ヘッダー	認証情報の格納場所	App_ID App_Secret
ボディ	リクエストパラメーター本体	後述
ContentType	データ形式	application/json

これを PowerShell でハンドリングするにはハッシュテーブル形式で以下のように書きます

ヘッダー

認証情報として、ヘッダーに app_id と app_secret をセットするのであれば、以下のように書きます

# ヘッダー
$headers = @{
    app_id = '01249faf-21ec-49d7-8a08-f1bb9d3607f5'
    app_secret = '3e00270e-cb6a-4d62-84e8-a7e0ba7ab23a'
}

ボディ

API リクエストの本体で、こんな感じで書きます

# リクエストパラメーター
$body = @{
    last_name = '海野'
    first_name = '博'
    last_name_kana = 'ウミノ'
    first_name_kana = 'ヒロシ'
    email = 'h.umino@example.com'
    gender_id = '1'
}

API は UTF-8 で送る必要があるので、ボディを UTF-8 にエンコードします

日本語が含まれている場合は、UTF-8 にエンコードが必須ですが、API によっては日本語が含まれていない場合でも UTF-8 にエンコードしないとエラーになるケースがあるので、ボディは UTF-8 にエンコードの呪文をかけると思っておいた方が余計なエラーに悩まされなくて良いかと思います
(トキトギ忘れてヤラカスのはナイショ w)

# UTF-8 にエンコードする
$JsonData = $body | ConvertTo-Json
$SendJson = [System.Text.Encoding]::UTF8.GetBytes($JsonData)

エンドポイント/メソッド/ContentType

エンドポイントとメソッド、ContentTypeは Invoke-RestMethod コマンドレットのオプションとして指定します

エンドポイントは、API を受け付ける URL なので、API 説明書で指定されているか、API 提供者から情報提供されます

メソッドは、使用する API ごとに決まっているので、API 説明書で指定されているメソッドを指定します

ContentTypeは、データタイプです
REST API は、json でリクエストパラメーターを記述するので「application/json」をしています
エラーになる場合は、この指定を外してみるとエラーが起きなくなる事があります

API を叩く

では、Invoke-RestMethod で API の叩き方です

# API を叩く
$Response = Invoke-RestMethod -Method Post -Uri $URL 'https://api.example.com/customer/regist' -Body $SendJson -Headers $headers -ContentType 'application/json'

API の実行結果は「status」にステータスが、「data」に戻り値が格納されているので、以下のように分解すると良いでしょう

$Status = $Response.status
$Data = $Response.data

まとめ

一連のスクリプトをまとめると以下のようになります

# ヘッダー
$headers = @{
    app_id = '01249faf-21ec-49d7-8a08-f1bb9d3607f5'
    app_secret = '3e00270e-cb6a-4d62-84e8-a7e0ba7ab23a'
}

# リクエストパラメーター
$body = @{
    last_name = '海野'
    first_name = '博'
    last_name_kana = 'ウミノ'
    first_name_kana = 'ヒロシ'
    email = 'h.umino@example.com'
    gender_id = '1'
}

# UTF-8 にエンコードする
$JsonData = $body | ConvertTo-Json
$SendJson = [System.Text.Encoding]::UTF8.GetBytes($JsonData)

# API を叩く
$Response = Invoke-RestMethod -Method Post -Uri $URL 'https://api.example.com/customer/regist' -Body $SendJson -Headers $headers -ContentType 'application/json'

$Status = $Response.status
$Data = $Response.data

こいつを PowerShell プロンプトにコピペするか、.ps1 に書いてやれば API を簡単に叩くことが出来ます

参考情報

SOAP の PowerShell ハンドリング
https://www.vwnet.jp/windows/PowerShell/2018042401/SOAPbyPowerShell.htm