概要
ユーザーやグループ、組織、役職などのインポート/エクスポート機能を持ったAPIです。
プロトコル
HTTPS
インターフェース
JSON
文字コード
UTF-8
エスケープ
「\」を使用します。
認証
パスワード認証
- リクエストヘッダに「X-Cybozu-Authorization」を追加し、その値として、ログイン名とパスワードをBASE64エンコードしたものを指定します。
// ログイン名が「Administrator」、パスワードが「cybozu」の場合
X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=
- セキュアアクセス設定環境にログインしたユーザーが、ログインユーザーと異なるユーザーの認証情報を使って JavaScript カスタマイズでの REST API を実行する場合、設定が必要です。
利用するには「.com 共通管理」より「証明書のユーザーとパスワード認証のユーザーが異なるアクセスを許可する」を有効にしてください。 - 2要素認証を設定したcybozu.com ユーザーアカウントでは、パスワード認証でREST APIを利用できません。
セッション認証
セッション認証とは、Webサーバから付与されたセッションIDをCookieに保存する事でユーザを識別する認証方法です。
セッション認証ではGETメソッド以外の場合、通常はCSRFトークンが必要になります。
詳しくはCSRFトークン利用時の注意点をご確認ください。
※付与するCSRFトークンは「kintone」のCSRFトークンを使用する必要があります。
- kintone → kintone.getRequestToken()
- Garoon → garoon.connect.kintone.getRequestToken()
認証時の優先順位について
優先順位は以下の通りです。
- パスワード認証
- セッション認証
SAML認証設定時の利用について
SAML認証設定時に、cybozu.comのパスワード認証、セッション認証でUser APIを利用できます。
cybozu.com のログイン時に SAML 認証のみを使うように制限している場合、パスワード認証による User API の実行がcybozu.com共通管理者のみに制限されます。セッション認証の場合、この制限を受けません。
Basic認証
cybozuでBasic認証を利用している場合には、更にHTTPリクエストヘッダに「Authorization」ヘッダを追加します。
例) ログイン名が「Administrator」、パスワードが「cybozu」の場合
Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=
上記認証に関するリクエストヘッダはAPI実行(HTTPSリクエスト送信)の度に送信します。
リクエストヘッダ
以下のリクエストヘッダをAPI実行時に指定します。
ヘッダ名 | 内容 |
Host | (サブドメイン名).cybozu.com:443 |
cybozuで Basic 認証を利用しているリクエストヘッダ例
POST /v1/csv/user.json HTTP/1.1 Host: example.cybozu.com:443 X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU= Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU= Content-type: application/json
レスポンス
HTTPステータスコードが「200」であれば正常終了、それ以外はエラー終了です。
エラー時には下記情報を含むJSONデータをレスポンスとして受け取ります。
キー | 値 |
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です。
基本的に以下のような流れで利用します。
(1) ユーザー情報や組織情報などをCSVとして準備する (手動)
(2) CSVをアップロードする (ファイルアップロードAPI)
(3) ファイルキーが返却される (ファイルアップロードAPIのレスポンス)
(4) 実行したいインポート処理に対してファイルキーを送信する(例:ユーザーインポートAPI(CSV))
(5) ジョブ番号が返却される (例:ユーザーインポートAPI(CSV)のレスポンス)
(6) ジョブ番号を送信して (4) の処理が完了したか確認する (結果確認API)
(7) 処理結果が返却される (結果確認APIのレスポンス) ※処理結果が"処理中"であれば (6) を繰り返す。
API実行時に指定するデータは、CSV のアップロードでは CSV ファイル、
ファイルキーを送信するAPIはファイルキーを JSON 形式で生成し、これをリクエストボディとして送信します。
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 においては下記の2点で異なる挙動となります。
- ログイン名に「*」を指定することはできません。
- カスタマイズ項目に「*」を指定した場合、項目に「*」という文字として設定されます。
kintone JavaScript APIからの実行
User API を kintone JavaScript APIから実行する場合、kintone.api() を利用することができます。
※下記のUser APIでは kintone.api() を利用できません。
- ファイルアップロードAPI
- URIの末尾が.json以外のもの(ユーザーエクスポート API(CSV)など)
記事に関するフィードバック
記事のコメント欄は記事に対するフィードバックをする場となっております。
右の記事フィードバックのためのガイドを参照してコメントしてください。
記事のリンク切れなど、気になる点がある場合も、こちらのフォームからフィードバックいただけますと幸いです。