User API的共通规格

aki发表于:2019年10月28日 13:18:49更新于:2022年07月14日 16:39:14

Index

概要

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

协议

HTTPS

接口

JSON

文字编码

UTF-8

转义符号

使用“\”。

验证

验证方式

密码验证

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

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

会话验证

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

验证方式的优先顺序

优先顺序如下:

  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时执行以下请求头部。

头部名称内容
Host(子域名).cybozu.cn:443

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数据的应答。

key
message按所指定的本地语言显示错误信息。
id错误ID。查询时可使用。
code表示错误类型的代码。

例)

{"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。
基本上按照如下流程使用。

0015db7a2ec32c53bdd61478276135c

(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格式的数据。
0015db7a2571038adf109caf9d8352f(1) 用JSON格式准备用户信息等 (手动)
(2) 执行导入JSON的API
(3) 返回处理结果(例:导入用户API(JSON)的应答)

导出

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

(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()。

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


    注意:贴代码时请注意格式并使用"代码语言",与本文无关的问题请至“讨论社区”提问。