kintone REST API リクエストを送信する
kintone REST API および User API で利用できます。
- PCとモバイルで利用できます。
- 本 API は非同期リクエストとなります。同期的に処理したい場合はこちらの Tips をご参照ください。
- kintone REST API のファイルアップロード API、ファイルダウンロード APIでは利用できません。
これらを利用する際には、CSRF トークンを取得して、HTTP リクエストで実行してください。 - User APIのファイルアップロード API、URI の末尾が .json 以外の API(ユーザーエクスポート API(CSV)など)では利用できません。
- kintone.api() を利用する場合、リクエストヘッダの指定は不要です。
関数
kintone.api(pathOrUrl, method, params, successCallback, failureCallback)
引数
パラメータ名 | 指定する値 | 必須 | 説明 |
---|---|---|---|
pathOrUrl | 文字列 | 必須 |
kintone REST API のパスもしくは、kintone.api.url で取得したURLを指定します。 例) API の URL が https://(サブドメイン名).cybozu.com/k/v1/xxx.json の場合は、"/k/v1/xxx.json" を指定します。 ゲストスペース内アプリでも動作させる場合は、kintone.api.url("/k/v1/xxx.json", true) を指定してください。 |
method | 文字列 | 必須 | 使用する HTTP メソッド。 GET, POST, PUT, DELETE が指定可能です。 |
params | オブジェクト | 必須 | API に渡すパラメータをオブジェクトで指定します。 |
successCallback | 関数 | 省略可 |
API の呼び出しが成功したら実行されるコールバック関数です。 引数の型はオブジェクトになります。 |
failureCallback | 関数 | 省略可 |
API の呼び出しが失敗したら実行されるコールバック関数です。 引数にはレスポンス JSON が渡されます。 レスポンスが JSON としてパースできなかった場合は、パース前の文字列が渡されます。 |
返り値
引数の successCallback を省略した時、kintone.Promise オブジェクトを返します。
※ この kintone.Promise オブジェクトを return することで、kintone.api() の実行を待ってから次の処理を実行できるイベントがあります。
対応しているイベントはこちらをご参照ください。
successCallback を指定した場合返り値はありません。
利用できる画面
- 全ての画面(アプリ、スペースも含まれます)
サンプル
コールバックを使用した記述方法
kintone.Promise オブジェクトを使った記述方法
URL を取得する(クエリ文字列無し)
省略した形式の API のパスから、URL を生成します。
- PCとモバイルで利用できます。
- User API のファイルアップロード API、URI の末尾が .json 以外の API(ユーザーエクスポート API(CSV)など)では利用できません。
関数
kintone.api.url(path, detectGuestSpace)
引数
パラメータ名 | 指定する値 | 必須 | 説明 |
---|---|---|---|
path | 文字列 | 必須 |
kintone REST API のパスを / で始まる文字列で指定します。 例)API の URL が https://(サブドメイン名).cybozu.com/k/v1/xxx.json の場合は、"/k/v1/xxx.json" を指定します。 |
detectGuestSpace | 真偽値 | 省略可 | ゲストスペース内で true を指定する場合、kintone REST API の実行に必要なゲストスペース用の URI が返されます。デフォルトは false です。 |
返り値
URL 文字列。
利用できる画面
- 全ての画面(アプリ、スペースも含まれます)
サンプル
URL を取得する(クエリ文字列付き)
API のパスとパラメータを受け取ってクエリ文字列付きの URL を生成します。
- PCとモバイルで利用できます。
- User API のファイルアップロード API、URI の末尾が .json 以外の API(ユーザーエクスポート API(CSV)など)では利用できません。
関数
kintone.api.urlForGet(path, params, detectGuestSpace)
引数
パラメータ名 | 指定する値 | 必須 | 説明 |
---|---|---|---|
path | 文字列 | 必須 |
kintone REST API のパスを / で始まる文字列で指定します。 例) API の URL が https://(サブドメイン名.cybozu.com/k/v1/xxx.json の場合は、"/k/v1/xxx.json" を指定します。 |
params | オブジェクト | 必須 | パラメータをオブジェクトで指定します。 |
detectGuestSpace | 真偽値 | 省略可 | ゲストスペース内で true を指定する場合、kintone REST API の実行に必要なゲストスペース用の URI が返されます。デフォルトは false です。 |
返り値
クエリ文字列が付与され、パラメータが URL エンコードされた URL 文字列。
// パラメータにオブジェクトや配列が渡された場合、クエリ文字列は以下のように展開されます。 // params = {app: 4, fields: ['record_no']} https://{subdomain}.cybozu.com/k/v1/records.json?app=4&fields[0]=record_no
利用できる画面
- 全ての画面(アプリ、スペースも含まれます)
サンプル
CSRF トークンの取得
HTTP メソッドが POST, PUT, DELETE である API すべてにおいて利用できます。
- PCとモバイルで利用できます。
- HTTP メソッドが GET の API では CSRF トークンは不要です。
関数
kintone.getRequestToken()
引数
なし
返り値
文字列
利用できる画面
- 全ての画面(アプリ、スペースも含まれます)
有効期間
最終アクセス時間から 86400 秒(1日)
サンプル
API がパラメータをクエリで受け付ける場合の例
https://(サブドメイン名).cybozu.com/k/v1/records.json?__REQUEST_TOKEN__=72A0C9714B6E1C086D24BBC11A5C3508
API がパラメータをリクエストボディで受け付ける場合の例
以下のリクエストヘッダを API 実行時に指定します。
ヘッダー名 | 内容 |
---|---|
X-Requested-With | XMLHttpRequest |
Content-Type | application/json |
わかりずらすぎ
井ノ内勢二郎様
コメントいただきありがとうございます。
ドキュメントの改善に努めたいと思いますので、もし可能でしたらどういった点が分りずらいかお伝えいただくことはできますか?
GET, POST, PUT, DELETE それぞれについてサンプルコードが欲しいです。GETの例にしてもrecord_noはアプリで定義したパラメータであることが書かれておらず動かすのに苦慮しました。また、JavaScript APIがREST APIの上に乗っていることも明記されておらず、現在POSTするコードを書いているのですが両方のページを行ったり来たりして試行錯誤中です。APIの設計は良いと思うので、ぜひそれに見合ったドキュメントを付けて下さい。
REST APIを実行する際にアプリIDを指定しますが、アプリコードなどからアプリを指定してGETやPOSTを行うことは可能でしょうか?
(例)
https://xxxxxxx.cybozu.com/k/v1/records.json?app=889&id=100
https://xxxxxxx.cybozu.com/k/v1/records.json?app=(アプリコードなど)&id=15
kintone.api()に直接記述することと、
kintone.api.urlForGet()の返り値をkintone.api()のpathOrUrlに指定することは どのように使い分けるべきでしょう。
推奨等はありますか?
吉岡 三四郎さん
たしかGETはURLにappidとid指定すればいけますが、POSTはムリだったと思います。
尾浦 俊行さん
コードの可読性的に(個人の好みになっちゃいますが) kintone.api()のparamsに記載するほうがわかりやすいなーと思います
こちらのAPIは非常に使いやすいのですが、非同期メソッドであることを明記して欲しいです。
ナカゴウユイエさん
cybozu.com developer network事務局です。
ありがとうございます。確かに追記したほうがよさそうですね。
同期処理の場合以下のようなTipsもありますので、ご参照ください。
https://cybozudev.zendesk.com/hc/ja/articles/204564604
↑ということで追記致しました。
は、早い…!素早いご対応ありがとうございます。また、2015年7月に実装された同期処理の頁の紹介、非常に助かります。こちらも合せてお礼を申し上げます。
下記の点をご教示ください。
Q.kintone.apiを利用したGETメソッドの場合、ユーザー認証は不要でしょうか?
Q.CSRFトークンを利用したPOST, PUT, DELETEメソッドのサンプルコードを教えてください。
キントーンカスタマイズを始めて1ケ月の初心者です。サイボウズ デベロッパー ネットワークのサイト構成が初心者にとっては、
1.Webページを表示するまでの流れ(HTTP リクエスト等)
2.javascript等のプログラム言語
3.API
の基本知識は持っている前提の構成になっているため、知識がなくてもできる部分もあのますが、基本知識がないとはまり込んでしまう部分があることを痛感しています。最低限のカスタマイズはサンプルコードをアレンジしてできたのですが、javascriptの非同期処理と同期処理、APIについて知識ももたず適当にやっていてつまずいています。APIについて勉強してから次に進むのが近道のようですね。ユーチューブの情報サイトを見て勉強します。
White 様
お世話になっております。cybozu developer network 運営チームです。
フィードバックをいただきありがとうございます。参考にさせていただきます。
JavaScript や API については、チュートリアルがありますのでこちらもご参照ください。
https://developer.cybozu.io/hc/ja/articles/360024370392
今後とも kintone をご活用いただけますと幸いです。