【GAS×freeeAPI】APIリクエストのレスポンスから必要データのみを取り出す

こんにちは！ITライターのもり(@moripro3)です！

クラウド会計ソフトfreeeのAPIを使って経理業務を自動化するネタをシリーズでお届けしています。

このシリーズでは、freeeとチャットワークを連携して「当日入金予定の取引一覧を自動でチャットワークに送信するツール」を作成します。

成果物のイメージがこちら！入金予定のある日に、自動でチャットワークに通知が届きます。

前回の記事では、freeeAPIにGETリクエストを送信して、「当日入金予定の取引一覧」のレスポンスが返ってくることまでを確認しました。

【GAS×freeeAPI】GETリクエストで当日入金予定の取引一覧を取得する

「当日入金予定の取引一覧を自動でチャットワークに送信する」シリーズの第3回目。スクリプト実行時の「当日日付」を取得する関数を作成し、リクエストURLの日付パラメータを置き換え、GETリクエストでレスポンスを取得します。

tonari-it.com

2019.08.26

次のステップでは、レスポンスの文字列をスプレッドシートに出力する処理を作るのですが、いきなりシートに書き出すのはやや大変です。

そこで今回の記事では、freeeAPIのレスポンスから「必要なデータのみを取り出す方法」をお伝えします。

シリーズを通してfreeeAPIを使いこなし、経理業務の自動化を進めていきましょう！

（この記事はfreee株式会社さまとのコラボ企画です。シリーズを通して、皆さんの働くの価値を上げられるようサポートしていきます！）

前回のおさらいとgetDealsの部品化

前回の記事では、当日入金予定の取引一覧を取得する関数「getDeals」を作成しました。

ツールを完成させるためには、他にもいろいろな処理が必要です。すべての処理をひとつの関数に書くと長くなるので、処理ごとに「部品化」します。

• freeeAPIのレスポンスをスプレッドシートに書き出す処理
• スプレッドシートのデータを元に、チャットワーク通知用の本文を作成する処理
• チャットワークに送信する処理

関数getDealsも部品化します。前回はfreeeAPIのレスポンスをログ出力しましたが、return文で呼び出し元に戻すよう変更します。

また、エントリポイント（プログラムを構成するコードのなかで、最初に実行する位置）となるmain関数を作成します。今後、シリーズを通して作成する各処理（関数）は、すべてmain関数から呼び出すこととします。

function main() {
  
  var response = getDeals();
  Logger.log(response);
  
  //後続の処理を記述
  
}

/**
 * freeeAPIにGETリクエストを送信して取引一覧を取得する
 *
 * @return {object} freeeAPIからのレスポンス
 */
function getDeals() {
  
  var accessToken = getService().getAccessToken();
  
  var company_id = 'xxxxxxx'; //事業所ID
  
  var date = new Date(); //現在日時
  date = Utilities.formatDate(date, 'JST', 'yyyy-MM-dd'); //表示形式を変換
  
  //リクエストURL
  var requestUrl = 'https://api.freee.co.jp/api/1/deals?' + 
    'company_id=' + company_id + 
    '&status=unsettled' +
    '&type=income' + 
    '&start_due_date=' + date +
    '&end_due_date=' + date + 
    '&limit=100';
  
  //リクエスト送信時に付与するオプションパラメータ
  var params = {
    "method" : "get",
    "headers" : {"Authorization":"Bearer " + accessToken}
  };
  
  var response = UrlFetchApp.fetch(requestUrl,params);
  //Logger.log(response);
  
  return response;
  
}

main関数を実行すると、freeeAPIから取引一覧を取得できます。（2019/8/15に実行）

それでは、このレスポンスから「必要なデータのみを取り出す方法」を学んでいきましょう！

GETリクエストのレスポンスを「オブジェクト」に変換する

freeeAPIにGETリクエストを送信し、戻ってきたデータ（レスポンス）は、JSON形式の文字列です。文字列のままではGASで扱いにくいので、「文字列」を「オブジェクト」に変換します。

JSON形式の文字列をJavaScriptのオブジェクトに変換する、JSONオブジェクトのparseメソッドを使用します。

parseメソッドによって、文字列がオブジェクト（連想配列）に変換されます。

関数getDealsの戻り値（文字列）を変数responseに格納し、responseをparseメソッドでオブジェクトに変換します。

オブジェクトを格納する変数名はobjにしておきましょう。

var response = getDeals(); //freeeAPIからのレスポンス（文字列）
var obj = JSON.parse(response); //オブジェクトに変換
Logger.log(obj);

