カテゴリー内の他の記事

kintone REST APIの共通仕様

作成日2014年05月08日 07:21
更新日2021年08月02日 00:34

Index

kintone REST APIの概要
ユーザー認証
Basic認証
リクエストヘッダ
レスポンス
注意事項
制限事項
関連Tips

kintone REST APIの概要

kintone アプリのレコードの操作やフォーム設計情報の取得、スペースを操作することができます。

プロトコル

HTTPS

フォーマット

JSON

文字コード

UTF-8

エスケープ文字

「\」を使用します。

日時のフォーマット

日付、時刻、日時フィールド（作成日時、更新日時フィールドも含む）のデータを扱う場合、それぞれ以下のフォーマットの文字列で指定する必要があります。

フィールドタイプ	フォーマット	説明
日付	YYYY-MM-DD	UTCに変換されません。以下のような形式の入力を受け付けます。 * 2015 * 2015-07 * 2015-7 * 2015-7-5 月日を省略した場合は01で補完されます。 * 2015 -> 2015-01-01 * 2015-07 -> 2015-07-01 * 2015-7 -> 2015-07-01 * 2015-7-5 -> 2015-07-05
時刻	HH:MM	UTCに変換されません。
日時	取得時 YYYY-MM-DDTHH:MM:SSZ	「YYYY-MM-DD」と「HH:MM:SS」の間の「T」は固定値です。「HH:MM:SS」の後ろの「Z」は固定値です。取得時の「Z」はUTCを表します。一覧の取得APIでは日時はUTCで出力されます。日本時間（JST）の2012年3月22日14時00分は次のように表せます。例）「2012-03-22T05:00:00Z」「T」以降を省略した場合、UTCとして扱われます。
日時	登録・更新時 YYYY-MM-DDTHH:MM:SS±HH:MM または YYYY-MM-DDTHH:MM:SSZ	「YYYY-MM-DD」と「HH:MM:SS」の間の「T」は固定値です。「HH:MM:SS」の後ろの「Z」は固定値です。登録・更新時の「±HH:MM」には、UTCとの時刻の差を指定します。日本時間（JST）の2012年3月22日14時17分は次のように表せます。例1）「2012-03-22T14:17:00+09:00」例2）「2012-03-22T05:17:00Z」「T」以降を省略した場合、UTCとして扱われます。秒情報を指定して登録または更新を行った場合、秒情報は無視されます。例)「2019-02-06T12:59:59Z」と指定すると、「2019-02-06T12:59:00Z」として登録または更新されます。

ユーザー認証

APIを実行するリクエストには、認証のためのヘッダを追加する必要があります。

パスワード認証

リクエストヘッダに「X-Cybozu-Authorization」を追加し、「ログイン名:パスワード」をBASE64エンコードしたものを値に指定します。

// ログイン名が「Administrator」、パスワードが「cybozu」の場合
  X-Cybozu-Authorization:QWRtaW5pc3RyYXRvcjpjeWJvenU=

セキュアアクセス設定環境にログインしたユーザーが、ログインユーザーと異なるユーザーの認証情報を使って JavaScript カスタマイズでの REST API を実行する場合、設定が必要です。
利用するには「.com 共通管理」より「証明書のユーザーとパスワード認証のユーザーが異なるアクセスを許可する」を有効にしてください。
2要素認証を設定したcybozu.com ユーザーアカウントでは、パスワード認証でREST APIを利用できません。

APIトークン認証

アプリごとに生成するAPIトークンを使用して、kintone REST APIを処理できます。 APIトークンを生成する方法は、こちらをご確認ください。

リクエストヘッダに「X-Cybozu-API-Token」を追加し、アプリごとに生成するAPIトークンを値に指定します。

// APIトークンが「BuBNIwbRRaUvr33nWXcfUZ5VhaFsJxN0xH4NPN92」の場合
  X-Cybozu-API-Token:BuBNIwbRRaUvr33nWXcfUZ5VhaFsJxN0xH4NPN92

