kintone APIドキュメント

フィールドを追加する

目次

フィールドを追加する

固定リンクがコピーされました

フォームにフィールドを追加します。

このAPIは、動作テスト環境のアプリを変更します。
本番環境に変更を反映する場合、このAPIを実行した後に、アプリ設定を運用環境へ反映するAPIを実行してください。
アプリ設定を運用環境へ反映するAPI

URL

固定リンクがコピーされました

通常のアプリ
https://sample.cybozu.com/k/v1/preview/app/form/fields.json
ゲストスペースのアプリ
https://sample.cybozu.com/k/guest/SPACE_ID/v1/preview/app/form/fields.json

HTTPメソッド

固定リンクがコピーされました

POST

必要なアクセス権

固定リンクがコピーされました

  • アプリ管理権限

リクエスト

固定リンクがコピーされました

パラメーター
パラメーター名 型 必須 説明
app 数値または文字列 必須 アプリID
properties オブジェクト 必須 フィールドの設定
properties.フィールドコード オブジェクト 必須 各フィールドの設定
フィールドコードには追加するフィールドのフィールドコードを指定します。
フィールドコードに使用できる文字は、フィールドコードに使用できる文字を参照してください。
フィールドコードに使用できる文字 (External link)
properties.フィールドコード.type 文字列 必須 フィールドの種類
  • GROUP：グループ
  • GROUP_SELECT：グループ選択
  • CHECK_BOX：チェックボックス
  • SUBTABLE：テーブル
  • DROP_DOWN：ドロップダウン
  • USER_SELECT：ユーザー選択
  • RADIO_BUTTON：ラジオボタン
  • RICH_TEXT：リッチエディター
  • LINK：リンク
  • REFERENCE_TABLE：関連レコード一覧
  • CALC：計算
  • TIME：時刻
  • NUMBER：数値
  • ORGANIZATION_SELECT：組織選択
  • FILE：添付ファイル
  • DATETIME：日時
  • DATE：日付
  • MULTI_SELECT：複数選択
  • SINGLE_LINE_TEXT：文字列（1行）
  • MULTI_LINE_TEXT：文字列（複数行）
ルックアップフィールドは、コピー元のフィールドのフィールドタイプを指定します。
properties.フィールドコード.code 文字列 必須 フィールドコード
フィールドコードと同じ値を指定します。
properties.フィールドコード.label 文字列 条件必須 フィールド名
テーブルでは、このパラメーターの指定は不要です。
properties.フィールドコード.noLabel 真偽値または文字列 省略可 フィールド名を非表示にするかどうか
  • true：非表示にする
  • false：表示する
省略すると「false」が設定されます。
properties.フィールドコード.required 真偽値または文字列 省略可 入力が必須かどうか
  • true：必須
  • false：任意
省略すると「false」が設定されます。
properties.フィールドコード.unique 真偽値または文字列 省略可 重複を禁止するかどうか
  • true：重複を禁止する
  • false：重複を許可する
省略すると「false」が設定されます。
properties.フィールドコード.maxValue 数値または文字列 省略可 最大値
properties.フィールドコード.minValue 数値または文字列 省略可 最小値
properties.フィールドコード.maxLength 数値または文字列 省略可 最大文字数
properties.フィールドコード.minLength 数値または文字列 省略可 最小文字数
properties.フィールドコード.defaultValue 文字列または配列 省略可 初期値
複数の初期値を設定できるフィールドでは、配列形式で指定します。
defaultNowValueを指定した場合、defaultNowValueの値が設定されます。
ユーザー選択／グループ選択／組織選択フィールドの場合、codeとtypeをキーにもつオブジェクトの配列を指定します。
properties.フィールドコード.defaultValue[].type 文字列 条件必須 ユーザー選択／グループ選択／組織選択フィールドの場合の初期値の種類
defaultValueを指定する場合、必須です。
  • USER：ユーザー
  • GROUP：グループ
  • ORGANIZATION：組織
  • FUNCTION：関数
properties.フィールドコード.defaultValue[].code 文字列 条件必須 ユーザー選択／グループ選択／組織選択フィールドの場合の初期値のコード
defaultValueを指定する場合、必須です。
  • ユーザー選択フィールドの場合、次のいずれかの値を指定できます。
    • ユーザーのログイン名
    • グループコード
    • 組織コード
    • 関数名（LOGINUSER()のみ）
    ゲストスペースのアプリでは、ユーザー、グループ、関数名のみ指定できます。
  • グループ選択フィールドの場合は、グループコードを指定できます。
  • 組織選択フィールドの場合は、次のいずれかの値を指定できます。
    • 組織コード
    • 関数名（PRIMARY_ORGANIZATION()のみ）
