はじめに
kintoneとは
kintoneの活用方法
kintone環境を手に入れよう
kintoneアプリの作成
HTTPリクエストでデータの送受信
- データの取得方法
  - cURL
  - Python
  - Node.js
- データの登録方法
  - cURL
  - Python
  - Node.js
よくある質問(FAQ)
参考リンク

はじめに

この記事では、kintoneをハッカソンで使う方法を紹介します。ハッカソンの作品にWebデータベースが必要な場合、是非参考にしてください。無料で手に入れることが出来るkintone開発者ライセンスの取得方法についても案内します。

👍 ワンポイントアドバイス
この記事ではkintoneをバックエンドで使うことを想定として、外部システムからkintoneのデータの送受信をする方法を案内しています。kintoneをフロントエンドで使ってJavaScriptでカスタマイズをしいたい場合は、下記のチュートリアルを参考にして下さい：【Cybozu Developer Network】カスタマイズファイルを適用してみよう

👍 ワンポイントアドバイス

この記事ではkintoneをバックエンドで使うことを想定として、外部システムからkintoneのデータの送受信をする方法を案内しています。kintoneをフロントエンドで使ってJavaScriptでカスタマイズをしいたい場合は、下記のチュートリアルを参考にして下さい：
【Cybozu Developer Network】カスタマイズファイルを適用してみよう

kintoneとは

kintoneはWebデータベースをGUIで簡単に作成出来るクラウドサービスです。HTTPリクエストを使用することで、Webデータベースにデータを溜めたり、データを取得することが出来ます。

kintoneの活用方法

ハッカソンでの活用方法は色々とありますが、一番分かりやすい活用方法は『データを溜める箱』として扱うことです。

kintoneでは、Webデータベースをドラッグ＆ドロップで作成することが出来ます。データを溜めるための構造が直感的に理解しやすく、柔軟なサイズの箱を設計することが出来ます。このように作成されたWebデータベースは『kintoneアプリ』と呼びます。

一度作成されたkintoneアプリには手動でデータを追加したり、閲覧したり出来ます。また、kintoneアプリから認証用のAPIトークンを生成することにより、外部のプログラムからkintoneアプリへのデータの送受信が可能になります*1。

例として、ハッカソンでゲームの作品を作った場合、その作品と連動するゲームのスコアを管理するアプリをkintoneで作成できます。APIトークンを利用することにより、ゲームで新しいスコアが出た時にkintoneアプリに情報を登録したり、スコアのランキングをkintoneアプリから取得し、ゲーム内で表示することが出来ます。

この記事ではゲームスコアを溜めるkintoneアプリを例にして話を進めます。

kintone環境を手に入れよう

エンジニアは、kintone開発者ライセンスという名の、無料のkintone環境を入手することが出来ます。以下のページの注意書きを良く読んでから、『開発者ライセンスを申し込む』ボタンをクリックしてください。 cybozu.dev

フォームに必要事項を入力すれば、メールでkintone開発者ライセンスの環境情報が手に入ります。*2

kintoneアプリの作成

まずはじめに

kintone開発者ライセンスを取得したら、その環境内でWebデータベースの作成が出来ます。ヘルプページを参考に、アプリを作成しはじめてみましょう。

アプリの準備

アプリの項目はドラッグ＆ドロップで自由に組み合わせることができます。この記事では、ゲームスコアを管理するアプリを例に解説を進めます。まずは下記の様なゲームスコアを管理する項目を設定しておきます。

フィールド項目	フィールド名	フィールドコード
文字列(一行)	名前	name
数値	スコア	score
ラジオボタン	難易度	difficulty

アプリ作成時に、フォームのタブを選択することで、これらのフィールドの設定が出来ます。

APIトークンの準備

kintoneアプリから認証用のAPIトークンを生成することが出来ます。このAPIトークンは、生成元のアプリに対してのみ使用できます。また、APIトークンにアクセス権限を設定することによって、APIトークンで実行出来るメソッド(閲覧・追加・更新など)を制限することが出来ます。

ヘルプページを参考に、作成したkintoneアプリからAPIトークンを発行出来ます。

APIトークンを持っていると、誰でも外部プログラムからkintoneアプリにアクセスすることが出来るので、大事に保管してください。誤ってGitHubなどのオープンの場に公開してしまった場合は、一度kintoneアプリの設定でAPIトークンを削除し、新しいAPIトークンを生成して使用してください。