複数のAPI トークンを指定できます。複数トークンはカンマ区切りまたは別ヘッダーで指定します。
参考Tips：複数 API トークンを使ってできること
```
// API トークンを複数指定（カンマ区切り）する
// API トークンが「BuBNIwbRRaUvr33nWXcfUZ5VhaFsJxN0xH4NPN92」「YuLjjdiOECJjV5ZDbFwh5BZoJJGDx3LtdCE1Dl7E」の場合
  X-Cybozu-API-Token:BuBNIwbRRaUvr33nWXcfUZ5VhaFsJxN0xH4NPN92, YuLjjdiOECJjV5ZDbFwh5BZoJJGDx3LtdCE1Dl7E
```
- 一回のリクエストで指定できる API トークンは9個までです。10個以上指定するとエラーになります。
生成できるトークンは、アプリ1つにつき20個までです。
APIトークンを使用した操作は、Administratorによる操作として記録されます。
リクエストヘッダに「X-Cybozu-Authorization」を指定していると、その認証が優先されます。
APIトークンは、アプリを操作する次のkintone REST APIで使用できます。
- レコード
  - レコードの取得（GET）／レコードの登録（POST）／レコードの更新（PUT）／レコードの削除（DELETE）
    ルックアップフィールドの値を登録／更新する場合は、こちらの記事をご参照ください。
  - レコードの一括取得
  - レコードコメントの投稿／レコードコメントの削除
  - レコードの作業者の更新
  - レコードのステータスの更新
  - 複数アプリへのレコード一括処理
- ファイル
  - ファイルアップロード／ファイルダウンロード
- アプリ
セキュアアクセス設定時、有効なクライアント証明書が使用されている場合のみAPIトークン認証を利用できます。
組織間のアクセス権の設定を有効にすると、APIトークンを生成/閲覧できるのはkintoneシステム管理者のみになります。

セッション認証

セッション認証とは、Webサーバから付与されたセッションIDをCookieに保存する事でユーザを識別する認証方法です。

認証時の優先順位について

優先順位は以下の通りです。

パスワード認証
APIトークン認証
セッション認証

ゲストユーザがAPIを実行する場合はセッション認証のみ利用できます。パスワード認証は利用できません。

OAuthクライアントを使用して認証することも出来ます。詳細はこちらを参照してください。

SAML認証設定時の利用について

SAML認証設定時に、パスワード認証、APIトークン認証、セッション認証、OAuthクライアントを使用した認証でkintone REST APIを利用できます。
パスワード認証ではcybozu.comのログイン名とパスワードを利用する必要があります。
cybozu.com のログイン時に SAML 認証のみを使うように制限している場合、パスワード認証による kintone REST API の実行がcybozu.com共通管理者のみに制限されます。APIトークン認証、セッション認証、OAuthクライアントを使用した認証の場合、この制限を受けません。

Basic認証

cybozu.com でBasic認証を利用している場合は、更にリクエストヘッダに「Authorization」ヘッダを追加し、「Basic 」と「ログイン名:パスワード」をBASE64エンコードしたものを値に指定します。
- 「Basic」と「ログイン名:パスワード」の間は、半角空白が必要です。
- 「Basic 」の BASE64エンコードは不要です。
ゲストスペース内のアプリは対象外です。

// ログイン名が「Administrator」、パスワードが「cybozu」の場合
  Authorization:Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=

リクエストヘッダ

送信するリクエストに応じて以下のリクエストヘッダを指定します。

※kintone.api() を利用する場合、リクエストヘッダの指定は不要です。

ヘッダー名

内容

Host

サブドメイン名.cybozu.com:443

Content-Type

application/json

※リクエストボディにJSON文字列を格納する場合のみ指定します。

X-HTTP-Method-Override

HTTPメソッド(GET, POST, PUT, DELETE)

X-HTTP-Method-OverrideにHTTPメソッドを指定してPOSTリクエストを送信すると、指定したHTTPメソッドに対応するAPIが実行されます。

X-HTTP-Method-OverrideヘッダはPOSTリクエストの時のみ有効になります。
X-HTTP-Method-Overrideを使ったAPI呼び出しは全てのkintone REST APIで利用できます。
X-HTTP-Method-Overrideに指定するHTTPメソッド名は大文字のみ使用可能です。

※リクエストURIが8KBを超えると発生するエラー(Request URI Too Large)を回避する目的で使用します。
※kintone.api()でURIの長さが4KBを超えるGETリクエストが送信された場合、X-HTTP-Method-Overrideヘッダが自動的に付与され、
POSTリクエストとして送信されます。
※kintone.proxy()については動作保証外となります。

以下のリクエストを送信した場合、レコード一括取得APIが実行されます。

リクエストヘッダ

POST /k/v1/records.json
Host: example.cybozu.com:443
X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=
Content-Type: application/json
X-HTTP-Method-Override: GET

リクエストボディ