削除済みや無効なユーザー／グループ／組織は指定できません。
properties.フィールドコード.defaultNowValue 真偽値または文字列 省略可 レコード登録時の日時を初期値にするかどうか
  • true：レコード登録時の日時を初期値にする
  • false：レコード登録時の日時を初期値にしない
省略すると「false」が設定されます。
properties.フィールドコード.options オブジェクト 条件必須 選択肢の設定
ラジオボタンなど、選択肢を指定できるフィールドでは、必須です。
properties.フィールドコード.options.選択肢名 オブジェクト 条件必須 各選択肢の設定
選択肢名には追加する選択肢の項目名を指定します。
optionsを指定する場合は必須です。
properties.フィールドコード.options.選択肢名.label 文字列 条件必須 選択肢名
選択肢名と同じ値を指定します。
optionsを指定する場合は必須です。
properties.フィールドコード.options.選択肢名.index 数値または文字列 条件必須 選択肢の順番
数値で指定します。指定した数値の昇順で選択肢が並びます。
optionsを指定する場合は必須です。
properties.フィールドコード.align 文字列 省略可 選択肢の並び
  • HORIZONTAL：横にする
  • VERTICAL：縦にする
省略すると「HORIZONTAL」が設定されます。
properties.フィールドコード.expression 文字列 条件必須 自動計算式
計算フィールドでは必須です。
properties.フィールドコード.hideExpression 真偽値または文字列 省略可 計算フィールドの計算式を非表示にするかどうか
  • true：非表示にする
  • false：表示する場合
省略すると「false」が設定されます。
properties.フィールドコード.digit 真偽値または文字列 省略可 数字の桁区切りを表示するかどうか
  • true：表示する
  • false：表示しない場合
省略すると「false」が設定されます。
properties.フィールドコード.thumbnailSize 数値または文字列 省略可 ピクセル単位でのサムネイル画像の大きさ
次のいずれかの値を指定します。
  • 50
  • 150
  • 250
  • 500
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分）
省略すると「NUMBER」が設定されます。
properties.フィールドコード.displayScale 数値または文字列 省略可 小数点以下の表示桁数
properties.フィールドコード.unit 文字列 省略可 単位記号
properties.フィールドコード.unitPosition 文字列 省略可 単位記号の表示位置
  • BEFORE：フィールドの前に付ける
  • AFTER：フィールドの後ろに付ける
省略すると「BEFORE」が設定されます。
properties.フィールドコード.entities 配列 省略可 ユーザー選択／組織選択／グループ選択フィールドの選択肢
properties.フィールドコード.entities[].type 文字列 条件必須 選択肢の種類
entitiesを指定する場合は必須です。
  • USER：ユーザー
  • GROUP：グループ
  • ORGANIZATION：組織
properties.フィールドコード.entities[].code 文字列 条件必須 選択肢のコード
entitiesを指定する場合は必須です。
  • ユーザー選択フィールドの場合、次のいずれかの値を指定します。
    • ユーザーのログイン名
    • グループコード
    • 組織コード
    ゲストスペースのアプリでは、ユーザーかグループのみ指定できます。
  • グループ選択フィールドの場合は、グループコードを指定します。
  • 組織選択フィールドの場合は、組織コードを指定します
