検索
Close
カテゴリー内の他の記事

kintone REST APIの共通仕様

作成日
更新日
フォローする

Index

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:SS 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 共通管理」より「証明書のユーザーとパスワード認証のユーザーが異なるアクセスを許可する」を有効にしてください。

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
  • 生成できるトークンは、アプリ1つにつき20個までです。
  • APIトークンを使用した操作は、Administratorによる操作として記録されます。
  • リクエストヘッダに「X-Cybozu-Authorization」を指定していると、その認証が優先されます。
  • APIトークンは、アプリを操作する次のkintone REST APIで使用できます。
  • セキュアアクセス設定時、有効なクライアント証明書が使用されている場合のみAPIトークン認証を利用できます。
  • 組織間のアクセス権の設定を有効にすると、APIトークンを生成/閲覧できるのはkintoneシステム管理者のみになります。

セッション認証

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

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

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

  1. パスワード認証
  2. APIトークン認証
  3. セッション認証

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

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

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

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

Basic認証

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

リクエストヘッダ

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

ヘッダー名 内容
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件までです。
  • 一度に登録、更新、および削除できるレコードは100件までです。
  • 1つのテーブルに登録できる行数の上限値は5,000行までです。
  • レコード取得、登録、更新において、存在しないフィールドコードを指定した場合は、そのフィールドコードへの処理は無視されます。
  • 次のフィールドは、レコードの取得 APIによって値の取得のみできます。レコードの登録API及びレコードの更新APIで値の登録と更新はできません。
  • レコード登録、更新において、ルックアップフィールドの値を変更する場合、ルックアップフィールドの「コピー元のフィールド」はレコード番号または「値の重複を禁止する」に設定されている必要があります。
  • ルックアップフィールドの「コピー元のフィールド」に自動計算の設定をしている「文字列1行」フィールドを選択している場合、ルックアップフィールドの値は変更できません。

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

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

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

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

その他の制限事項

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

関連Tips

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

直接的に記事と関連がないご質問はcybozu developer コミュニティをご活用ください。

Avatar
Shigeru SAWADA

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

Avatar
dylan

試用版を利用しているところ、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"}

Avatar
cybozu development team

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

Avatar
cybozu development team

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

Avatar
Shigeru SAWADA

cybozu.com developer network事務局さま

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

Avatar
miriorg

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

Avatar
Yutaro Hosoi

＞Moriatsu Iri

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

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

Avatar
flowers

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

Avatar
ダン吉

iwasaki様

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

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

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

Avatar
suzuki

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

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

Avatar
cybozu Development team

suzuki 様

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

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

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

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

Avatar
Yasuyuki Tanaka

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

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

Yasuyuki Tanakaにより編集されました
Avatar
cybozu Development team

田中　靖之 様

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

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

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

Avatar
Yasuyuki Tanaka

developer network 運営チーム様

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

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

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

Avatar
Suzuki Suguru

お世話になります。

 

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

日付→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がセットされています。

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

Avatar
cybozu Development team

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がない状態で返ってくるべきです。
この件については、社内に不具合として共有しております。

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

Avatar
出町 望

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

出町と申します。

 

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

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

 

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

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

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

 

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

Avatar
cybozu Development team

出町 望 様

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

 

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

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

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

 

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

 

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

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

Avatar
mseb

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

 

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

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

Avatar
cybozu Development team

mseb 様

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

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

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