カテゴリー内の他の記事

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 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=

APIトークン認証

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

セッション認証

kintone や Garoon に適用した JavaScript ファイルから kintone REST API を実行する場合には、セッションによる認証を利用できます。

OAuth を使った認証

OAuthクライアントを使用して認証することもできます。
詳細は、OAuthクライアントの使用を参照してください。

認証方式の優先順位

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

  1. パスワード認証
  2. APIトークン認証
  3. OAuth を使った認証
  4. セッション認証

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

セキュリティ設定を行っている環境での API の利用

IP アドレス制限を設定している場合

IP アドレス制限を設定している場合には、次のいずれかの方法で kintone REST API を実行します。

  • kintone REST API を実行するサーバーの IP アドレスを許可する
    許可する方法は、ヘルプページを参照してください。
  • Basic 認証を設定している場合は、「Authorization」リクエストヘッダを付与する
    詳細は、Basic 認証を参照してください。
  • 有効期限の過ぎていないクライアント証明書を付与する
    詳細は、クライアント証明書を参照してください。

Basic 認証

IP アドレス制限に加え、Basic 認証を設定している場合は、リクエストヘッダに「Authorization」ヘッダを追加します。

  • 「Basic 」と「ログイン名:パスワード」をBASE64エンコードしたものを、「Authorization」ヘッダの値に指定します。
    • 「Basic」 と 「ログイン名:パスワード」 の間は、半角空白が必要です。
    • 「Basic 」の BASE64エンコードは不要です。
  • ゲストスペースやゲストスペース内のアプリに対して API を実行する場合には、「Authorization」ヘッダを付ける必要はありません
// ログイン名が「Administrator」、パスワードが「cybozu」の場合
  Authorization:Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=

クライアント証明書

クライアント証明書は、ユーザーに利用サービスの「セキュアアクセス」を許可することで発行できるようになります。
セキュアアクセスの利用を許可し、クライアント証明書を発行する方法は、セキュアアクセスを設定するを参照してください。

  • リクエストする URLには、.s を付ける必要があります。
    たとえば、URL が https://sample.cybozu.com の場合は、https://sample.s.cybozu.com です。
  • 違うユーザーのクライアント証明書を使って、パスワード認証をする場合には、.com 共通管理のログインのセキュリティ設定で、「API利用時の認証」を有効にしてください。
    詳細は、ログインに関するセキュリティの概要を参照してください。

SAML認証を設定している場合

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

2要素認証を設定している場合

2要素認証を設定した cybozu.com ユーザーアカウントでは、パスワード認証は利用できません。

パスワード認証以外の認証方式で実行するか、2要素認証を無効にした連携用ユーザーを用意してください。

リクエストヘッダ

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

※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 スキーマ情報の取得

制限事項

ドメインへの同時接続

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

アプリのレコード操作API

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

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

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

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

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

その他の制限事項

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

関連Tips

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

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

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
hosyuta

>Moriatsu Iri

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

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

Avatar
flowers

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

Avatar
cybozu Development team

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
demachi

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

出町と申します。

 

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

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

 

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

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

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

 

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

Avatar
cybozu Development team

出町 望 様

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

 

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

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

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

 

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

 

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

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

Avatar
mseb

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

 

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

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

Avatar
cybozu Development team

mseb 様

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

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

Avatar
Takahiro Nakamura

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

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認証を完了させたサーバです。

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

Avatar
cybozu Development team

Takahiro Nakamura 様

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

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

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

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

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

Avatar
金田 晃

お世話になります。英語版の記載も日本語に合わせて記載を追記してほしいです。例えば日付フォーマットについて

英語版:
https://developer.kintone.io/hc/en-us/articles/212495188#dateformats

だと、日本語版にある

秒情報を指定して登録または更新を行った場合、秒情報は無視されます。
例)「2019-02-06T12:59:59Z」と指定すると、「2019-02-06T12:59:00Z」として登録または更新されます。

の注釈が見当たりません。

Avatar
cybozu Development team

金田様

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

英語版の記事において、情報に不足があり大変申し訳ございません。
確認し対応させていただきます。

ご指摘いただきましてありがとうございました。
今後ともご活用いただけますと幸いです。

Avatar
5MP2

お世話になります。

「日時のフォーマット」の「日時」の「説明」の3行目について質問です。

  • 取得時の「Z」はUTCを表します。一覧の取得APIでは日時はUTCで出力されます。

"一覧の取得API"とありますが、具体的なAPIはどれになるか教えていただけると助かります。

 

Avatar
cybozu Development team

Kazuhiro Yoshida 様

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

「一覧の取得API」は「一覧の設定の取得」API を指しております。
https://developer.cybozu.io/hc/ja/articles/204529784

記事に不明瞭な点があり、申し訳ございません。
何卒、よろしくお願いいたします。

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