{
      "app":"8",
      "query":"更新日時 > \"2012-02-03T09:00:00Z\" and 更新日時 < \"2012-02-03T10:00:00Z\""
}

リクエストURI

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

ゲストスペース内のアプリの場合

https://(サブドメイン名).cybozu.com/k/guest/(スペースのID)/v1/(コマンド名).json

「コマンド名」は、APIの種類ごとに異なります。
「v1」は固定値です。

レスポンス

HTTPステータスコードが「200」であれば正常終了、それ以外はエラー終了です。エラー時には下記情報を含むJSONデータをレスポンスとして受け取ります。

Key	Value
message	エラーメッセージが表示されます。ユーザーの言語によって異なります。
id	エラーIDです。問い合わせの際に利用します。
code	エラーの種類を表すコードです。

すべてのkintone REST APIのレスポンスヘッダには、次の情報が含まれています。

Key

Value

X-ConcurrencyLimit-Limit

同時接続数の上限値

固定値の100です。

X-ConcurrencyLimit-Running

現在の同時接続数

 X-ConcurrencyLimit-Limit:  100
 X-ConcurrencyLimit-Running:  2

kintone.api()でリクエストした場合のレスポンスについて

kintone.api()でkintone REST APIをリクエストした際、コールバックに渡される情報はレスポンスボディのみです。
そのため、レスポンスボディ以外の情報を利用する場合はkintone.api()以外でリクエストする必要があります。

注意事項

リクエストデータ、およびレスポンスデータのJSONフォーマットには、今後フィールドやキーなどが追加される場合があります。
アプリ、レコード、コメント、スペースなどの操作による監査ログは、「監査ログの一覧」をご確認ください。
次のAPIはリクエスト数にカウントされません。
- ファイルのダウンロード
- ファイルのアップロード
- スペース情報の取得
- スペースの作成
- スペースの本文の更新
- スペースのスレッドの更新
- スペースのスレッドへの投稿
- スペースのメンバーの取得
- スペースのメンバーの更新
- ゲストスペースのゲストメンバーの更新
- ゲストユーザーの一括追加
- ゲストユーザーの一括削除
- スペースの削除
- API一覧の取得
- API スキーマ情報の取得
IPアドレス制限を行っている環境に対するREST APIリクエストについては、次のAPIリクエストがアクセス可能です。
- アクセス許可されたIPアドレスがアクセス元となるAPIリクエスト
- アクセス許可されたクライアント証明書を利用したAPIリクエスト

制限事項

ドメインへの同時接続

APIによる同時接続数はドメインごとに100が上限です。

アプリのレコード操作API

一度に取得できるレコードは500件までです。
レコードの一括取得（クエリで条件を指定）のoffset の上限値は1万件です。
一度に登録、更新、および削除できるレコードは100件までです。
1つのテーブルに登録できる行数の上限値は5,000行までです。
レコード取得、登録、更新において、存在しないフィールドコードを指定した場合は、そのフィールドコードへの処理は無視されます。
次のフィールドは、レコードの取得 APIによって値の取得のみできます。レコードの登録API及びレコードの更新APIで値の登録と更新はできません。
- ルックアップフィールドによって値が入力されるフィールド
- カテゴリー
- 計算
- ステータス (更新は、レコードのステータスの更新 API をご利用ください。)
- 作業者（更新は、レコードの作業者の更新API をご利用ください。）
レコード登録、更新において、ルックアップフィールドの値を変更する場合、ルックアップフィールドの「コピー元のフィールド」はレコード番号または「値の重複を禁止する」に設定されている必要があります。
ルックアップフィールドの「コピー元のフィールド」に自動計算の設定をしている「文字列1行」フィールドを選択している場合、ルックアップフィールドの値は変更できません。

ファイルのアップロードAPI

アップロードされたファイルは、レコード登録 API やレコード更新 API によってレコードに添付しない場合には、3日間で削除されます。保管されたファイルも、ディスク使用量に含まれます。

アプリのレコードコメントAPI

一度に取得できるレコードのコメントは10件までです。

その他の制限事項

その他、サービスに関する制限事項は、こちらをご確認ください。

記事に関するフィードバック

記事のコメント欄は記事に対するフィードバックをする場となっております。
右の記事フィードバックのためのガイドを参照してコメントしてください。
記事のリンク切れなど、気になる点がある場合も、こちらのフォームからフィードバックいただけますと幸いです。

Shigeru SAWADA 2016年02月26日 05:37

