Home > Windows にまつわる e.t.c.

PowerShell で Web API を叩く(kintone 編)

サイボーズ社が提供している kintone は、開発インターフェースを持っており、REST API もサポートされています。

cybozu developer network
https://developer.cybozu.io/hc/ja

kintone API
https://developer.cybozu.io/hc/ja/articles/360028177472

 

REST API は PowerShell の Invoke-RestMethod でハンドリングできるので、PowerShell で kintone の操作が可能です。

僕が今まで使っていたパターンは、API キーを json にセットするパターンだったのですが、kintone の API はリクエストヘッダーに API キーをセットしたり、クライアント証明書を使ったりと、今まで扱っていたパターンと少々勝手が違っていたので技術情報としてまとめます。

PowerShell での API ハンドリングにフォーカスするので、kintone そのものの解説は割愛します。

 

GET API を叩く

まずは一番単純なレコード取得を例に API をどう叩くのか解説します。

レコードの取得（GET）
https://developer.cybozu.io/hc/ja/articles/202331474

 

リクエストパラメーターのセット

リクエストパラメーターは、通常の REST API と同様に連想配列にセットし、-Body オプションに渡します。

# リクエストパラメーター
$body = @{
    app = '1'
    id = '2'
}

 

API キー(APIトークン)をリクエストヘッダーにセットする

kintone の REST API は、API キーを json にセットするのではなく、リクエストヘッダーに API キーではをセットします。

(kintone では API キーを「APIトークン」と呼んでいます)

PowerShell でリクエストヘッダーに API キーをセットするには、API キーを連想配列にセットし、-Headers オプションに渡します。

こんな感じでAPI キーを連想配列にセットします。

# API キー
$headers = @{
    'X-Cybozu-API-Token' = '発行した API キー'
}

 

その他のパラメーター

kintone の場合は、テナントごとに FQDN が異なっており、API ごとに URI が異なっています。

# Web API の URI
$AppUri = 'https://hogehoge.cybozu.com/k/v1/record.json'

 

GET API を叩く

パラメーターが準備出来たら Get で API を叩きます

# GET API を叩く
$Report = Invoke-RestMethod -Method Get -Uri $AppUri -Body $body -Headers $headers

 

戻り値は json で返ってくるのですが、PowerShell が暗黙でオブジェクトに変換してくれるので、そのまま PowerShell で使うことが出来ます。

メンテナンス性も考慮してまとめると、こんな感じですね。

# Web API の URI
$URL = 'https://hogehoge.cybozu.com'
$URI = "/k/v1/record.json"
$AppUri = $URL + $URI

# 取得した API Key
$ApiKey = '発行した API キー'

# API キー
$headers = @{
    'X-Cybozu-API-Token' = $ApiKey
}

# パラメーター
$ID = '1'
$Recode = '2'

# リクエストパラメーター
$body = @{
    app = $ID
    id = $Recode
}

# GET API を叩く
$Report = Invoke-RestMethod -Method Get -Uri $AppUri -Body $body -Headers $headers

 

POST API を叩く

続いて、json 形式のデータを渡す Post の場合です。

レコードの登録（POST）
https://developer.cybozu.io/hc/ja/articles/202166160

 

POST の場合、引き渡すデータ形式が json であることを明示的に伝える必要があるのと、日本語を含む json を引き渡す際の考慮が必要です。

 

データ形式が json であることを宣言する

データ形式が json であることを宣言するには、リクエストヘッダーで Content-Type を指定するのですが、PowerShell の場合は -ContentType オプションがあるので、このオプションの引数に application/json を指定します。

 

データーとして json をセットする

kintone の場合、日本語データを扱うことが多いのですが、日本語を含む json はそのまま送信しても正しく受け取ってくれません。

この問題を回避するには、PowerShell 上で連想配列として扱っているデータを明示的に json 変換し、更にバイト配列に変換して送信します。

# Put するレコード
$Recode = @{
    'Name' = @{
        value = '村嶋 修一'
    }

    'Age' = @{
        value = '20'
    }
}

# リクエストパラメーター
$body = @{
    app = '1'
    record = $Recode
}

# リクエストパラメーターを json にする
$JsonData = $body | ConvertTo-Json

# json をバイト配列にする
$SendJson = [System.Text.Encoding]::UTF8.GetBytes($JsonData)

 

