获取kintone REST API的schema信息

aki发表于:2016年12月09日 14:54:33更新于:2023年02月17日 13:19:45

获取kintone REST API的schema信息

获取kintone REST API的schema信息时所使用的API。

无法获取以下API的schema信息。

HTTP 方法

GET

URI

https://(子域名).cybozu.cn/k/v1/apis/*.json 

URI是在 获取kintone API列表 中获取到的URL。

必要的访问权限

※未登录用户也可执行。

※空间/用户/来宾空间等功能未启用的情况下也可以获取API信息。

请求参数

应答

参数名称值的类型内 容
id字符串

要获取schema信息的应用的API的ID。和 获取kintone REST API列表 的apis.(key) 一样

例如:获取一条记录的API,key就是“record/get”,URL的路径是https://sample.cybozu.cn/k/v1/apis/record/get.json 

baseUrl字符串使用各API时所需要的最基本的URL。
path字符串API的路径。 baseUrl + path 为 API的URL 。
httpMethod字符串使用API时的HTTP方法。
request对象是API请求的schema信息。用 JSON Schema 表示。
response对象是API应答的schema信息。用 JSON Schema表示。
schemas对象在各API中通用的schema信息列表。 key是表示schema信息的字符串。通过 JSON Schema的$ref来参照。
应答的范例
{    
    "id": "records/get",    
    "baseUrl": "https://*******.cybozu.com/k/v1/",    
    "path": "records.json",    
    "httpMethod": "GET",    
    "request": {    
        "type": "object",    
         "required": ["app"],    
         "properties": {    
            "app": {    
                "type": "string",    
                "format": "long"    
            },    
            "fields": {    
                "type": "array",    
                "items": {    
                    "type": "string"    
                }    
            },    
            "query": {    
                "type": "string",    
                "format": "query"    
            },    
            "totalCount": {    
                "format": "boolean",    
                "type": "string"    
            }    
        }    
    },    
    "response": {    
        "type": "object",    
        "properties": {    
            "records": {    
                "type": "array",    
                "items": {    
                    "type": "object",    
                    "patternProperties": {    
                        "*": {    
                            "anyOf": [    
                                { "$ref": "CalcSimpleValue" },    
                                { "$ref": "CategorySimpleValue" },    
                                ...    
                            ],    
                            "type": "object"    
                        }    
                    }    
                }    
            },    
            "totalCount": {    
                "format": "long",    
                "type": "string"    
            }    
        }    
    },    
    "schemas": {    
        "SingleLineTextSimpleValue": {    
            "type": "object",    
            "properties": {    
                "type": {    
                    "type": "string",    
                    "enum": ["CATEGORY", "CREATED_TIME", ... ]    
                },    
                "value": { "type": "string" }    
            }    
        },    
        "MultipleLineTextSimpleValue": {    
            "type": "object",    
            "properties": {    
                "type": {    
                    "type": "string",    
                    "enum": [ "CATEGORY", "CREATED_TIME", ... ]    
                },    
                "value": { "type": "string" }    
            }    
        },    
        ...    
    }    
}

关于JSON Schema

在上述request、response、schemas中使用的JSON Schema以draft v4为基准。使用core和validation,不可使用hyper schema 。

type和format

除了在 JSON Schema中定义的格式外, 还定义以下格式来表示 kintone 参数的限制:

typeformat说明
stringlong-9223372036854775808 ~ 9223372036854775807 范围内的整数型
stringlocale"", "en", "ja" or "zh" 的字符串
stringboolean"true" or "false" 的字符串
stringemailEmail 形式的字符串
stringnumber实数类型
stringquerykintone 查询的写法。关于查询的写法请参考这里
stringdate-timeISO格式的日期时间字符串
stringtimezone表示时区的字符串

※ 关于kintone特有的 format ,今后可能会追加。

关于文件 API

发送文件的API (/k/v1/apis/json 的 POST)

JsonSchema 的request对象中虽然有kintone的内部类型信息,但实际请求需要用Multipart (多部分)格式发送。

获取文件的API (/k/v1/apis/json的 GET)

JsonSchema的response对象虽然为空,实际上文件会被下载。

JavaScript 范例

使用API请求发送 kintone REST API 请求

kintone.api(kintone.api.url('/k/v1/apis/record/get', true), 'GET', {}, function(resp) {    
    // success    
    console.log(resp);    
}, function(error) {    
    // error    
    console.log(error);    
});

使用 XMLHttpRequest 请求

var url = 'https://{subdomain}.cybozu.cn/k/v1/apis/record/get.json';
var xhr = new XMLHttpRequest();
xhr.open('GET', url);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
xhr.onload = function() {
    if (xhr.status === 200) {
        // success
        console.log(JSON.parse(xhr.responseText));
    } else {
        // error
        console.log(JSON.parse(xhr.responseText));
    }
};
xhr.send();