kintone API のクエリの書き方の基本

Index

• はじめに
• アプリの準備
• クエリの書き方
• クエリに変数を代入する
• おわりに

はじめに

今回は、クエリの書き方の基本について紹介したいと思います。
クエリを使用すると、ある条件で絞り込んだ特定のレコードを取得することができます。
クエリの書き方がよりわかりやすいように、アプリを用いながら紹介してきたいと思います。
もちろんアプリを使用しなくても、クエリの書き方のみを参考にすることも可能ですので、
ぜひ開発に役立てていただければと思います。

アプリの準備

アプリストアから「問い合わせ管理」を追加します。（参考：アプリストアからアプリを追加する）
アプリを作成する際には「サンプルデータを含める」にチェックを入れてください。

また、アプリの設定画面から以下のようにフィールドコードを変更してください。

フィールド名	フィールドコード
対応日時	ResponseDate
対応内容	Correspondence

クエリの書き方

式の形式について

クエリは、主に以下の形式にそって式を書いていきます。

<フィールドコード> <演算子> <値 または 関数>

より詳しいクエリの仕様や、フィールドごとに使える演算子・関数については「クエリの書き方」をご覧ください。
では、実際にレコードを取得してみましょう。JavaScript でクエリを指定してレコードを取得するサンプルは、この記事の最後で紹介しています。

文字列（1行）の値を指定する

以下の条件を指定して、実際にレコードを取得してみましょう。

• 「顧客名」フィールドの値が「山田商事株式会社」(完全一致)
  文字列を完全一致で指定する際は、以下のように「=」演算子を使用します。

  Customer = "山田商事株式会社"

• 「顧客名」フィールドの値に「株式会社」を含む（部分一致）
  文字列を部分一致で指定する際は、以下のように 「like」演算子 を使用します。

  Customer like "株式会社"

ドロップダウンの値を指定する

以下の条件を指定して、実際にレコードを取得してみましょう。
ドロップダウンフィールドの値を指定する際は、以下のように 「in」、「not in」演算子 を使用します。
「in」、「not in」演算子を使用する際には、値を ( ) で囲う必要があります。

• 「対応状況」フィールドの値に「対応中」または「未対応」を含む
  

  Status in ("対応中","未対応")

• 「対応状況」フィールドの値に「完了」を含まない

  Status not in ("完了")

また、以下のフィールドは、ドロップダウンと同じように、「in」、「not in」演算子を使用してレコードを取得することができます。

• チェックボックス
• ラジオボタン
• 複数選択

日付フィールドの値を指定する

以下の条件を指定して、実際にレコードを取得してみましょう。

• 「期限」フィールドの値が「2018-02-01」

  LimitDay = "2018-02-01"

日付フィールドでは、一致するもの以外にも範囲を指定して絞り込みを行うことができます。
以下の条件を指定して、実際にレコードを取得してみましょう。

• 「期限」フィールドの値が「2018-02-01」から「2018-03-01」まで

   LimitDay >= "2018-02-01" and LimitDay <= "2018-03-01"

このように、複数の条件を指定する際には「and」演算子 を使って式をつなげていきます。

テーブル内のフィールドの値を取得する

テーブル内のフィールドを取得する際には「=」、「!=」演算子が使えません。
その代わりに「in」、「not in」演算子を使う必要があります。

実際に、以下の条件でフィールドを取得してみましょう。

• 「対応日時」フィールドの値が「2018-01-05 14:00」

  ResponseDate in ("2018-01-05T05:00:00Z")

「日付フィールドの値を指定する」で紹介したように、通常は日付フィールドや日時フィールドに対しては「=」、「!=」演算子を使用します。しかし、テーブル内では使用できなくなってしまうので注意が必要です。

ここまでは、フィールド単体を指定したクエリを紹介しました。次は、複数のフィールドを指定する方法について紹介します。

複数のフィールドや条件の指定

「日付フィールドの値を指定する」の最後にも指定しましたが、「and」、「or」演算子 を使って複数の条件を指定することができます。

まずは、「and」演算子 を使用して複数のフィールドの条件をクエリで指定してみましょう。

「and」を使用した条件の指定

• 「期限」フィールドの値が「今日」より前
• 「対応状況」フィールドの値に「完了」を含まない

  LimitDay < TODAY() and Status not in ("完了")

「期限」フィールドの条件に 「TODAY()」関数を指定しました。「TODAY()」関数 というのは、クエリで使える関数のひとつです。
関数を使用すれば、いちいち日付を指定しなくても、「今日」「先週」や「来週」といった条件を簡単に指定することができます。
（他の関数は「クエリの書き方 > 関数」を参照ください。）

「order by」を使用した条件の指定

続いて、先ほどの条件にもうひとつ条件を追加してみましょう。

• 「期限」フィールドの値が「今日」より前
• 「対応状況」フィールドの値に「完了」が含まれない
• 「期限」フィールドの値の「昇順」で取得する

   LimitDay < TODAY() and Status not in ("完了") order by LimitDay asc

このように、 「order by 」オプションを使うことで、レコードの出力される順番をソートすることができます。

式のグループ化

複数のフィールドに対して複数の条件を指定する際には、式をグループしましょう。
式を丸括弧「()」で囲うことで、グループ化することができます。
グループ化を行うことにより、より詳細な条件を指定することができます。

• 「問い合わせ種別」フィールドの値が「その他」
  または
• 「期限」フィールドの値が「2018-02-01」から「2018-03-01」まで

   (QType in ("その他")) or (LimitDay >= "2018-02-01" and LimitDay <= "2018-03-01")

クエリに変数を代入する

最後に変数を代入する方法について紹介したいと思います。
実際にJavaScriptを使用してクエリを書く際には、クエリ内に変数を含めるケースがあるかと思います。
例えば、レコードから取得した値をクエリに代入したりするケースです。
こういった動的な値を使用してクエリを書くためには文字列を変数を分けて考える必要があります。

以下のようなケースを想定して考えてみましょう。

• レコードを開いたときに、「期限日」の値が同じ他のレコードを取得したいとき

上記の条件を実装するには、

1. 開いているレコードの値を取得する
2. 取得した値をクエリに代入する

といった順番で処理が必要となります。実際に、コードをみていきましょう。

ポイント

上のコードの7行目がポイントです。

レコード取得の条件であるクエリには、レコード内の「期限」フィールドの値を代入しています。
このように、JavsScript 内の変数をクエリに代入するためには、文字列として結合する必要があります。

おわりに

クエリの書き方は、一度コツを掴めたら簡単に書くことができるようになります。
今回は書き方についての紹介をしましたが、簡単にクエリを作ることができる便利な方法もあります。

• レコード一括取得APIのクエリを簡単に作りたい

クエリは、組み合わせることによって様々なデータを取得することができ、実際の開発で利用することも多いです。
クエリを活用して、これからも kintone をより便利にカスタマイズしていただければと思います。