変数objの中身です。

見た目は文字列とあまり変わりませんが、GASで扱うためにはこの形式が相応しいのです。

オブジェクトからデータを抽出する

GASで扱いやすいように変換した「オブジェクト」から、目的のデータを抽出する方法を紹介します。

オブジェクトの値にアクセスするドット記法

オブジェクト（連想配列）とは、「キー」と「値」がペアになった集合体です。

ドット記法とは、オブジェクトから値を取り出す記述方法です。ドット(.)でキーを指定します。（「キー」の名称を「プロパティ名」といいます）

サンプルデータ（personオブジェクト）を用いて、ドット記法の使い方をみてみましょう。

var person = 
      {
        "name" : "Bob",
        "age" : 25,
        "brothers" : [
          {
            "name" : "Tom",
            "age" : 23
          },
          {
            "name" : "Jack",
            "age" : 20
          },
          {
            "name" : "Noah",
            "age" : 18
          }
        ]
      }

personオブジェクトの「nameプロパティ」の値を取得してみます。personオブジェクトに対して、ドット(.)でnameプロパティを指定します。

Logger.log(person.name); //Bob

つづいて、「brothersプロパティ」から値を取り出してみます。

brothersプロパティは角括弧[ ]で括られて配列になっているのがポイントです。兄弟の人数分のオブジェクトが並んでいます。

1番目の兄弟の年齢を取得します。配列の要素番号は0から始まるので、1番目 = 0です。
brothersプロパティの要素番号[0]を指定し、さらに、ageプロパティをつなげます。ドット(.)は複数つなげることが可能です。

Logger.log(person.brothers[0].age); //23

3番目の兄弟の名前を取得します。brothersプロパティの要素番号[2]を指定し、nameプロパティをつなげます。

Logger.log(person.brothers[2].name); //Noah

このように、プロパティ名をドット(.)でつなげてオブジェクトの値にアクセスする方法が「ドット記法」です。

レスポンスの件数をチェック

このツールは、該当の取引が存在する場合のみチャットワークに通知するので、取引が存在しない場合は、以降の処理は不要です。

そこで、ドット記法を使用して、まずは「レスポンスの件数」を取得します。

freeeAPIリファレンスで、各プロパティの意味が確認できるので見てみましょう。

「取引（収入／支出）一覧の取得」をクリックして展開します。

ResponsesのCode200の項目が、正常終了の場合のレスポンスを表しています。Modelをクリックすると、各プロパティの説明が記載されています。

「metaプロパティ」配下の「total_countプロパティ」が「検索条件に合致する取引の総数」であることが確認できます。

freeeAPIからのレスポンスをオブジェクトにした変数objはこのような形式になっています。（dealsプロパティの中身は省略）

ここから「total_countプロパティ」の値「3」を取り出してみましょう。

{
  "deals":[...],
  "meta":{
    "total_count":3
  }
}

変数objの「metaプロパティ」の「total_countプロパティ」をドット(.)で指定して連結すると、目的の値「3」を取得できます。

var total_count = obj.meta.total_count;
Logger.log(total_count); //3

対象データが存在する場合、つまり、total_countが0より大きい場合のみ、後続の処理に進むようにしたいので、if文で判定します。

var total_count = obj.meta.total_count;

if (total_count > 0) {

  //スプレッドシートに書き出す処理

}

ここまでがメイン関数の処理です。

取引データを取り出す

この項では、実際にスプレッドシートに書き出すデータ（チャットワークに通知する取引データ）を取り出します。

まず、変数objの構成です。dealsプロパティの中身は配列であり、条件に合致する取引の数だけ、オブジェクトが並んでいます。（1取引＝1オブジェクト）

取引が3件の場合、dealsプロパティに3つのオブジェクトが並びます。

    {
      "deals":[
        {
          //取引1件目=要素番号[0]
        },
        {
          //取引2件目=要素番号[1]
        },
        {
          //取引3件目=要素番号[2]
        }
      ],
      "meta":{
        "total_count":3
      }
    }

変数objから、取引1件目のオブジェクトを取得してみます。ポイントは2つです。

• dealsプロパティの中身は配列である
• 配列の要素数は0から始まる

よって、1件目の取引を取得する場合は、配列の要素番号[0]を指定します。

Logger.log(obj.deals[0]);

出力結果です（オブジェクトでは、プロパティの並び順は不定です）