HTTPリクエストでデータの送受信

データの取得方法

kintoneの複数のレコードを取得するAPIを使うことにより、kintoneアプリからレコード情報を一度に500件まで取得することが出来ます。このセクションでは、様々なプログラムから、レコード取得用のHTTPリクエストをする方法を案内します。リクエストの例として、kintoneで作ったゲームスコアのランキングアプリから、下記の条件に合うレコードを取得します：

kintoneアプリが入っている環境が『https://sample.cybozu.com』
スコアが『5000以上』で、難易度が『Medium』
スコアのフィールドコードが『score』、難易度のフィールドコードが『difficulty』
アプリのIDが『239』
APIトークンが『00pXoSDFpogj3409GGGd340003gDSF43tQQzA』

cURL

クエリを指定する部分はURLエンコードする必要があります。

curl -X GET 'https://sample.cybozu.com/k/v1/records.json?app=239&query=score%20%3E%3D%20%225000%22%20and%20difficulty%20in%20%28%22Medium%22%29' \
  -H 'X-Cybozu-API-Token: 00pXoSDFpogj3409GGGd340003gDSF43tQQzA'

Python

この例では、requests モジュールでHTTPリクエストを実現しています。
pip install requests などで、requestsモジュールをインストールして下さい。

import requests

def get_all_records():
    API_endpoint = "https://sample.cybozu.com/k/v1/records.json"
    app_id = "239"
    query = "score >= \"5000\" and difficulty in (\"Medium\")"
    API_endpoint = API_endpoint + "?app=" + app_id + "&query=" + query

    kintone_headers = {
        "X-Cybozu-API-Token": "00pXoSDFpogj3409GGGd340003gDSF43tQQzA",
    }

    try:
        response = requests.get(API_endpoint, headers=kintone_headers)
        jsondata = response.json()
        print(jsondata)

    except requests.exceptions.RequestException as error:
        print(error)

get_all_records()

Node.js

この例では、axios ライブラリでHTTPリクエストを実現しています。 npm install axios などで、axiosライブラリをインストールして下さい。

const axios = require("axios");

async function get_all_records() {
  const API_endpoint = "https://sample.cybozu.com/k/v1/records.json";
  const app_Id = "239";
  const query = "score >= \"5000\" and difficulty in (\"Medium\")";
  const parameters = "?app=" + app_Id + "&query=" + query;
  
  const headers = {
    "X-Cybozu-API-Token": "00pXoSDFpogj3409GGGd340003gDSF43tQQzA"
  };

  try {
    const response = await axios.get(API_endpoint + parameters, { headers });
    const records = response.data.records;
    console.log(records);
  } catch (error) {
    console.error(error);
  }
}

get_all_records();

データの登録方法

kintoneの1 件のレコードを登録するAPIを使うことにより、kintoneアプリにレコードを1件登録することが出来ます。このセクションでは、様々なプログラムから、レコード登録用のHTTPリクエストをする方法を案内します。リクエストの例として、kintoneで作ったゲームスコアのランキングアプリに、下記の情報を含めたレコードを登録します：

kintoneアプリが入っている環境が『https://sample.cybozu.com』
名前が『ギョウザドン』、スコアが『12000』、難易度が『Hard』
名前のフィールドコードが『name』、スコアのフィールドコードが『score』、難易度のフィールドコードが『difficulty』
アプリのIDが『239』
APIトークンが『00pXoSDFpogj3409GGGd340003gDSF43tQQzA』

cURL

curl -X POST 'https://sample.cybozu.com/k/v1/record.json' \
  -H 'X-Cybozu-API-Token: 00pXoSDFpogj3409GGGd340003gDSF43tQQzA' \
  -H 'Content-Type: application/json' \
  -d '{
    "app": "239",
    "record": {
        "name": {
            "value": "ギョウザドン"
        },
        "score": {
            "value": "12000"
        },
        "difficulty": {
            "value": "Hard"
        }
    }
  }'

Python

この例では、requests モジュールでHTTPリクエストを実現しています。
pip install requests などで、requestsモジュールをインストールして下さい。

import requests
import json