削除済みや無効なユーザー／グループ／組織コードは指定できません。
properties.フィールドコード.referenceTable オブジェクト 条件必須 関連レコード一覧フィールドの設定
関連レコード一覧フィールドを追加する場合は必須です。
properties.フィールドコード.referenceTable.relatedApp オブジェクト 条件必須 「参照するアプリ」の設定
referenceTableを指定する場合は必須です。
properties.フィールドコード.referenceTable.relatedApp.app 数値または文字列 条件必須 「参照するアプリ」に指定するアプリのアプリID
referenceTableを指定する場合、appまたはcodeが必須です。
両方指定するとcodeの値が設定されます。
properties.フィールドコード.referenceTable.relatedApp.code 文字列 条件必須 「参照するアプリ」に指定するアプリのコード
referenceTableを指定する場合、appまたはcodeが必須です。
両方指定するとcodeの値が設定されます。
properties.フィールドコード.referenceTable.condition オブジェクト 条件必須 「表示するレコードの条件」の設定
referenceTableを指定する場合は必須です。
properties.フィールドコード.referenceTable.condition.field 文字列 条件必須 「表示するレコードの条件」に指定する、関連レコード一覧フィールドと同じアプリのフィールドコード
referenceTableを指定する場合は必須です。
properties.フィールドコード.referenceTable.condition.relatedField 文字列 条件必須 「表示するレコードの条件」に指定する、関連レコード一覧フィールドが参照するアプリのフィールドコード
referenceTableを指定する場合は必須です。
properties.フィールドコード.referenceTable.fliterCond 文字列 省略可 「さらに絞り込む条件」の設定
クエリ形式で指定します。クエリ形式の詳細は次のページを参照してください。
クエリの書き方
properties.フィールドコード.referenceTable.displayFields 配列 条件必須 「表示するフィールド」に指定するフィールドのフィールドコードの一覧
referenceTableを指定する場合は必須です。
properties.フィールドコード.referenceTable.sort 文字列 省略可 レコードのソートの設定
クエリ形式で指定します。クエリ形式の詳細は次のページを参照してください。
クエリの書き方
properties.フィールドコード.referenceTable.size 数値または文字列 省略可 一度に表示する最大レコード数
次のいずれかの値を指定します。
  • 1
  • 3
  • 5
  • 10
  • 20
  • 30
  • 40
  • 50
省略すると「5」が設定されます。
properties.フィールドコード.lookup オブジェクト 省略可 ルックアップフィールドの設定
ルックアップフィールドを追加する場合は必須です。
properties.フィールドコード.lookup.relatedApp オブジェクト 条件必須 「関連付けるアプリ」の設定
lookupを指定する場合は必須です。
properties.フィールドコード.lookup.relatedApp.app 数値または文字列 条件必須 関連付けるアプリのアプリID
lookupを指定する場合、appまたはcodeが必須です。
両方指定するとcodeの値が設定されます。
properties.フィールドコード.lookup.relatedApp.code 文字列 条件必須 関連付けるアプリのコード
lookupを指定する場合、appまたはcodeが必須です。
両方指定するとcodeの値が設定されます。
properties.フィールドコード.lookup.relatedKeyField 文字列 条件必須 「コピー元のフィールド」に指定するフィールドコード
lookupを指定する場合は必須です。
properties.フィールドコード.lookup.fieldMappings 配列 省略可 「他のフィールドのコピー」の設定の一覧
properties.フィールドコード.lookup.fieldMappings[].field 文字列 条件必須 「他のフィールドのコピー」のコピー先に指定するフィールドコード
lookup.fieldMappingsを指定する場合は必須です。
properties.フィールドコード.lookup.fieldMappings[].relatedField 文字列 条件必須 「他のフィールドのコピー」のコピー元に指定するフィールドコードを指定します。
lookup.fieldMappingsを指定する場合、必須です。
properties.フィールドコード.lookup.lookupPickerFields 配列 省略可 「コピー元のレコードの選択時に表示するフィールド」の設定の一覧
フィールドコードの配列を指定します。
properties.フィールドコード.lookup.filterCond 文字列 省略可 絞り込みの初期設定
クエリ形式で指定します。クエリ形式の詳細は次のページを参照してください。
クエリの書き方
properties.フィールドコード.lookup.sort 文字列 省略可 ソートの初期設定
クエリ形式で指定します。クエリ形式の詳細は次のページを参照してください。
クエリの書き方
properties.フィールドコード.openGroup 真偽値または文字列 省略可 グループ内のフィールドを表示するかどうか
  • true：表示する
  • false：非表示にする
省略すると「false」が設定されます
properties.フィールドコード.fields オブジェクト 省略可 テーブル内のフィールド
オブジェクトの構造は、propertiesと同じです。
テーブルを追加する場合は必須です。
revision 数値または文字列 省略可 期待しているリビジョン番号
実際のリビジョン番号と一致しない場合はエラーとなり、フィールドは追加されません。
値に「-1」を指定する、または指定しなかった場合はリビジョン番号は検証されません。
リクエストの例
ヘッダー
1
2
3
4