{ref_number=, amount=86400, partner_id=18092592, company_id=xxxxxxx, issue_date=2019-07-01, due_amount=86400, due_date=2019-08-15, details=[{tax_code=101, tag_ids=[], amount=86400, section_id=null, item_id=165676671, account_item_id=296536450, vat=6400, description=, id=1125122564, tax_id=146197682, entry_side=credit}], id=432070388, partner_code=null, type=income, status=unsettled}

それでは、変数objから、取引1件目の2項目を取り出す処理を書いてみます。

1. 金額
2. 勘定科目ID

（※コメントアウトで ★ を付与している行です。）

    {
      "deals":[
        {
          "id":432070388,
          "company_id":xxxxxxx,
          "issue_date":"2019-07-01",
          "due_date":"2019-08-15",
          "amount":86400, //★金額
          "due_amount":86400,
          "type":"income",
          "partner_id":18092592,
          "partner_code":null,
          "ref_number":"",
          "status":"unsettled",
          "details":[
            {
              "id":1125122564,
              "account_item_id":296536450, //★勘定科目ID
              "tax_id":146197682,
              "tax_code":101,
              "item_id":165676671,
              "section_id":null,
              "tag_ids":[],
              "amount":86400,
              "vat":6400,
              "description":"",
              "entry_side":"credit"
            }
          ]
        },
        {
          //（省略）取引2件目
        },
        {
          //（省略）取引3件目
        }
      ],
      "meta":{
        "total_count":3
      }
    }

まず、取引1件目の金額を取り出します。「dealsプロパティ（配列）」→「amountプロパティ」の順にアクセスします。

Logger.log(obj.deals[0].amount); //86400

続いて、取引1件目の勘定科目IDを取り出します。「dealsプロパティ（配列）」→「detailsプロパティ（配列）」→「account_item_idプロパティ」の順にアクセスします。

Logger.log(obj.deals[0].details[0].account_item_id); //2.9653645E8

※ログ出力をすると小数点表示になってしまいますが、スプレッドシートに出力すれば問題ないです。

「detailsプロパティ」も配列形式であり、1件の取引に複数明細が存在する場合、明細の数だけオブジェクトが並びます。1取引1明細のみの場合も配列形式なので、要素番号の指定が必要です。

detailsプロパティの値については、複数明細をすべて取得する処理を作るとややこしくなってしまうので、このツールでは、要素番号[0]で「最初の1明細」のみを取得することにします。

まとめ・次回予告

「当日入金予定の取引一覧を自動でチャットワークに送信する」シリーズの第4回目では、これらを紹介しました。

• freeeAPIからのレスポンス（文字列）をオブジェクトに変換する方法
  • JSONオブジェクトのparseメソッドを使用する。文字列よりもオブジェクトの方がGASで扱いやすくなる
• ドット記法でオブジェクトから値を取り出す方法
  • プロパティ名をドット(.)で指定する。複数プロパティをつなげることが可能
  • プロパティが配列形式の場合、要素番号も指定する

次回は、オブジェクトから取り出した値をスプレッドシートに書き出す処理を作成します。

【GAS×freeeAPI】オブジェクトからデータを取り出してスプレッドシートに書き出す

「当日入金予定の取引一覧を自動でチャットワークに送信する」シリーズの第5回目。キーと値がペアになった「オブジェクト」から必要な値のみを取り出して「配列」に格納し、スプレッドシートに書き出す方法を紹介しています。

tonari-it.com

2019.09.26

連載目次：【GAS×freeeAPI】当日入金予定の取引一覧を自動でチャットワークに送信する

「クラウド会計ソフトfreee」のAPIをGASで操作して経理業務を自動化するシリーズ。「当日入金予定の取引一覧を自動でチャットワークに送信するツール」の作成を目標とします。

1. ノンプログラミングでOK！「会計freee連携アドオン」でスプレッドシートにデータを取得する
2. 【GAS×freeeAPI】指定条件の取引一覧を取得する「リクエストURL」の作り方と仕組み
3. 【GAS×freeeAPI】GETリクエストで当日入金予定の取引一覧を取得する
4. 【GAS×freeeAPI】APIリクエストのレスポンスから必要データのみを取り出す
5. 【GAS×freeeAPI】オブジェクトからデータを取り出してスプレッドシートに書き出す
6. 【GAS×freeeAPI】スプレッドシートのデータからチャットワーク通知用の本文を作成する
7. 【GAS×freeeAPI】当日入金予定の取引一覧を毎日自動でチャットワークに送信する