まとめるとこんな感じですね

# Web API の URI
$URL = 'https://hogehoge.cybozu.com'
$URI = '/k/v1/record.json'
$AppUri = $URL + $URI

# 取得した API Key
$ApiKey = '発行した API キー'

# API キー
$headers = @{
    'X-Cybozu-API-Token' = $ApiKey
}

# Put するレコード
$Name = '村嶋 修一'
$Age = '20'

$Recode = @{
    'Name' = @{
        value = $Name
    }

    'Age' = @{
        value = $Age
    }
}

# リクエストパラメーター
$body = @{
    app = '1'
    record = $Recode
}

# リクエストパラメーターを json にする
$JsonData = $body | ConvertTo-Json

# json をバイト配列にする
$SendJson = [System.Text.Encoding]::UTF8.GetBytes($JsonData)

# GET API を叩く
$Report = Invoke-RestMethod -Method Post -Uri $AppUri -Body $SendJson -Headers $headers -ContentType 'application/json'

 

ちなみに、レコードのフィールド名はフィールドの一覧で取得できる「Code」です。

フォームの設定の取得
https://developer.cybozu.io/hc/ja/articles/204783170

 

BASIC 認証とクライアント証明書

kintone の場合、アプリを API でハンドリングする場合は、アプリ毎に発行する API キーが使えるのですが、テナント情報そのものをハンドリングする場合は、この API キーが使えません。

例えば、テナントに登録している組織を取得する場合とかがこれに該当します。

組織エクスポートAPI
https://developer.cybozu.io/hc/ja/articles/202124754-組織エクスポートAPI

 

この場合、BASIC 認証を使うのですが、攻撃リスク低減のためにクライアント証明書を使うようにしている場合は、Invoke-RestMethod もクライアント証明書を使用する必要があります。

Windows の場合は、クライアント証明書をインストールして、拇印で証明書を指定する事が出来ますが、Windows 以外のプラットフォームではファイル状態のクライアント証明書をハンドリングします。

 

BASIC 認証用の API キーを作成する

BASIC 認証とは、「ID」と「パスワード」を「:」で接続し、BASE64 でエンコードしたデータで認証する方式です。

こんな感じですね。

# ID / Password
$ID = 'hogehoge@example.com'
$Pass = 'P@ssW0rd'

# 「:」で連結する
$Plain = $ID + ':' + $Pass

# バイト配列にする
$Byte = [System.Text.Encoding]::UTF8.GetBytes($Plain)

# BASE 64 にする
$Base64 = [System.Convert]::ToBase64String($Byte)

 

これで得られた BASE64 データを API キーに使用します。

kintone の場合は、リクエストヘッダーの「X-Cybozu-Authorization」にセットします。

$headers = @{
    'X-Cybozu-Authorization' = $Base64
}

 

拇印でクライアント証明書を指定する

Windows の場合は、クライアント証明書をインストールして、-CertificateThumbprint オプションで拇印を指定することが出来ます。

# 拇印でクライアント証明書を指定する
$Report = Invoke-RestMethod -Method Get -Uri $AppUri -Headers $headers -CertificateThumbprint '685D44EF4CC1215A744C71D54CD05BEDDE9664B5'

 

拇印の確認は Get-ChildItem で確認できます。

# ユーザーアカウント
Get-ChildItem Cert:\CurrentUser\My

# コンピューターアカウント
Get-ChildItem Cert:\LocalMachine\My

 

クライアント証明書そのものを使う

Windows 以外のプラットフォームでは、証明書をインストールすることが出来ないので、証明書ファイルそのものを使います。

証明書ファイルは .net の「X509Certificate2」で .pfx をハンドリングします。

# .pfx 証明書をバイナリリードする
$pfx = [System.IO.File]::ReadAllBytes('.pfx 証明書のパス')

# 証明書オブジェクトにする
$Cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($pfx, '平文パスワード')

# API を叩く
$Report = Invoke-RestMethod -Method Get -Uri $AppUri -Headers $headers -Certificate $Cert

 

関連情報

PowerShell で VirusTotal の Web API を使ったファイルの安全性を確認する
https://www.vwnet.jp/Windows/PowerShell/2016100501/CheckVirusTotalWebAPI.htm

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

 

back.gif (1980 バイト)

home.gif (1907 バイト)

Copyright © MURA All rights reserved.