{
  "X-Cybozu-API-Token": "API_TOKEN",
  "Content-Type": "application/json"
}

リクエストヘッダーの詳細は共通仕様を参照してください。
kintone REST APIの共通仕様

ボディ
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292

{
  "app": 1,
  "revision": 2,
  "properties": {
    "文字列__1行_": {
      "type": "SINGLE_LINE_TEXT",
      "code": "文字列1行",
      "label": "文字列 (1行)",
      "noLabel": false,
      "required": false,
      "minLength": "",
      "maxLength": "",
      "expression": "",
      "hideExpression": false,
      "unique": false,
      "defaultValue": ""
    },
    "リッチエディター": {
      "type": "RICH_TEXT",
      "code": "リッチエディター",
      "label": "リッチエディター",
      "noLabel": false,
      "required": false,
      "defaultValue": ""
    },
    "文字列__複数行_": {
      "type": "MULTI_LINE_TEXT",
      "code": "文字列複数行",
      "label": "文字列 (複数行)",
      "noLabel": false,
      "required": false,
      "defaultValue": ""
    },
    "数値": {
      "type": "NUMBER",
      "code": "数値",
      "label": "数値",
      "noLabel": false,
      "required": false,
      "minValue": "",
      "maxValue": "",
      "digit": false,
      "unique": false,
      "defaultValue": "",
      "displayScale": "",
      "unit": "",
      "unitPosition": "BEFORE"
    },
    "計算": {
      "type": "CALC",
      "code": "計算",
      "label": "計算",
      "noLabel": false,
      "required": false,
      "expression": "数値",
      "format": "NUMBER",
      "displayScale": "",
      "hideExpression": false,
      "unit": "",
      "unitPosition": "BEFORE"
    },
    "ラジオボタン": {
      "type": "RADIO_BUTTON",
      "code": "ラジオボタン",
      "label": "ラジオボタン",
      "noLabel": false,
      "required": true,
      "options": {
        "sample1": {
          "label": "sample1",
          "index": "0"
        },
        "sample2": {
          "label": "sample2",
          "index": "1"
        }
      },
      "defaultValue": "sample1",
      "align": "HORIZONTAL"
    },
    "チェックボックス": {
      "type": "CHECK_BOX",
      "code": "チェックボックス",
      "label": "チェックボックス",
      "noLabel": false,
      "required": false,
      "options": {
        "sample1": {
          "label": "sample1",
          "index": "0"
        },
        "sample2": {
          "label": "sample2",
          "index": "1"
        }
      },
      "defaultValue": [],
      "align": "HORIZONTAL"
    },
    "複数選択": {
      "type": "MULTI_SELECT",
      "code": "複数選択",
      "label": "複数選択",
      "noLabel": false,
      "required": false,
      "options": {
        "sample1": {
          "label": "sample1",
          "index": "0"
        },
        "sample2": {
          "label": "sample2",
          "index": "1"
        },
        "sample3": {
          "label": "sample3",
          "index": "2"
        },
        "sample4": {
          "label": "sample4",
          "index": "3"
        }
      },
      "defaultValue": []
    },
    "ドロップダウン": {
      "type": "DROP_DOWN",
      "code": "ドロップダウン",
      "label": "ドロップダウン",
      "noLabel": false,
      "required": false,
      "options": {
        "sample1": {
          "label": "sample1",
          "index": "0"
        },
        "sample2": {
          "label": "sample2",
          "index": "1"
        }
      },
      "defaultValue": ""
    },
    "日付": {
      "type": "DATE",
      "code": "日付",
      "label": "日付",
      "noLabel": false,
      "required": false,
      "unique": false,
      "defaultValue": "",
      "defaultNowValue": true
    },
    "時刻": {
      "type": "TIME",
      "code": "時刻",
      "label": "時刻",
      "noLabel": false,
      "required": false,
      "defaultValue": "",
      "defaultNowValue": true
    },
    "日時": {
      "type": "DATETIME",
      "code": "日時",
      "label": "日時",
      "noLabel": false,
      "required": false,
      "unique": false,
      "defaultValue": "",
      "defaultNowValue": true
    },
    "添付ファイル": {
      "type": "FILE",
      "code": "添付ファイル",
      "label": "添付ファイル",
      "noLabel": false,
      "required": false,
      "thumbnailSize": "150"
    },
    "リンク": {
      "type": "LINK",
      "code": "リンク",
      "label": "リンク",
      "noLabel": false,
      "required": false,
      "protocol": "WEB",
      "minLength": "",
      "maxLength": "",
      "unique": false,
      "defaultValue": ""
    },
    "ユーザー選択": {
      "type": "USER_SELECT",
      "code": "ユーザー選択",
      "label": "ユーザー選択",
      "noLabel": false,
      "required": false,
      "entities": [],
      "defaultValue": []
    },
    "組織選択": {
      "type": "ORGANIZATION_SELECT",
      "code": "組織選択",
      "label": "組織選択",
      "noLabel": false,
      "required": false,
      "entities": [],
      "defaultValue": []
    },
    "グループ選択": {
      "type": "GROUP_SELECT",
      "code": "グループ選択",
      "label": "グループ選択",
      "noLabel": false,
      "required": false,
      "entities": [],
      "defaultValue": []
    },
    "関連レコード一覧": {
      "type": "REFERENCE_TABLE",
      "code": "関連レコード一覧",
      "label": "関連レコード一覧",
      "noLabel": false,
      "referenceTable": {
        "relatedApp": {
          "app": "2",
          "code": ""
        },
        "condition": {
          "field": "レコード番号",
          "relatedField": "数値"
        },
        "filterCond": "",
        "displayFields": ["文字列__1行_"],
        "sort": "レコード番号 desc",
        "size": "5"
      }
    },
    "ルックアップ": {
      "type": "NUMBER",
      "code": "ルックアップ",
      "label": "ルックアップ",
      "noLabel": false,
      "required": false,
      "lookup": {
        "relatedApp": {
          "app": "2",
          "code": ""
        },
        "relatedKeyField": "レコード番号",
        "fieldMappings": [
          {
            "field": "ユーザー選択",
            "relatedField": "作成者"
          }
        ],
        "lookupPickerFields": [],
        "filterCond": "",
        "sort": "レコード番号 desc"
      }
    },
    "グループ": {
      "type": "GROUP",
      "code": "グループ",
      "label": "グループ",
      "noLabel": false,
      "openGroup": false
    },
    "Table": {
      "type": "SUBTABLE",
      "code": "Table",
      "label": "Table",
      "noLabel": false,
      "fields": {
        "文字列__1行__0": {
          "type": "SINGLE_LINE_TEXT",
          "code": "文字列1行",
          "label": "文字列 (1行)",
          "noLabel": false,
          "required": false,
          "minLength": "",
          "maxLength": "",
          "expression": "",
          "hideExpression": false,
          "unique": false,
          "defaultValue": ""
        }
      }
    }
  }
}

