kintone REST API について (共通事項編)

はじめに

前回の記事 の続きです。

▼ 連載記事一覧

	タイトル
0	kintone環境の取得方法 (開発者ライセンス)
1	kintoneの使い方 (データベース編)
2	kintone REST API について (共通事項編) ← 本記事
3	kintone REST API について (GET編)
4	kintone REST API について (POST編)

今回はREST APIを使って、kintoneのデータを扱うための共通事項の説明をします！

共通事項

kintoneのデータを操作するためには、

• URI/URL
• メソッド
• ヘッダー (認証)
• リクエストパラメータ (GETの場合はURIに追記)

が必要になります。
これはkintoneだけでなく、いわゆる一般的なREST APIで必要な項目になります。

これらはすべて cybozu developer network (devnet) に細かく記述されるけど、
ただ、ページがわかれていたりと初心者には難しいかもなので、
さらりと全体の概要をここで説明します！

URI/URL

kintoneの何のデータを扱うか を示すものです。
例) レコードを1件操作したい / レコードを複数件操作したい / アプリ自体を操作したい

レコードを1件を操作する場合は、

https://(サブドメイン名).cybozu.com/k/v1/record.json

となります。他にも

// レコード複数件
https://(サブドメイン名).cybozu.com/k/v1/records.json

// アプリのフィーム情報
https://(サブドメイン名).cybozu.com/k/v1/app/form/fields.json

などあります！詳しくは上記のdevnetで！

サブドメイン

サブドメインとはURLにあるこの部分です！

メソッド

これは データをどうしたいか 示すものです。
kintoneでは以下の4種類用意しています！

GET / POST / PUT / DELETE
(取得 / 新規登録 / 更新 / 削除)

ヘッダー (認証)

認証 や リクエストパラメータで送るデータ形式 を示すものです。

kintoneでは

• ログインID/パスワード 認証
• APIトークン認証
• (セッション認証)

の3種類があります。
(セッション認証はブラウザのクッキーを利用するので暗黙的認証ですね)

ログインID/パスワード認証

Webブラウザでkintoneへログインする際の「ID」と「パスワード」を以下のようにbase64でエンコードしたものを利用します。

// ID/パスワードが demo/password の場合、「demo:password」をbase64でエンコードしたものを利用します
'X-Cybozu-Authorization: ZGVtbzpwYXNzd29yZA=='

APIトークン認証

アプリごとに発行できるトークンを使った認証です。
発行方法は、

トークンごとにどんな操作をさせるか制御させることもできます！
(使うメソッドに合わせてチェックをつけると良いですね！)

※ トークン発行後は必ずアプリの設定から更新をしてください！！

そしてAPIトークンを使った認証方法は、

'X-Cybozu-API-Token: 発行したAPIトークン'

と書きます。

また。GET以外のメソッドの場合、何かしらのデータを送るため、
その 送るデータの形式 を指定する必要があります。
データ形式については、ほとんどの場合 JSONを扱うと思うので、

'Content-Type: application/json'

で良いと思います！
※ GETの場合、URLにデータ(パラメータ)を載せるため必要ありません。

これらを組み合わせて、JSだと

let headers = {
  'Content-Type': 'application/json',
  'X-Cybozu-API-Token': 'hogehoge',
}

とかよく書きますね。これがヘッダー部分です。

リクエストパラメータ

扱いたいデータの具体的な部分 を示します。
よくURIと混同されますが、あっちはアバウトです！(レコード1件！レコード複数件！とか)

こちらはもっと具体的な部分で、
レコード1件の操作であれば「どのレコード1件」か指定する必要があり、
さらにはそもそも「どのアプリの？」も必要です。

現実世界でも一緒です！
「おにぎり買ってきて！」と言われても、
「どこで？」「何味？」となると思います。それと同じ

そしてこれは「使うURI、メソッドによって」変わってきます ← ここ大事！！

レコード1件を取得する場合、必要なパラメータは

• アプリID (どのアプリから？)
• レコードID (どのレコードを？)

となります。
アプリIDとレコードIDはレコードの詳細画面を開くとそれぞれURLに記載されています！

なので、この例だと

• アプリID → 126
• レコードID → 1

となります。JSだと

let params = {
  app: 126,
  record: 1,
}

とよく書きます。

おわりに

以上がkintone REST APIの共通事項でした。
コマンドラインやJS、Pythonなどいろいろな方法でREST APIを実行する場合でも
これらは基本必要です！

次は 実際にkintoneのデータを取得する部分を説明します！

連載記事一覧

	タイトル
0	kintone環境の取得方法 (開発者ライセンス)
1	kintoneの使い方 (データベース編)
2	kintone REST API について (共通事項編) ← 本記事
3	kintone REST API について (GET編)
4	kintone REST API について (POST編)

それでは！≧(+･` ཀ･´)≦