REST APIエラー時のレスポンスのcode(エラーコードの種類)について、公開はないのでしょうか？
一般的なものだけでも公開していただけるとありがたいのですが。
具体的には、同時アクセスによるエラーコードが"GAIA_RE18"で返って来ているようなので、
この場合個別にハンドリングしてリトライさせたいのですが、
公式で公開していただけると安心してハンドリングロジックを入れられるので。

dylan 2016年04月01日 09:32

試用版を利用しているところ、REST　APIの呼び出しが失敗しました。
試用版でREST APIの利用が可能でしょうか。
curl -H "X-Cybozu-API-Token: (作成したAPIトークン)" "https://(サブドメイン名).cybozu.com/k/v1/record.json?app=9&id=1"
で試しましたが、、認証が通らないようです。

HTTP 520のレスポンスメッセージ
{"message":"ログインしてください。","id":"1505999166-787662019","code":"CB_AU01"}

cybozu development team 2016年04月12日 00:25

Shigeru SAWADAさん
cybozu.com developer network事務局です。
残念ながら今のところ公開予定はありません。
ただ、要望は多い所ではあるので将来的に検討していきたいと思います。

cybozu development team 2016年04月12日 00:25

Shigeru SAWADA
cybozu.com developer network事務局です。
恐らくなにかパラメータが間違っているはずです…認証キーの設定等を見返してみてください。

Shigeru SAWADA 2016年04月18日 07:30

cybozu.com developer network事務局さま

回答ありがとうございました。
是非とも将来的に検討のほどよろしくお願いします。

miriorg 2016年08月04日 09:22

アプリの一覧を取得するAPIは存在しないのでしょうか?

hosyuta 2016年08月22日 02:23

＞Moriatsu Iri

アプリ情報取得APIの一括取得をすればよいかと。

https://cybozudev.zendesk.com/hc/ja/articles/202931674

flowers 2017年11月24日 05:59

API連携を検討しております。上限5,000行を超える場合の方法は何かありませんでしょうか。

cybozu Development team 2017年11月27日 07:34

iwasaki様

>1つのテーブルに登録できる行数の上限値は5,000行までです

についてのご相談でしょうか。

仕様外についてのご質問は、具体的に希望される動作を明記の上cybozu developer コミュニティに投稿ください。

suzuki 2018年04月18日 07:58

APIリクエスト数10,000件の制限があると思いますが、

それに関連して現在のAPIリクエスト数を取得するAPIはございますでしょうか。

cybozu Development team 2018年04月19日 06:58

suzuki 様

お世話になっております。developer network 運営チームです。

現在のAPIリクエスト数を取得するAPIはございません。
ご希望に添えず申し訳ございません。

なお、現在のAPIリクエスト数はアプリ管理画面にてご確認いただけます。
詳しくはこちらをご確認ください。

今後ともよろしくお願いいたします。

Yasuyuki Tanaka 2018年04月21日 15:22

プロセス管理に関するREST APIのページへのリンクが左部ツリーメニューより消えています。

APIの廃止や使用の非推奨が予定されているのでしょうか？

Yasuyuki Tanakaにより編集されました 2018年04月21日 15:23

cybozu Development team 2018年04月23日 00:26

田中　靖之様

お世話になっております。developer network 運営チームです。

大変申し訳ございません、メニュー表示に誤りがあったため修正いたしました。
プロセス管理のAPIにについて、廃止予定はございません。

ご指摘いただきましてありがとうございました。
今後ともよろしくお願いいたします。

Yasuyuki Tanaka 2018年04月23日 06:31

developer network 運営チーム様

ご回答ありがとうございました。

APIに変更がないとのことで安心しました。

今後ともよろしくお願いいたします。

Suzuki Suguru 2019年03月10日 04:42

お世話になります。

日時フィールドの初期値に

日付→2019-03-15

時刻→06:00 PM

とセットしたのですが、

REST APIでフォーム設定を取得し初期値を確認したところ

「2019-03-15T18:00:00.000Z」

となっておりました。

これをそのまま見ると

2019-03-16 03:00:00

が初期値にセットさせてしまうのではないかと思うのですが、

初期値には2019-03-15 06:00 PMがセットされています。

ミリ秒が記載されているかどうかで判断が分かれるということでしょうか？

cybozu Development team 2019年03月11日 05:37

Suzuki Suguru 様

お世話になっております。
developer network 運営チームです。

