アプリのフォームの設定を取得します。
フォームの設定の取得には、次の2つの操作で異なるAPIを使用します。
- フィールドの一覧を取得する
フィールドの一覧、およびそれらの設定を取得します。 - フォームのレイアウトを取得する
次の設定を取得します。 - フィールドの縦幅と横幅
- テーブルに設定したフィールドと、それらの順番
- グループフィールドに入れたフィールドと、それらのレイアウト
- ラベル、スペース、および罫線の設定
フィールドの一覧を取得する
URI
URIは、運用環境の設定を取得する場合と、動作テスト環境の設定を取得する場合とで異なります。
運用環境の設定を取得する場合
https://(サブドメイン名).cybozu.com/k/v1/app/form/fields.json
ゲストスペースのアプリの場合:https://(サブドメイン名).cybozu.com/k/guest/(スペースのID)/v1/app/form/fields.json
動作テスト環境の設定を取得する場合
https://(サブドメイン名).cybozu.com/k/v1/preview/app/form/fields.json
ゲストスペースのアプリの場合:https://(サブドメイン名).cybozu.com/k/guest/(スペースのID)/v1/preview/app/form/fields.json
HTTPメソッド
GET
必要なアクセス権
運用環境の設定を取得する場合、次のいずれかの権限が必要です。
- アプリのレコード閲覧権限
- アプリのレコード追加権限
動作テスト環境の設定を取得する場合
- アプリ管理権限
リクエストパラメータ
パラメータ名 | 指定する値 | 必須 | 説明 |
---|---|---|---|
app | 数値または文字列 | 必須 | アプリのIDを指定します。 |
lang | 文字列 | フィールドや選択肢の名前に「言語ごとの名称」を設定している場合に、取得する名称の言語を指定します。
|
リクエストの例
送信するリクエストは、パラメータの送信方法によって異なります。パラメータ「app」と「lang」を指定したリクエストの例は、次のとおりです。
URLにパラメータを含める場合
GET /k/v1/app/form/fields.json?app=8&lang=ja HTTP/1.1 Host: example.cybozu.com:443 X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU= Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=
リクエストボディにパラメーターを含める場合
ヘッダ
GET /k/v1/app/form/fields.json HTTP/1.1 Host: example.cybozu.com:443 X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU= Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU= Content-Type: application/json
ボディ
レスポンス
パラメータ
パラメータ名 | 値の種類 | 説明 |
---|---|---|
properties | オブジェクト | フィールドの設定を表すオブジェクトです。 |
properties.(フィールドコード).label | 文字列 | フィールド名です。 |
properties.(フィールドコード).code | 文字列 | フィールドコードです。 |
properties.(フィールドコード).type | 文字列 | フィールドの種類です。
|
properties.(フィールドコード).noLabel | 真偽値 | フィールド名を非表示にするかどうかの設定です。
|
properties.(フィールドコード).required | 真偽値 | 入力が必須かどうかの設定です。
|
properties.(フィールドコード).unique | 真偽値 | 重複を禁止するかどうかの設定です。
|
properties.(フィールドコード).maxValue | 文字列 | 最大値です。未設定の場合は空です。 |
properties.(フィールドコード).minValue | 文字列 | 最小値です。未設定の場合は空です。 |
properties.(フィールドコード).maxLength | 文字列 | 最大文字数です。未設定の場合は空です。 |
properties.(フィールドコード).minLength | 文字列 | 最小文字数です。未設定の場合は空です。 |
properties.(フィールドコード).defaultValue | 文字列または配列 | 初期値です。複数の初期値を設定できるフィールドでは、配列が返ります。 |
properties.(フィールドコード).defaultNowValue | 真偽値 | レコード登録時の日時を初期値にするかどうかの設定です。
|
properties.(フィールドコード).options | オブジェクト | 選択肢の設定を表すオブジェクトです。 |
properties.(フィールドコード).options.(選択肢名).label | 文字列 | 選択肢名です。 |
properties.(フィールドコード).options.(選択肢名).index | 文字列 | 選択肢の順番(昇順)です。 |
properties.(フィールドコード).align | 文字列 | 選択肢の並びです。
|
properties.(フィールドコード).expression | 文字列 | 自動計算式です。未設定の場合は空です。 |
properties.(フィールドコード).hideExpression | 真偽値 | 計算フィールドの計算式を非表示にするかどうかの設定です。
|
properties.(フィールドコード).digit | 真偽値 | 数値の桁区切りを表示するかどうかの設定です。
|
properties.(フィールドコード).thumbnailSize | 文字列 | 画像のサムネイルの大きさ(ピクセル単位)です。 |
properties.(フィールドコード).protocol | 文字列 | リンクの種類です。
|
properties.(フィールドコード).format | 文字列 | 計算フィールドの表示形式です。
|
properties.(フィールドコード).displayScale | 文字列 | 小数点以下の表示桁数です。未設定の場合は空です。 |
properties.(フィールドコード).unit | 文字列 | 単位記号です。 |
properties.(フィールドコード).unitPosition | 文字列 | 単位記号の表示位置です。
|
properties.(フィールドコード).entities | 配列 | 選択肢のユーザーを表す配列です。未設定の場合は空です。 |
properties.(フィールドコード).entities[].code | 文字列 | 選択肢のユーザー、グループ、または組織のコードです。 |
properties.(フィールドコード).entities[].type | 文字列 | 値の種類です。
|
properties.(フィールドコード).referenceTable | オブジェクト | 関連レコード一覧フィールドの設定を表すオブジェクトです。参照先のアプリに閲覧権限がない場合はnullです。 |
properties.(フィールドコード).referenceTable.relatedApp | オブジェクト | 「参照するアプリ」の設定を表すオブジェクトです。 |
properties.(フィールドコード).referenceTable.relatedApp.app | 文字列 | 「参照するアプリ」に指定されたアプリのIDです。 |
properties.(フィールドコード).referenceTable.relatedApp.code | 文字列 | 「参照するアプリ」に指定されたアプリのコードです。アプリコードが未設定の場合は空です。 |
properties.(フィールドコード).referenceTable.condition | オブジェクト | 「表示するレコードの条件」の設定を表すオブジェクトです。 |
properties.(フィールドコード).referenceTable.condition.field | 文字列 | 「表示するレコードの条件」で指定された、関連レコード一覧フィールドと同じアプリのフィールドのコードです。 |
properties.(フィールドコード).referenceTable.condition.relatedField | 文字列 | 「表示するレコードの条件」で指定された、関連レコード一覧フィールドが参照するアプリのフィールドのコードです。 |
properties.(フィールドコード).referenceTable.filterCond | 文字列 | 「さらに絞り込む条件」の設定です。クエリ形式で表されます。クエリ形式については、次のページを参照してください。 レコードの一括取得(クエリで条件を指定) |
properties.(フィールドコード).referenceTable.displayFields | 配列 | 「表示するフィールド」に指定されたフィールドのコードの配列です。 |
properties.(フィールドコード).referenceTable.sort | 文字列 | レコードのソートの設定です。クエリ形式で表されます。クエリ形式については、次のページを参照してください。 レコードの一括取得(クエリで条件を指定) |
properties.(フィールドコード).referenceTable.size | 文字列 | 一度に表示する最大レコード数です。 |
properties.(フィールドコード).lookup | オブジェクト | ルックアップフィールドの設定を表すオブジェクトです。参照先のアプリに閲覧権限がない場合はnullです。 |
properties.(フィールドコード).lookup.relatedApp | オブジェクト | 「関連付けるアプリ」の設定を表すオブジェクトです。 |
properties.(フィールドコード).lookup.relatedApp.app | 文字列 | 関連付くアプリのIDです。 |
properties.(フィールドコード).lookup.relatedApp.code | 文字列 | 関連付くアプリのコードです。アプリコードが未設定の場合は空です。 |
properties.(フィールドコード).lookup.relatedKeyField | 文字列 | 「コピー元のフィールド」に指定されたフィールドのコードです。 |
properties.(フィールドコード).lookup.fieldMappings | 配列 | 「ほかのフィールドのコピー」の設定を表す配列です。未設定の場合は空です。 |
properties.(フィールドコード).lookup.fieldMappings[].field | 文字列 | 「ほかのフィールドのコピー」のコピー先に指定されたフィールドのコードです。 |
properties.(フィールドコード).lookup.fieldMappings[].relatedField | 文字列 | 「ほかのフィールドのコピー」のコピー元に指定されたフィールドのコードです。 |
properties.(フィールドコード).lookup.lookupPickerFields | 配列 | 「コピー元のレコードの選択時に表示するフィールド」の設定を表す、フィールドコードの配列です。未設定の場合は空です。 |
properties.(フィールドコード).lookup.filterCond | 文字列 | 絞り込みの初期設定です。クエリ形式で表されます。クエリ形式については、次のページを参照してください。 レコードの一括取得(クエリで条件を指定) |
properties.(フィールドコード).lookup.sort | 文字列 | ソートの初期設定です。クエリ形式で表されます。クエリ形式については、次のページを参照してください。 レコードの一括取得(クエリで条件を指定) |
properties.(フィールドコード).openGroup | 真偽値 | グループ内のフィールドを表示するかどうかの設定です。
|
properties.(フィールドコード).fields | オブジェクト | テーブル内のフィールドを表すオブジェクトです。オブジェクトのパラメータは、「properties」パラメータと同じです。 |
properties.(フィールドコード).enabled | 真偽値 |
機能が有効かどうかの設定です。このパラメータは、ステータスフィールド、およびカテゴリーフィールドでのみ出力されます。
|
revision | 文字列 | アプリの設定のリビジョン番号です。 |
レスポンスの例
JavaScriptサンプル
XMLHttpRequest
フォームのレイアウトを取得する
URI
URIは、運用環境の設定を取得する場合と、動作テスト環境の設定を取得する場合とで異なります。
運用環境の設定を取得する場合
https://(サブドメイン名).cybozu.com/k/v1/app/form/layout.json
ゲストスペースのアプリの場合:https://(サブドメイン名).cybozu.com/k/guest/(スペースのID)/v1/app/form/layout.json
動作テスト環境の設定を取得する場合
https://(サブドメイン名).cybozu.com/k/v1/preview/app/form/layout.json
ゲストスペースのアプリの場合:https://(サブドメイン名).cybozu.com/k/guest/(スペースのID)/v1/preview/app/form/layout.json
HTTPメソッド
GET
必要なアクセス権
運用環境の設定を取得する場合、次のいずれかの権限が必要です。
- アプリのレコード閲覧権限
- アプリのレコード追加権限
動作テスト環境の設定を取得する場合
- アプリ管理権限
リクエストパラメータ
パラメータ名 | 指定する値 | 必須 | 説明 |
---|---|---|---|
app | 数値または文字列 | 必須 | アプリのIDを指定します。 |
リクエストの例
送信するリクエストは、パラメータの送信方法によって異なります。パラメータ「app」を指定したリクエストの例は、次のとおりです。
URLにパラメータを含める場合
GET /k/v1/app/form/layout.json?app=8 HTTP/1.1 Host: example.cybozu.com:443 X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU= Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=
リクエストボディにパラメーターを含める場合
ヘッダ
GET /k/v1/app/form/layout.json HTTP/1.1 Host: example.cybozu.com:443 X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU= Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU= Content-Type: application/json
ボディ
レスポンス
パラメータ
パラメータ名 | 値の種類 | 説明 |
---|---|---|
layout | 配列 | フォームの行ごとのレイアウトを表す配列です。 |
layout[].type | 文字列 | 行の種類です。
|
layout[].code | 文字列 | テーブル、またはグループのコードです。いずれでもない行では、このパラメータは出力されません。 |
layout[].fields | 配列 | 行に含まれるフィールドを表す配列です。 |
layout[].fields[].type | 文字列 | フィールドの種類です。
|
layout[].fields[].code | 文字列 | フィールドコードです。 |
layout[].fields[].label | 文字列 | ラベル名です。ラベルフィールドで出力されます。 |
layout[].fields[].elementId | 文字列 | 要素IDです。スペースフィールドで出力されます。 |
layout[].fields[].size | オブジェクト | フィールドのサイズを表すオブジェクトです。 ※ PCで表示したときのフィールドサイズです。スマートフォンで表示したときのフィールドサイズは取得できません。 |
layout[].fields[].size.width | 文字列 | ピクセル単位でのフィールドの横幅です。 |
layout[].fields[].size.height | 文字列 | フィールド名を含めた、ピクセル単位でのフィールドの縦幅です。 |
layout[].fields[].size.innerHeight | 文字列 | フィールド名を除いた、ピクセル単位でのフィールドの縦幅です。 |
layout[].layout | 配列 | グループ内のフィールドのレイアウトを表す配列です。 |
revision | 文字列 | アプリの設定のリビジョン番号です。 |
レスポンスの例
JavaScriptサンプル
XMLHttpRequest
「フィールドの一覧を取得する」のレスポンスのパラメータが「properties.(フィールドコード).referenceTable.fliterCond」となっている行がありますが、「properties.(フィールドコード).referenceTable.filterCond」ではないでしょうか。
takasakai 様
お世話になっております。
cybozu developer network 事務局です。
ご指摘ありがとうございます。
ご指摘頂いた通り、こちら正しくは「properties.(フィールドコード).referenceTable.filterCond」です。
該当箇所修正致しました。
今後ともよろしくお願い致します。
フィールドの一覧を取得するAPI(/form/fields.json)のレスポンスJSONの各フィールド項目ですが、Code順でもなく、フォーム設計情報(画面)の順番でも無いようですが、並び順の仕様を教えて頂けますでしょうか?
Yoshiyuki Kuwajima 様
お世話になっております。
cybozu developer network 事務局です。
/form/fields.json のレスポンスJSONの並び順ですが、不定となっております。
フィールドの並び順を参照したい場合は、layout.jsonをご利用ください。
宜しくお願い致します。
事務局ご担当者様
ご回答ありがとうございます。不定との旨理解いたしました。
cybozu Development team さま
お世話になっております。
テスト環境のフィールドの一覧を取得(/k/v1/preview/app/form/fields)のレスポンスが
掲載されている形式と異なるようです。
console.logに出してみたところ
運用環境の場合は"properties"以下がフィールドコードをkeyとしたobjectですが、
テスト環境の場合は"properties"以下が配列になっています。
ご確認お願いします。
Jo 様
お世話になっております。
cybozu developer network 事務局です。
ご指摘の点について、1点確認させてください。
比較されたAPIは「テスト環境:/k/v1/preview/app/form/fields.json」と「運用環境:/k/v1/app/form/fields.json」で合っていますでしょうか?
なお、フォーム設計情報取得 (/k/v1/form.json または /k/v1/preview/form.json)を使うと、properties は配列で返ってきます。
テスト環境のリクエストで form.json を使われていることはないでしょうか?
/k/v1/preview/app/form/fields.json と /k/v1/app/form/fields.json でレスポンスを比較してみましたが、差異はなく本記事の記載通りの形式でした。
大変恐れ入りますが、リクエストを送ったコードとレスポンス結果をご提示いただくことは可能でしょうか?
(個人情報に当たる部分は xxx などでマスキングしていただければと思います)
よろしくお願いいたします。
cybozu Development team さま
ご指摘の通り、掲載されているrespは正確な形式です。
大変失礼致しました。
Jo 様
お世話になっております。
cybozu developer network 事務局です。
ご確認いただきありがとうございます。
記載の内容で問題なかったとのこと、承知いたしました。
今後ともよろしくお願い致します。
お世話になっております。
テスト環境と運用環境で異なるURIでAPIをコールするという記述について質問です。テスト環境と運用環境の違いがよくわからず検索したところ以下の2つの記事を見つけました。
①テスト環境で作ったアプリを運用環境にデプロイしてみよう-前編
https://developer.cybozu.io/hc/ja/articles/204851030
②アプリの動作テストをする
https://jp.cybozu.help/k/ja/user/app_settings/app_preview.html
①と②どちらでも「テスト環境」という言葉が使われていますが、異なる概念を指しているように思えます。API呼び出しのURIに関して「テスト環境」と書かれているのはどちらを指しているのでしょうか?
よろしくお願いします。
LunaPapa 様
API呼び出しのURIに関しての「テスト環境」は、記載②の、kintone アプリの動作テスト環境に該当します。
①はテスト用の別の環境、という意味で使っています。
cybozu Development team 様
ご回答ありがとうございます。了解いたしました。
お世話になっております。
/form/fields.jsonで得られるレスポンスの内容について、1点質問があります。
ルックアップフィールドについて、関連するアプリでは以下のようにアプリIDとアプリコードが得られるとあります。
しかし、レスポンス例を見ると、codeに半角英数字ではない値が入っているように見えます。
アプリコードは、半角英数字でなければならないと認識しているのですが、こちらには
アプリコードが入るということでよろしいのでしょうか。
以上、よろしくお願いいたします。
Morimori 様
お世話になっております。 cybozu developer network 事務局です。
> アプリコードは、半角英数字でなければならないと認識している
はい、ご認識いただいておりますとおり、アルファベットから始まる半角英数字である必要がございます。
> こちらにはアプリコードが入るということでよろしいのでしょうか
はい、アプリコードが入ります。
誤解を招いて申し訳ございませんが、添付いただいております画像にあるレスポンス例につきましては「コピー元アプリのアプリコードが入る」という意図で示しております。よろしくお願いいたします。
MoriMori 様
ご質問いただきました /form/fields.jsonで得られるレスポンス の記述について、
アプリコードが入ることがわかりにくいと思われるため下記のように修正いたしました。
フィードバックをありがとうございました。