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

フォームの設定の取得

作成日
更新日

アプリのフォームの設定を取得します。
フォームの設定の取得には、次の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 文字列   フィールドや選択肢の名前に「言語ごとの名称」を設定している場合に、取得する名称の言語を指定します。
  • 日本語の名称を取得する場合：ja
  • 英語の名称を取得する場合：en
  • 中国語の名称を取得する場合：zh
  • ログインユーザーの言語設定で取得する場合：user*
    *ログインユーザーの言語設定が「Webブラウザの設定にしたがう」の場合、
    Accept-Languageヘッダがあればその設定が反映され、
    Accept-Languageヘッダがなければcybozu.com共通管理の「ローカライズの設定」で設定された言語で取得されます。
  • デフォルトの名称を取得する場合：default
省略すると、デフォルトの名称が取得されます。

リクエストの例

送信するリクエストは、パラメータの送信方法によって異なります。パラメータ「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 文字列 フィールドの種類です。
  • CALC：計算
  • CATEGORY：カテゴリー
  • CHECK_BOX：チェックボックス
  • CREATED_TIME：作成日時
  • CREATOR：作成者
  • DATE：日付
  • DATETIME：日時
  • DROP_DOWN：ドロップダウン
  • FILE：添付ファイル
  • GROUP：グループ
  • GROUP_SELECT：グループ選択
  • LINK：リンク
  • MODIFIER：更新者
  • MULTI_LINE_TEXT：文字列（複数行）
  • MULTI_SELECT：複数選択
  • NUMBER：数値、またはルックアップ *
  • ORGANIZATION_SELECT：組織選択
  • RADIO_BUTTON：ラジオボタン
  • RECORD_NUMBER：レコード番号
  • REFERENCE_TABLE：関連レコード一覧
  • RICH_TEXT：リッチエディター
  • SINGLE_LINE_TEXT：文字列（1行）、またはルックアップ *
  • STATUS：プロセス管理機能のステータス
  • STATUS_ASSIGNEE：プロセス管理機能の作業者
  • SUBTABLE：テーブル
  • TIME：時刻
  • UPDATED_TIME：更新日時
  • USER_SELECT：ユーザー選択
*：ルックアップフィールドは、参照先のフィールドと同じ種類として表されます。
properties.（フィールドコード）.noLabel 真偽値 フィールド名を非表示にするかどうかの設定です。
  • true：非表示
  • false：表示
properties.（フィールドコード）.required 真偽値 入力が必須かどうかの設定です。
  • true：必須
  • false：任意
properties.（フィールドコード）.unique 真偽値 重複を禁止するかどうかの設定です。
  • true：重複を禁止する
  • false：重複を許可する
properties.（フィールドコード）.maxValue 文字列 最大値です。未設定の場合は空です。
properties.（フィールドコード）.minValue 文字列 最小値です。未設定の場合は空です。
properties.（フィールドコード）.maxLength 文字列 最大文字数です。未設定の場合は空です。
properties.（フィールドコード）.minLength 文字列 最小文字数です。未設定の場合は空です。
properties.（フィールドコード）.defaultValue 文字列または配列 初期値です。複数の初期値を設定できるフィールドでは、配列が返ります。
properties.（フィールドコード）.defaultNowValue 真偽値 レコード登録時の日時を初期値にするかどうかの設定です。
  • true：レコード登録時の日時を初期値にする
  • false：レコード登録時の日時を初期値にしない
properties.（フィールドコード）.options オブジェクト 選択肢の設定を表すオブジェクトです。
properties.（フィールドコード）.options.（選択肢名）.label 文字列 選択肢名です。
properties.（フィールドコード）.options.（選択肢名）.index 文字列 選択肢の順番（昇順）です。
properties.（フィールドコード）.align 文字列 選択肢の並びです。
  • HORIZONTAL：横
  • VERTICAL：縦
properties.（フィールドコード）.expression 文字列 自動計算式です。未設定の場合は空です。
properties.（フィールドコード）.hideExpression 真偽値 計算フィールドの計算式を非表示にするかどうかの設定です。
  • true：非表示
  • false：表示
properties.（フィールドコード）.digit 真偽値 数値の桁区切りを表示するかどうかの設定です。
  • true：桁区切りを表示する
  • false：桁区切りを表示しない
properties.（フィールドコード）.thumbnailSize 文字列 画像のサムネイルの大きさ（ピクセル単位）です。
properties.（フィールドコード）.protocol 文字列 リンクの種類です。
  • WEB：Webサイト
  • CALL：電話番号
  • MAIL：メールアドレス
properties.（フィールドコード）.format 文字列 計算フィールドの表示形式です。
  • NUMBER：数値（例：1000）
  • NUMBER_DIGIT：数値（例：1,000）
  • DATETIME：日時（例：2012-08-06 2:03）
  • DATE：日付（例：2012-08-06）
  • TIME：時刻（例：2:03）
  • HOUR_MINUTE：時間（例：26時間3分）
  • DAY_HOUR_MINUTE：時間（例：1日2時間3分）
properties.（フィールドコード）.displayScale 文字列 小数点以下の表示桁数です。未設定の場合は空です。
properties.（フィールドコード）.unit 文字列 単位記号です。
properties.（フィールドコード）.unitPosition 文字列 単位記号の表示位置です。
  • BEFORE：フィールドの前に付ける
  • AFTER：フィールドの後ろに付ける