def add_record():
    API_endpoint = "https://sample.cybozu.com/k/v1/record.json"
    app_id = "239"

    kintone_headers = {
        "X-Cybozu-API-Token": "00pXoSDFpogj3409GGGd340003gDSF43tQQzA",
        "Content-Type": "application/json"
    }

    bodydata = {
        "app": app_id,
        "record": {
            "name": {
                "value": "ギョウザドン"
            },
            "score": {
                "value": "12000"
            },
            "difficulty": {
                "value": "Hard"
            }
        }
    }

    try:
        response = requests.post(API_endpoint, headers=kintone_headers, data=json.dumps(bodydata))
        jsondata = response.json()
        print(jsondata)

    except requests.exceptions.RequestException as error:
        print(error)

add_record()

Node.js

この例では、axios ライブラリでHTTPリクエストを実現しています。 npm install axios などで、axiosライブラリをインストールして下さい。

const axios = require("axios");

async function addRecord() {
  const API_endpoint = "https://sample.cybozu.com/k/v1/record.json";
  const appId = "239";

  const headers = {
    "X-Cybozu-API-Token": "00pXoSDFpogj3409GGGd340003gDSF43tQQzA",
    "Content-Type": "application/json"
  };

  const  data = {
            app: appId,
            record: {
                name: {
                    value: "ギョウザドン"
                },
                score: {
                    value: "12000"
                },
                difficulty: {
                    value: "Hard"
                }
            }
        }

  try {
    const response = await axios.post(API_endpoint, data, { headers });
    console.log(response.data);
  } catch (error) {
    console.error(error.response.data);
  }
}

addRecord();

よくある質問(FAQ)

Q: ReactやVue.jsといった、Webのフロントからkintoneアプリとのデータの送受信がしたいです
A: フロントからHTTPリクエストをした場合、CORSエラー*3が出てしまい、リクエストが失敗します。バックエンドからリクエストする場合はこのエラーが回避出来ます。自分でバックエンドを準備して、フロントからはこのバックエンドにリクエストをし、そのバックエンドからkintoneにリクエストをしましょう。

Q. kintoneのCORS ポリシーを削除したいです
A. セキュリティの観点から、削除出来ないように設計されています。

Q. kintoneにHTTPリクエストをしたさいに、『不正なJSON文字列です』というエラーが返ってきます
A. JSONの形が正しくありません。ネット上に、JSONの形をチェックしてくれるツールが多くあるので、自分が作成したJSONをそこにコピペをしてチェックしてもらいましょう。括弧の数が正しいこと、カンマの位置が正しいこと、ダブルクオーテーションが使用されていること*4を確認しましょう。

Q: ハッカソンのチームでkintoneを使ってみたいです
A: チーム内で代表を1人決めて、その人にkintoneの開発者ライセンスを取得してもらってください。代表が環境にログインした後に、その環境にアクセス出来るメンバーのアカウントを追加出来ます。開発者ライセンスの場合は5名までアカウントを追加することができます。

参考リンク

リンク	詳細
1 件のレコードを取得するAPI	アプリのIDとレコードのIDを指定して、レコードの情報を取得します。
複数のレコードを取得する	アプリのIDと検索クエリを指定して、複数のレコードを取得します。
1件のレコードを登録するAPI	アプリIDと登録データを指定して、1件のレコードを登録します。
複数のレコードを登録するAPI	アプリIDと複数の登録データを指定して、複数のレコードを登録します。

*1:APIトークン以外の認証方法も存在します。詳しくは、Cybozu Developer Networkの認証の記事をご確認下さい。

*2:15分から30分程度かかる場合があります

*3:Cross-Origin Resource Sharingに関するエラー。詳しくはmdn web docsの記事を読んで下さい

*4:ダブルクオーテーションを使用しなくても、そのJSON許容するライブラリも存在します

kintoneGeeks blog

kintoneに関連する情報を発信しています

ハッカソンでkintoneを使う方法

はじめに

kintoneとは

kintoneの活用方法

kintone環境を手に入れよう

kintoneアプリの作成

まずはじめに

アプリの準備

APIトークンの準備

HTTPリクエストでデータの送受信

データの取得方法

cURL

Python

Node.js

データの登録方法

cURL

Python

Node.js

よくある質問(FAQ)

参考リンク