レスポンス

固定リンクがコピーされました

プロパティ
プロパティ名 型 説明
revision 文字列 アプリの設定を変更したあとのリビジョン番号
レスポンスの例
1
2
3

{
  "revision": "1"
}

サンプルコード

固定リンクがコピーされました

curlを使ったリクエスト
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

curl -X POST 'https://sample.cybozu.com/k/v1/preview/app/form/fields.json' \
  -H 'X-Cybozu-API-Token: API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "app": 1,
    "revision": 1,
    "properties": {
      "文字列1行_": {
        "type": "SINGLE_LINE_TEXT",
        "code": "文字列1行",
        "label": "文字列 (1行)",
        "noLabel": false,
        "required": false,
        "minLength": ",
        "maxLength": ",
        "expression": ",
        "hideExpression": false,
        "unique": false,
        "defaultValue": "
      },
    },
  }'
kintone.api()を使ったリクエスト

kintone.api()の詳細は、次のページを参照してください。
kintone REST APIリクエストを送信する 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

const body = {
  app: kintone.app.getId(),
  revision: 2,
  properties: {
    文字列1行: {
      type: 'SINGLE_LINE_TEXT',
      code: '文字列1行',
      label: '文字列 (1行)',
      noLabel: false,
      required: false,
      minLength: '',
      maxLength: '',
      expression: '',
      hideExpression: false,
      unique: false,
      defaultValue: ''
    }
  }
};

await kintone.api(kintone.api.url('/k/v1/preview/app/form/fields.json', true), 'POST', body);

制限事項

固定リンクがコピーされました

次のフィールドは追加できません。

  • ステータス
  • 作業者
  • カテゴリー