コラボフロー Advent Calendar 2022 16日目の記事です！
外を歩けばすっかりと冬らしくなりましたね。
私が住む静岡では、ほぼ雪が降らないので冬らしい季節といえば時折見る水溜まりの氷や、葉の落ちた落葉樹でしょうか。
さむい！っと叫びながら登校していく子供たちもそんな風景の一つかもしれません。
さむいと体がこわばって力んで…力んで…
力といえばパワー！！パワーといえばPowerShell！！
そんなわけで今回は、PowerShellを使ってコラボフローのREST APIを実行してみたいと思います！
はじめに
本記事では、Windowsに標準搭載されている PowerShellのVersion5系 の利用を前提としています。
まずは、PowerShellでREST APIの実行を体験していただくために、本来必要なセキュリティ対策や、エラー処理を省いています。
「こんな流れで、PowerShellからREST APIを実行できるんだ！」と思っていただけたら幸いです。
PowerShellってなに？
PowerShellは、コマンドプロンプトのようにOSやデータを操作することができるシェルで、Windowsには標準でインストールされています。
すでにご存じの方でも独特のコマンドや記述方法がとっつきにくいという意見が散見されます。
※かつての私もそうでした。
しかし、PowerShellはその名の通りとても強力なシェルであり、頑張ればGUIアプリを作成する※ことすら可能です。
※あまりおすすめしません。
オブジェクト指向などのプログラミングを経験された方であれば、PowerShellのコマンド（正しくはコマンドレット）の結果がオブジェクトで返るという点は、素晴らしい利点となりうることをご理解いただいていると思います。
本セクションですでに述べたように、Windowsに標準でインストールされていることから、何も設定しなくても使えるところも大変魅力ですね。
ではさっそくやっていきましょう
@collabo-hiroakiさんの「コラボフロー REST APIを利用するためのお話」では、REST APIについてわかりやすく解説いただきました。
また、@nonbinさんの「コラボフロー REST APIって叩いてみた？」では、リファレンスサイトからREST APIを実行する手順について解説いただきました。
まだ読まれていない方は、是非読んでくださいね！
さて...どうですか？そろそろ、コマンドで実行してみたくなりませんか…？
今回は、（実行APIなどは異なりますが）PowerShellでやっていくという流れになります。
まずは全体の流れを掴みましょう
おおまかな流れは以下の通りになります。やや複雑なところもありますが、そこはもう呪文と覚えていたければ問題ありません！
今回は、組み合わせることでAPIを実行するスクリプトにすることも可能です。
- API実行に必要な情報を収集する
- APIキーと実行ユーザーIDから認証情報をBASE64化して作成する
- ヘッダを作成する
- ボディを作成する※
- REST API リクエストを実行する
- 実行結果をごにょごにょする
APIによってはボディ部の指定は不要になります。
どうですか？たったの6ステップです！
では早速、やっていきましょう！！
API実行に必要な情報を収集する
まずは、APIキーを取得します。
ノンビンさんの記事を参考にAPIキーを取得・メモしましょう！
加えて、今回は、申請APIを実行するのに、以下の情報が必要です。
- 申請する経路の経路ID
- 申請する経路があるコラボフローアプリケーションのコード
- フォームのパーツ情報
- 申請者のユーザーID
経路のIDは次の方法で確認します。
- コラボフローにシステム管理者または設定権限者でログインします。
- アプリ設定 > 経路設定 をクリックします。
- 申請に使いたい経路の「経路ID」列の数字をメモします。
アプリケーションのコードは以下の方法で確認します。
- コラボフローにアクセスします。
- 該当のアプリを開きます。
- ブラウザのアドレスバーから、
app_cd=x(xは数字）を探します。 - xの数字部分をメモします。
フォームパーツ情報は次の方法で確認します。
- アプリ設定 > フォーム設定をクリックします。
- 先ほどの経路で使用されているフォームを選択します。
- 編集画面に入り、APIで入力をおこないたいパーツをクリックします。
- パーツ設定画面のパーツIDをメモします。
申請者のユーザーIDは次の方法で確認します。
- システム管理者でコラボフローにログインします。
- 歯車アイコン > システム管理エリア をクリックします。
- 組織管理タブ > APIで申請をおこなうユーザーをクリックし、ユーザーIDの項目をメモします。
以上で、必要な情報は集まりました！
今回は、次のような申請書・情報を想定します。
皆さんの環境に合わせて変更してみてください。
- 申請する経路の経路ID：30
- フォームのパーツ情報
- fidName - テキスト1行パーツ
- fidAge - テキスト1行（数値）パーツ
- fidNote - テキストエリアパーツ
- 申請者のユーザーID：naruo
認証情報をBASE64化して作成する
PowerShellのターミナルを開く
さぁ、ここからはPowerShellのターミナルを開いてコマンドを入力していきます。
スタートボタンをクリックしたら「PowerShell」と入力してみましょう。
こんな選択肢が表示されましたか？クリックすれば黒または青い次のようなウィンドウが開かれます。
これがPowerShellのターミナルです。ここにコマンドを入力することで、PowerShellでの操作がおこなえます。（設定を少しいじってあるので、細かな表示は異なるかもしれません。。）
BASE64化する
早速、以下のコマンドのうち、「***をここに入力」の部分のみ書き換えて、ターミナルに張り付けてEnterキーを押下します。
$apiKey = "APIキーをここに入力"
$requestUserId = "API実行ユーザーIDをここに入力"
$base64Target = "${requestUserId}/apikey:${apiKey}"
$bytes = [System.Text.Encoding]::UTF8.GetBytes($base64Target)
$base64Text = [Convert]::ToBase64String($bytes)
$collaboflowAuthText = "Basic ${base64Text}"
上記コマンドは、BASE64化された認証ヘッダーに指定するべき文字列を生成し、$collaboflowAuthText変数に格納するという内容です。
やや複雑ですが、呪文として割り切ってしまいましょう！
試しに、$collaboflowAuthTextの中身を画面に表示するために以下のコマンドをPowerShellのターミナルに入力してみましょう。
$collaboflowAuthText
次のような、Basic に続くアルファベットや数字・記号によって構成された文字列が表示されましたか？(Xはアルファベットや数字）
Basic XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX==
表示されていれば成功です！次のステップに進みましょう！
ヘッダを作成する
では、先程生成して認証文字列を、APIリクエストのヘッダーにセットするために、以下のコマンドを入力します。
$header = @{}
$header.Add("X-Collaboflow-Authorization" ,$collaboflowAuthText)
このコマンドは、$headerという連想配列の変数に、X-Collaboflow-Authorizationのキー・値をセットするという処理をおこなっています。
後でこの$header変数を利用します。
ここでは、さらにもう一つ、文字列のエンコーディングを正しく扱えるようにContentTypeに指定する値をセットします。
$contentType = "application/json; charset=utf-8"
PowerShellの理解が深い方向けの解説
後で利用するInvoke-RestMethodではオプションとして、-Headerと-ContentTypeがあります。
-Header内でContent-Typeとcharsetを指定した場合無視されるようで、日本語が含まれた内容をリクエストした際に文字化けする問題が発生します。
この問題を解消するため、charset設定は、-ContentTypeオプションで指定します。
ボディを作成する
実行したいAPIに合わせたボディを作成します。
ボディ部ではほとんどの場合、JSONという文字列を指定しますが、今回はJSONではなく、PowerShellの連想配列で指定してからJSON化する方法を利用します。
今回は、「申請書の申請・下書き保存」のAPI用に必要な最低限の内容を作成します。
詳細やその他のAPIについては以下のリンクをご確認ください。
http://docs.collaboflow.com/api-docs/
$body = @{
"app_cd" = 1 #申請書のあるアプリIDをここに
"processes_id" = 30 #申請する経路の経路ID（例では30）をここに
"title" = "申請書のタイトル（PowerShellから作成しました）"
"document" = @{
"fidName" = "fidNameに入力する文字列"
"fidAge" = 23
"fidNote" = "fidNoteに入力する文字列"
}
}
$jsonBody = $body | ConvertTo-JSON
※APIによっては上記ボディの作成は不要です。
REST APIを実行する
REST APIを実行するにあたり、エンドポイントのURLも設定しておきましょう。
申請書の申請・下書き保存のAPIのエンドポイントを指定します。
xxxxxx部は皆さんのインスタンス名に変更してください。
$url = "https://cloud.collaboflow.com/xxxxxx/api/index.cfm/v1/documents"
さらに、目的のREST APIのメソッドも定義してしまいましょう。
APIドキュメントを確認すると、申請書の申請・下書き保存APIは、POSTと示されていますね。
APIドキュメント通りにPOSTを指定しましょう。
$method = "POST"
さて、PowerShellでは、Webリクエストをおこなうにあたり、２種類のコマンドレットが存在します。
Invoke-WebRequestと、Invoke-RestMethodです。それぞれ微妙な違いはあります※が、今回はInvoke-RestMethodコマンドレットを使用します。
以下のようにターミナルに入力して実行してみましょう。
$response = Invoke-RestMethod -Uri $url -Header $header -Body $jsonBody -Method $method -ContentType $contentType
上記コマンドを実行後、特に何も表示されていないかと思いますが、そこは安心してください。
$response変数に結果が全て収められています。
※実行後に何か表示される場合はエラーが起きている可能性が高いです。
次のようにターミナルに入力し、実行結果を確認してみます。
$response
どうでしょうか？API実行結果のJSONがしっかりと解析されてPowerShellの連想配列になっているのがお分かりでしょうか？
document_number : 030-000001
represent_usercd :
request_groupname : なるおグループ
app_cd : 1
flow_status : decision
end_date : 2022-12-16Txx:xx:xxZ
represent_username :
request_usercd : XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
request_groupcd : XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
request_date : 2022-12-16Txx:xx:xxZ
document_id : 12345
request_username : なる なるお
link : https://cloud.collaboflow.com/xxxxxx/index.cfm?app_cd=1&fuseaction=clz_DocumentDesc&nPInstanceCD=12345
error : False
title : 申請書のタイトル（PowerShellから作成しました）
request_titles : {}
processes_id : 30
ここまできたら、結果を望む形で処理してあげれば、もう完成です！
実行結果をごにょごにょする
実行結果から、さらに細かく結果を見たい場合は次のように入力してみましょう。
$response.link
これでAPIの実行結果を確認できるところまで進めました。
例えば、これを規定のブラウザで開きたい場合は、以下のようにコマンドを入力してみましょう。
start $response.link
これを毎回やるのは…めんどくさいですよね？
これまで入力した内容を、スクリプトファイルにしてしまえば、いつでも再実行が可能になります！！以下の手順でファイル作成をしてみましょう。
- 空のテキストファイルを作成します。
- ファイル名は任意で構いませんが、例として「コラボフロー申請API実行.ps1」とします。
- これまで入力したすべてのコードをファイルに張り付けます。
- エンコードをutf-8のBOM付で保存します。
実行する際は以下の手順で実行します。
- 作成したスクリプトファイルを右クリック
- PowerShellで実行を選択します。
- 結果をCSVファイルに保存する
- さらに高度なフィルタリングをかけて、結果を絞り込む
- APIの実行結果によって、別のコマンドやWebサービスに結果を渡す
- Windowsのタスクスケジューラを利用して定期実行タスクのようなものを作る
など、コラボフローと何かを繋ぐことが意のままに行えるようになります！
今回のコラボフロー Advent Calendar 2022ではREST API成分が大量に含まれていますので、是非他の記事も参考に、コラボフローRESTAPIマスターになってください！
この記事が皆様の一助となれば、幸いです。
それでは！
明日は、テトリス狂の@tetrer さんです！