どうも。つじけ（tsujikenzo）です。この連載では 「会計freeeAPIを使って残高確認表を作成しよう」 について全7回でお送りします。今日は3回目で 「会計freeeAPIを操作する」 をお届けします。
前回のおさらい
前回は、「アプリとアクセストークンを準備する」 ということで、自分専用の「マイアプリ」を作成し、アクセストークンを取得するステートメントを作成しました。
今回は 「会計freeeAPIを操作する」 をお届けします。座学的な内容になってしまいますが、きちんとAPIの基礎を理解しましょう。
APIとは
APIに関しては、数多くの記事や書籍があります。なので、今回は「たとえ話」をしてみたいと思います。
APIは、Application Programming Interface (アプリケーション・プログラミング・インタフェース) の略です。
インターフェイスなので、たとえると 「窓口」 だと思っていただいて構いません。
外国人が日本で活躍するには
日本で活躍したい外国人「KENZO-san」が、日本に出入国をする場合は、労働ビザの取得や、許可証の返却など、さまざまな手続きを取る必要があります。
その手続きの窓口になっているのが、「入国管理局」です。
KENZO-sanは、母国語で手続きを行いたいですが、入国管理局は限られた言語のみ受付をしています。大切なのは、やりとりの決まりごとを決めないと、お互いに手続きができないことです。
この決まりごとを 「プロトコル」 と呼びます。
もし、やりとりをインターネットで行う場合は、HTTP、Hyper Text Transfer Protocol（ハイパーテキストトランスファープロトコル）という決まりごとでやりとりをしようね、ということになります。
HTTPリクエスト/レスポンス
「窓口」に対して、HTTPという決まりごとを守って、手続きのお願いをすることを 「HTTPリクエスト」 と呼びます。
一方で、HTTPリクエストを受け取った窓口が、おこなう返事のことを 「HTTPレスポンス」 と呼びます。
入国管理局への手続きは、いくつかの種類があります。
– 届出・・・書類を用意して提出するだけで手続きが完了する
– 申請・・・手続きが完了するためには、入国管理局による審査が必要
なので、目的に合わせてどのような手続きが必要なのか、ちゃんと理解する必要があります。
同様に、HTTPリクエストにも、いくつかの種類があります。
– GET・・・情報を取得する
– POST・・・情報を作成する
– DELETE・・・情報を削除する
– PUT・・・情報を更新する
なので、「窓口」つまり相手側のAPIに対して、適切なHTTPリクエストを送信することで、希望する返答「HTTPレスポンス」を受け取ることが、「APIを操作する」 といえます。
最近よく耳にする「API」は、ほぼインターネット上でやりとりをしますので 「Web API」 とも呼ばれます。
エンドポイント
APIはアプリケーションの窓口のことでしたが、手続きのために公開されている受付が 「エンドポイント」 です。
手続きによって、やりとりをするエンドポイントが変わります。
Web APIでは、インターネットでやりとりをしますので、エンドポイントが変わるということは、手続きによって、アクセスするURL先を変えていく ということです。
エンドポイントは、APIを公開しているサービス側で情報提供していることが多いです。この情報提供を 「リファレンス」 と呼びます。よくビジネスの世界で「リファレンスを参照してください」と言いますが、「リファレンス」とは「参照」という意味 なので、やたらカタカナ語を使うのは避けた方がいいですね。。
会計freeeのAPIリファレンス
会計freeeには、会計APIリファレンス（以降、リファレンス）が用意されています。
リファレンスは項目ごとに分かれており、「HTTPリクエストの種類」、「目的」、「エンドポイント」が分かりやすく表示されています。
たとえ話のKENZO-sanは、ここでさようならです。日本で活躍することはもちろん、世界で活躍するビジネスマンを目指しているそうです。
HTTPリクエスト
会計freeeAPIを操作するということは、HTTPリクエストを正しく送信するということでした。
今回は「増えすぎてしまった取引先を管理したい」という要求に応えたいと思います。
それでは、実際にHTTPリクエストを送信する流れを確認しましょう。
リファレンスの確認：GET
HTTPリクエストを送信する際に、まず最初に行うことは、リファレンスを確認 することです。
[Partners取引先]という項目があります。
まずは登録されているすべての取引先を見たいと思いますので「取引先一覧の取得」をクリックします。
取引先一覧の取得のHTTPリクエストの種類は「GET」です。
GETには、3つの項目が表示されています。
– 概要・・・このエンドポイントの概要
– Parameters(パラメーター)・・・エンドポイントの詳細設定方法
– Responses（レスポンス）・・・受け取るHTTPレスポンス例
Partnersの[Try it out]をクリックすると、エンドポイントに付与する詳細を入力できます。
「取引先一覧の取得」では以下の4項目を指定できるようです。
パラメーターの入力が終わったら[Excute]をクリックします。
画面をスクロールすると、[Request URL]（リクエストURL）が生成されています。
このリクエストURLを使って、会計freeeからデータを取得することになります。GASの書き方は追ってご説明いたします。
リファレンスの確認：POST
新しく取引先を登録したいという場合は、「取引先の作成」をクリックします。
取引先の作成のHTTPリクエストの種類は「POST」です。POSTには 「リクエストボディ」 と呼ばれる、POSTリクエストで送信可能なテキストデータを設定する項目があります。
POSTには、4つの項目が表示されています。
– 概要・・・このエンドポイントの概要
– Parameters(パラメーター)・・・エンドポイントの詳細設定方法
– Request body（リクエストボディ）・・・POSTリクエストで送信可能なテキストデータ
– Responses（レスポンス）・・・受け取るHTTPレスポンス例
Partnersの[Try it out]をクリックすると、リクエストボディを作成できます。
あらかじめ初期データが入力さていますので、必要に応じて、テキストを変更してください。
リクエストボディの入力が終わったら[Excute]をクリックします。
画面をスクロールすると、[Request URL]（リクエストURL）が生成されています。
POSTリクエストの場合、このリクエストURLとリクエストボディを使って、会計freeeにデータを登録することになります。GASの書き方は追ってご説明いたします。
HTTPレスポンス
これまでは、HTTPリクエストをみてきました。最後に 「HTTPレスポンス」 を確認しましょう。
おさらいですが、HTTPレスポンスとは、HTTPリクエストを受け取った窓口が、おこなう返事のこと でした。
では、実際にはどのような返事をするのでしょうか。
リファレンスの確認
ふたたび、「取引先一覧の取得」のリファレンスを確認します。
Responses（レスポンス）は、このような見出しの構造になっています。
Code：Description
わかりやすく日本語にするとこのようになります。
ステータスコード：説明
ステータスコード
ステータスコードとは、HTTPリクエストが正常に受け付けされたかを示すコードです。
世界中で、一番有名なステータスコードは 「404 Not Found」 だと思います。「URLが不明です」というエラーメッセージです。
「200」はHTTPリクエストが成功したことを示すステータスコードです。
リファレンスのResponses（レスポンス）の１項目目は、ステータスコードが200だった場合（HTTPリクエストが成功した場合）、どのようなレスポンスを返すのか が表示されています。
同様に、ステータスコードが400だった場合（HTTPリクエストが失敗した場合）、どのようなレスポンスを返すのかが表示されています。
JSONとは
レスポンスの中身は、「JSON形式」 と呼ばれる テキストデータ です。
JSONについて詳しい解説は、過去にブログを書いたことがありますので、こちらもご参照いただければ幸いです。
JSONの加工（詳細は後述）
JSONはテキストデータですが、その加工は、2つのメソッドを覚えていただければ問題ありません。
//JSONをJSONオブジェクトに変換する
JSON.parse(JSON);
//JSONオブジェクトをテキスト型に変換する
JSON.stringify(JSONオブジェクト);
今回はメソッドの紹介だけです。2つのメソッドの詳しい解説は、次回以降、GASを書くときにお伝えします。
まとめ
以上で、「会計freeeAPIを操作する」 ということで、「APIとはなにか」、「HTTPリクエストとHTTPレスポンス」などをお届けしました。
座学的な内容ばかりで、退屈だったかもしれません。。。
次回以降はGASを使って、会計freeeAPIをガンガン操作していきたいと思います。
「HTTPリクエストを送信」とか、「HTTPリクエストが成功」とか、「HTTPレスポンスがJSONを返す」といった動作を、実際に手を動かして経験していきましょう。
次回は 「事業所IDを取得しよう」 をお届けします。
この連載の目次
[GAS]会計freeeAPIを使って残高確認表を作成しよう
1. [GAS][会計freee]連載の概要と準備運動
2. [GAS][会計freee]アプリとアクセストークンを準備する
3. [GAS][会計freee]会計freeeAPIを操作する
4. [GAS][会計freee]事業所IDを取得しよう
5. [GAS][会計freee]取引（収入／支出）を取得しよう
6. [GAS][会計freee]取引（収入／支出）を登録しよう
7. [GAS][会計freee]残高確認表を作成しよう