properties.（フィールドコード）.entities 配列 選択肢のユーザーを表す配列です。未設定の場合は空です。
properties.（フィールドコード）.entities[].code 文字列 選択肢のユーザー、グループ、または組織のコードです。
properties.（フィールドコード）.entities[].type 文字列 値の種類です。
  • USER：ユーザー
  • GROUP：グループ
  • ORGANIZATION：組織
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 真偽値 グループ内のフィールドを表示するかどうかの設定です。
  • true：表示
  • false：非表示
properties.（フィールドコード）.fields オブジェクト テーブル内のフィールドを表すオブジェクトです。オブジェクトのパラメータは、「properties」パラメータと同じです。
properties.（フィールドコード）.enabled 真偽値

機能が有効かどうかの設定です。このパラメータは、ステータスフィールド、およびカテゴリーフィールドでのみ出力されます。

  • ステータスフィールドの場合
    • true：プロセス管理機能が有効
    • false：プロセス管理機能が無効
  • カテゴリーフィールドの場合
    • true：カテゴリー機能が有効
    • false：カテゴリー機能が無効
revision 文字列 アプリの設定のリビジョン番号です。

 

レスポンスの例

JavaScriptサンプル

kintone REST API

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 文字列 行の種類です。
  • ROW：標準の行です。
  • SUBTABLE：テーブルです。
  • GROUP：グループフィールドです。
layout[].code 文字列 テーブル、またはグループのコードです。いずれでもない行では、このパラメータは出力されません。
layout[].fields 配列 行に含まれるフィールドを表す配列です。
layout[].fields[].type 文字列 フィールドの種類です。
  • CALC：計算
  • CHECK_BOX：チェックボックス
  • CREATED_TIME：作成日時
  • CREATOR：作成者
  • DATE：日付
  • DATETIME：日時
  • DROP_DOWN：ドロップダウン
  • FILE：添付ファイル
  • GROUP_SELECT：グループ選択
  • HR：罫線
  • LABEL：ラベル
  • LINK：リンク
  • MODIFIER：更新者
  • MULTI_LINE_TEXT：文字列（複数行）
  • MULTI_SELECT：複数選択
  • NUMBER：数値、またはルックアップ *
  • ORGANIZATION_SELECT：組織選択
  • RADIO_BUTTON：ラジオボタン
  • RECORD_NUMBER：レコード番号
  • REFERENCE_TABLE：関連レコード一覧
  • RICH_TEXT：リッチエディター
  • SINGLE_LINE_TEXT：文字列（1行）、またはルックアップ *
  • SPACER：スペース
  • TIME：時刻
  • UPDATED_TIME：更新日時
  • USER_SELECT：ユーザー選択
*：ルックアップフィールドは、参照先のフィールドと同じ種類として表されます。
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サンプル

kintone REST API

XMLHttpRequest

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

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

Avatar
takasakai

「フィールドの一覧を取得する」のレスポンスのパラメータが「properties.（フィールドコード）.referenceTable.fliterCond」となっている行がありますが、「properties.（フィールドコード）.referenceTable.filterCond」ではないでしょうか。

Avatar
cybozu Development team

takasakai 様

お世話になっております。
cybozu developer network 事務局です。

ご指摘ありがとうございます。

ご指摘頂いた通り、こちら正しくは「properties.（フィールドコード）.referenceTable.filterCond」です。

該当箇所修正致しました。

 

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

Avatar
Yoshiyuki Kuwajima

フィールドの一覧を取得するAPI(/form/fields.json)のレスポンスJSONの各フィールド項目ですが、Code順でもなく、フォーム設計情報（画面）の順番でも無いようですが、並び順の仕様を教えて頂けますでしょうか？

Avatar
cybozu Development team

Yoshiyuki Kuwajima 様

お世話になっております。
cybozu developer network 事務局です。

/form/fields.json　のレスポンスJSONの並び順ですが、不定となっております。
フィールドの並び順を参照したい場合は、layout.jsonをご利用ください。

宜しくお願い致します。

Avatar
Yoshiyuki Kuwajima

事務局ご担当者様

ご回答ありがとうございます。不定との旨理解いたしました。

Avatar
Jo

cybozu Development team　さま

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

テスト環境のフィールドの一覧を取得(/k/v1/preview/app/form/fields)のレスポンスが
掲載されている形式と異なるようです。

console.logに出してみたところ
運用環境の場合は"properties"以下がフィールドコードをkeyとしたobjectですが、
テスト環境の場合は"properties"以下が配列になっています。

ご確認お願いします。

Avatar
cybozu Development team

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 などでマスキングしていただければと思います）

よろしくお願いいたします。

Avatar
Jo

cybozu Development team　さま

 

ご指摘の通り、掲載されているrespは正確な形式です。

大変失礼致しました。

Avatar
cybozu Development team

Jo 様

お世話になっております。 
cybozu developer network 事務局です。

ご確認いただきありがとうございます。
記載の内容で問題なかったとのこと、承知いたしました。

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

Avatar
LunaPapa

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

テスト環境と運用環境で異なる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に関して「テスト環境」と書かれているのはどちらを指しているのでしょうか？

よろしくお願いします。

Avatar
cybozu Development team

LunaPapa 様

API呼び出しのURIに関しての「テスト環境」は、記載②の、kintone アプリの動作テスト環境に該当します。

①はテスト用の別の環境、という意味で使っています。

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