kintone REST APIの概要
kintone アプリのレコードの操作やフォーム設計情報の取得、スペースを操作することができます。
プロトコル
HTTPS
フォーマット
JSON
文字コード
UTF-8
エスケープ文字
「\」を使用します。
日時のフォーマット
日付、時刻、日時フィールド(作成日時、更新日時フィールドも含む)のデータを扱う場合、それぞれ以下のフォーマットの文字列で指定する必要があります。
フィールドタイプ | フォーマット | 説明 |
---|---|---|
日付 | YYYY-MM-DD | UTCに変換されません。
以下のような形式の入力を受け付けます。 月日を省略した場合は01で補完されます。 |
時刻 | HH:MM:SS | UTCに変換されません。 |
日時 | 取得時 YYYY-MM-DDTHH:MM:SSZ |
|
登録・更新時 YYYY-MM-DDTHH:MM:SS±HH:MM または YYYY-MM-DDTHH:MM:SSZ |
|
ユーザー認証
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)
ルックアップフィールドの値を登録/更新する場合は、こちらの記事をご参照ください。 - レコードの一括登録
- レコードコメントの投稿 / レコードコメントの削除
- レコードの作業者の更新
- レコードのステータスの更新
- 複数アプリへのレコード一括処理
- レコードの取得(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が実行されます。
※リクエストURIが8KBを超えると発生するエラー(Request URI Too Large)を回避する目的で使用します。 以下のリクエストを送信した場合、レコード一括取得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件までです。
その他の制限事項
- その他、サービスに関する制限事項は、こちら をご確認ください。
REST APIエラー時のレスポンスのcode(エラーコードの種類)について、公開はないのでしょうか?
一般的なものだけでも公開していただけるとありがたいのですが。
具体的には、同時アクセスによるエラーコードが"GAIA_RE18"で返って来ているようなので、
この場合個別にハンドリングしてリトライさせたいのですが、
公式で公開していただけると安心してハンドリングロジックを入れられるので。
試用版を利用しているところ、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"}
Shigeru SAWADAさん
cybozu.com developer network事務局です。
残念ながら今のところ公開予定はありません。
ただ、要望は多い所ではあるので将来的に検討していきたいと思います。
Shigeru SAWADA
cybozu.com developer network事務局です。
恐らくなにかパラメータが間違っているはずです…認証キーの設定等を見返してみてください。
cybozu.com developer network事務局さま
回答ありがとうございました。
是非とも将来的に検討のほどよろしくお願いします。
アプリの一覧を取得するAPIは存在しないのでしょうか?
>Moriatsu Iri
アプリ情報取得APIの一括取得をすればよいかと。
https://cybozudev.zendesk.com/hc/ja/articles/202931674
API連携を検討しております。上限5,000行を超える場合の方法は何かありませんでしょうか。
iwasaki様
>1つのテーブルに登録できる行数の上限値は5,000行までです
についてのご相談でしょうか。
仕様外についてのご質問は、具体的に希望される動作を明記の上cybozu developer コミュニティに投稿ください。
APIリクエスト数10,000件の制限があると思いますが、
それに関連して現在のAPIリクエスト数を取得するAPIはございますでしょうか。
suzuki 様
お世話になっております。developer network 運営チームです。
現在のAPIリクエスト数を取得するAPIはございません。
ご希望に添えず申し訳ございません。
なお、現在のAPIリクエスト数はアプリ管理画面にてご確認いただけます。
詳しくは こちら をご確認ください。
今後ともよろしくお願いいたします。
プロセス管理に関するREST APIのページへのリンクが左部ツリーメニューより消えています。
APIの廃止や使用の非推奨が予定されているのでしょうか?
田中 靖之 様
お世話になっております。developer network 運営チームです。
大変申し訳ございません、メニュー表示に誤りがあったため修正いたしました。
プロセス管理のAPIにについて、廃止予定はございません。
ご指摘いただきましてありがとうございました。
今後ともよろしくお願いいたします。
developer network 運営チーム様
ご回答ありがとうございました。
APIに変更がないとのことで安心しました。
今後ともよろしくお願いいたします。
お世話になります。
日時フィールドの初期値に
日付→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がセットされています。
ミリ秒が記載されているかどうかで判断が分かれるということでしょうか?
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がない状態で返ってくるべきです。
この件については、社内に不具合として共有しております。
ご指摘いただきましてありがとうございました。
今後ともよろしくお願いいたします。
お世話になっております。
出町と申します。
ルックアップで取得し登録したデータを別アプリにコピーするのに、
「値の重複を禁止する」をオンにしました。
一つ確認ですが、サブテーブルに設定されているルックアップフィールドは、
「値の重複を禁止する」がオフのままでも別アプリにコピーされました。
これは制限事項の対象外ということなのでしょうか。
ご教示のほどよろしくお願いいたします。
出町 望 様
お世話になっております。cybozu developer network 運営チームです。
「値の重複を禁止する」設定が必要なのは、「関連付けるアプリ」の「コピー元のフィールド」に対してです。
「APIでレコードを登録するアプリ」のルックアップフィールド設定画面を開いていただき、
「関連付けるアプリ」>「コピー元のフィールド」をご確認ください。
たとえば以下の画面の場合、「顧客管理」アプリの「顧客名」フィールドに対して「値の重複を禁止する」の設定が必要です。
なお、「コピー元のフィールド」には、テーブル内のフィールドを設定することはできません。
上記の設定について、再度ご確認いただけますでしょうか。
ご不明点ございましたらご連絡ください。よろしくお願いいたします。
お世話になっております。
認証失敗や権限なしをハンドリングしたいと考えております。
エラー時のレスポンスコードとcode(エラーの種類を表すコード)の仕様を公開していただけないでしょうか?
mseb 様
お世話になっております。cybozu developer network 運営チームです。
現状APIリクエストのエラー時のレスポンスコードとエラーコードの仕様は公開されておりません。
ご不便をおかけしますが、ご理解いただけますようよろしくお願いいたします。
お世話になっております。
JavaScriptにて下記のコードを実行してみたところ、
添付した画像のエラーが出てきました。
上記ファイルを設置したのは、SSL認証を完了させたサーバです。
ご対処方法を教示いただければ幸いです。
Takahiro Nakamura 様
お世話になっております。cybozu developer network 運営チームです。
提示いただいているコード自体に問題はなさそうです。
確認したところ手元では動作致しました。
※下記の行にTypeScriptのような型情報(any)があったのでそれを削除した上で試しました。
恐れ入りますが、記事のコメント欄は当記事の内容に関するフィードバックのみ受付でおります。
実行環境固有の問題もあるかと思いますので、技術的なご質問はcybozu developer コミュニティをご活用ください。