フォームの設定の取得API（/k/v1/app/form/fields.json）で取得できる日時フィールドの初期値には、タイムゾーンはなく、ユーザーが設定した値そのものが入ります。

・ご確認いただいたように、画面で「2019-03-15 18:00」と設定した場合の期待する挙動は、次のとおりです。
　　初期値: 2019-03-15 18:00
　　レコードを追加したときのフィールドの値：2019-03-15 18:00

一方で、現在defaultValue で返ってくる値に UTCを表すZがついており、今回の混乱のもとになっておりました。
初期値にはタイムゾーンがないので、本来であれば、「2019-03-15 18:00:00.000」などの、Zがない状態で返ってくるべきです。
この件については、社内に不具合として共有しております。

ご指摘いただきましてありがとうございました。
今後ともよろしくお願いいたします。

demachi 2019年06月24日 08:16

お世話になっております。

出町と申します。

ルックアップで取得し登録したデータを別アプリにコピーするのに、

「値の重複を禁止する」をオンにしました。

一つ確認ですが、サブテーブルに設定されているルックアップフィールドは、

「値の重複を禁止する」がオフのままでも別アプリにコピーされました。

これは制限事項の対象外ということなのでしょうか。

ご教示のほどよろしくお願いいたします。

cybozu Development team 2019年06月25日 09:19

出町望様

お世話になっております。cybozu developer network 運営チームです。

「値の重複を禁止する」設定が必要なのは、「関連付けるアプリ」の「コピー元のフィールド」に対してです。

「APIでレコードを登録するアプリ」のルックアップフィールド設定画面を開いていただき、
「関連付けるアプリ」＞「コピー元のフィールド」をご確認ください。

たとえば以下の画面の場合、「顧客管理」アプリの「顧客名」フィールドに対して「値の重複を禁止する」の設定が必要です。

なお、「コピー元のフィールド」には、テーブル内のフィールドを設定することはできません。

kintone ヘルプ「ルックアップの注意点」

上記の設定について、再度ご確認いただけますでしょうか。

ご不明点ございましたらご連絡ください。よろしくお願いいたします。

mseb 2019年11月05日 07:04

お世話になっております。

認証失敗や権限なしをハンドリングしたいと考えております。

エラー時のレスポンスコードとcode(エラーの種類を表すコード)の仕様を公開していただけないでしょうか？

cybozu Development team 2019年11月06日 06:03

mseb 様

お世話になっております。cybozu developer network 運営チームです。

現状APIリクエストのエラー時のレスポンスコードとエラーコードの仕様は公開されておりません。
ご不便をおかけしますが、ご理解いただけますようよろしくお願いいたします。

Takahiro Nakamura 2021年01月26日 13:41

お世話になっております。

JavaScriptにて下記のコードを実行してみたところ、

const request = require('request');

let params = {

  url: 'https://{ドメイン}.cybozu.com/k/v1/records.json?app=9',

  method: 'GET',

  json: true,

  headers: {

    'X-Cybozu-API-Token': '{API　Token}',

  },

};

request(params, function(err:any, resp:any, body:any) {

  if (err) {

    console.log(err);

    return;

  }

  console.log(body);

});

添付した画像のエラーが出てきました。

上記ファイルを設置したのは、SSL認証を完了させたサーバです。

ご対処方法を教示いただければ幸いです。

cybozu Development team 2021年01月27日 05:09

Takahiro Nakamura 様

お世話になっております。cybozu developer network 運営チームです。

提示いただいているコード自体に問題はなさそうです。
確認したところ手元では動作致しました。
※下記の行にTypeScriptのような型情報(any)があったのでそれを削除した上で試しました。

request(params, function(err:any, resp:any, body:any) {

恐れ入りますが、記事のコメント欄は当記事の内容に関するフィードバックのみ受付でおります。

実行環境固有の問題もあるかと思いますので、技術的なご質問はcybozu developer コミュニティをご活用ください。

サインインしてコメントを残してください。

Index

kintone REST APIの概要

プロトコル

フォーマット

文字コード

エスケープ文字

日時のフォーマット

ユーザー認証

パスワード認証

APIトークン認証

セッション認証

認証時の優先順位について

SAML認証設定時の利用について

Basic認証

リクエストヘッダ

リクエストURI

ゲストスペース内のアプリの場合

レスポンス

kintone.api()でリクエストした場合のレスポンスについて

注意事項

制限事項

関連Tips

記事に関するフィードバック