Index

• 概要

• 协议

• 接口

• 文字编码

• 转义符号

• 验证

      验证方式

      验证方式的优先顺序

• 在安全设置的环境中使用API

      设置IP地址限制时

      设置SAML身份验证时

      设置双重身份验证时

• 请求头部

• 应答

• 导入

• 导出

• 其他

概要

此API可用于导入/导出用户、组、组织、职务等。

协议

HTTPS

接口

JSON

文字编码

UTF-8

转义符号

使用“\”。

验证

验证方式

密码验证

在请求头部里添加“X-Cybozu-Authorization”并对其赋值。值为将登录名称和密码通过BASE64编码之后的文字。

// 登录名为"Administrator"，密码为“cybozu”时
X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=

会话验证

要从应用于kintone的JavaScript文件中运行User API时，可使用会话验证。
在XMLHttpRequest或Fetch API上，运行POST/POT/DELETE方法的API时，请添加以下令牌。

• 在kintone上运行User API：CSRF令牌
  

验证方式的优先顺序

优先顺序如下：

1. 密码验证

2. 会话验证

在安全设置的环境中使用API

设置IP地址限制时

Basic身份验证

除了IP地址限制外，若设置了Basic身份验证，请在请求头部中添加【Authorization】头部。

• 将【Basic】和【登录名:密码】通过BASE64编码后得到的值指定为【Authorization】头部的值。
        ⚬【Basic】和【登录名:密码】之间需加半角空格。
        ⚬【Basic】无需经过 BASE64编码。

// 登录名为【Administrator】，密码为【cybozu】时 
Authorization:Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=

客户端证书

客户端证书可以通过允许用户使用“安全访问”来颁发。
有关如何允许使用安全访问和颁发客户端证书的详细信息，请参阅设置SecureAccess。

• 请求的 URL 必须添加 .s。
  例如：若 URL 为 https://sample.cybozu.cn ，则为 https://sample.s.cybozu.cn。

设置SAML身份验证时

设置SAML验证时，可以在cybozu.cn的密码验证、会话验证中使用User API。
密码验证需要使用cybozu.cn登录名和密码。
如设置了限制登录cybozu.cn时只能使用SAML身份验证，通过密码验证的方式仅cybozu.cn管理员可执行 User API。对于会话验证，不受此限制。

设置双重身份验证时

启用了双重身份验证的cybozu.cn用户帐号不能使用密码验证。
请以密码身份验证以外的身份验证方法执行，或提供禁用双重身份验证的协作用户。

请求头部

在执行API时执行以下请求头部。

cybozu中使用Basic验证时的请求头部范例

POST /v1/csv/user.json HTTP/1.1
    Host: example.cybozu.cn:443
    X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=
    Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=
    Content-type: application/json

应答

如果HTTP的状态代码为“200”则表示正常，其他状态代码时将报错并结束处理。
报错时，会返回含有以下内容的JSON数据的应答。

例)

{"message":"JSON字符串不正确。","id":"1505999166-897850006","code":"CB_IJ01"}

含有应答头部的范例

HTTP/1.1 400 Bad Request
    Date: Wed, 21 Mar 2012 13:48:31 GMT
    Server: Apache
    Strict-Transport-Security: max-age=315360000 ; includeSubDomains
    X-Content-Type-Options: nosniff
    X-Cybozu-Error: CB_IJ01
    Content-Type: application/json;charset=UTF-8
    Set-Cookie: JSESSIONID=6DDFFAAA58BAB36D2021589F80EE31C3; Path=/; Secure; HttpOnly
    Vary: Accept-Encoding,User-Agent
    Connection: close
    Transfer-Encoding: chunked
     
    {"message":"JSON字符串不正确。","id":"1505999166-897850006","code":"CB_IJ01"}

导入

CSV

导入CSV的API是异步处理的API。
基本上按照如下流程使用。

(1)用CSV准备用户信息或组织信息等 (手动)
(2) 导入CSV (文件上传API)
(3) 返回文件key (上传文件API的应答)
(4) 将文件key发送给需要执行导入的处理（例：导入用户API(CSV)（日文））
(5) 返回作业编号(例：导入用户API(CSV)的应答)
(6)发送工作编号，确认 (4) 的处理是否已结束 (确认结果的API（日文）)
(7) 返回处理结果 (确认结果的API的应答) ※如果处理结果为"处理中"，重复 (6) 。

关于执行API时要指定的数据，上传CSV时，发送CSV文件和文件key的API用JSON格式生成文件key，并将其作为请求正文发送。

JSON

JSON导入API为同步处理API。
和导入CSV不一样，可直接发送JSON格式的数据。
(1) 用JSON格式准备用户信息等 (手动)
(2) 执行导入JSON的API
(3) 返回处理结果（例：导入用户API(JSON)的应答）

导出

导出API是同步处理的API。
导出结果可以通过CSV文件或JSON格式输出。

(1) 执行导出API
(2) 返回CSV或者JSON（导出API的应答）
例：导出用户API(CSV) （日文）／ 导出用户API(JSON)

其他

关于“*”（星号）的使用说明

原则上，要上传的CSV文件的字段值指定为“*”时，表示该值不会被更新。
但是，用户信息的CSV，以下两点不同与上述。

• 登录名中不可指定“*”。

• 自定义项目指定为“*"时，项目将被设定为“*”。

用kintone JavaScript API执行时

用 kintone JavaScript API来执行User API时，可以使用kintone.api() 。

※如下User API不可以使用kintone.api()。

• 文件上传API

• URI的末尾为.json之外的情况（导出用户的API(CSV)（日文）等）

如果使用 kintone.api() 发送URI大于4KB的GET请求，则POST请求将与X-HTTP-Method-Override标头一起发送。