kintone API文件

新增欄位

information

本頁面使用機器翻譯而成。
機器翻譯免責聲明 (External link)

目錄

新增欄位

連結已複製

向表單新增欄位。

此 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：單行文字方塊
  • MULTI_LINE_TEXT：多行文字方塊
Lookup欄位指定從中複製該欄位的欄位類型。
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：網站地址
  • CALL：電話號碼
  • MAIL：電子郵件地址
properties.欄位代碼.format 字串 可省略 計算欄位的顯示格式
  • NUMBER：數值（例：1000）
  • NUMBER_DIGIT：數值（例：1000）
  • 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 物件 可省略 Lookup欄位的設定
如果要新增Lookup欄位，則為必填項。
properties.欄位代碼.lookup.relatedApp 物件 條件必填項 「要連結的應用程式」的設定
如果lookup指定，則為必填項。
properties.欄位代碼.lookup.relatedApp.app 數值或字串 部分條件下必須 要連結的應用程式的應用ID
如果指定了lookup，應用程式或代碼是必需的。
如果兩者都指定，將設置code 的值。
properties.欄位代碼.lookup.relatedApp.code 字串 條件必填項 要要連結的應用程式代碼
如果指定了lookup，應用程式或代碼是必需的。
如果兩者都指定，將設置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": {
    "單行文字方塊": {
      "type": "SINGLE_LINE_TEXT",
      "code": "單行文字方塊",
      "label": "單行文字方塊",
      "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": ["單行文字方塊"],
        "sort": "記錄編號 desc",
        "size": "5"
      }
    },
    "Lookup": {
      "type": "NUMBER",
      "code": "Lookup",
      "label": "Lookup",
      "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": {
        "單行文字方塊": {
          "type": "SINGLE_LINE_TEXT",
          "code": "單行文字方塊",
          "label": "單行文字方塊",
          "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": {
      "單行文字方塊": {
        "type": "SINGLE_LINE_TEXT",
        "code": "單行文字方塊",
        "label": "單行文字方塊",
        "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: {
    單行文字方塊: {
      type: 'SINGLE_LINE_TEXT',
      code: '單行文字方塊',
      label: '單行文字方塊',
      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);

限制

連結已複製

無法新增以下欄位：

  • 狀態
  • 執行者
  • 類別