User API の共通仕様

概要

ユーザーやグループ、組織、役職などのインポート／エクスポート機能を持ったAPIです。

プロトコル

HTTPS

インターフェース

JSON

文字コード

UTF-8

エスケープ

「\」を使用します。

認証

ログイン名、パスワードで認証する場合

リクエストヘッダに「X-Cybozu-Authorization」を追加し、その値として、ログイン名とパスワードをBASE64エンコードしたものを指定します。

例) ログイン名が「Administrator」、パスワードが「cybozu」の場合

X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=

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"}

インポート

インポートAPI は、非同期型の API です。
インポートAPIは基本的に以下のような流れで利用します。

(1) ユーザー情報や組織情報などをCSVとして準備する (手動)
(2) CSVをアップロードする (ファイルアップロードAPI) 
(3) ファイルキーが返却される (ファイルアップロードAPIのレスポンス)
(4) 実行したいインポート処理に対してファイルキーを送信する（例：ユーザーインポートAPI）
(5) ジョブ番号が返却される (例：ユーザーインポートAPIのレスポンス) 
(6) ジョブ番号を送信して (4) の処理が完了したか確認する (結果確認API) 
(7) 処理結果が返却される (結果確認APIのレスポンス) ※処理結果が"処理中"であれば (6) を繰り返す。

API実行時に指定するデータは、CSV のアップロードでは CSV ファイル、ファイルキーを送信するAPIはファイルキーを JSON 形式で生成し、これをリクエストボディとして送信します。

エクスポート

CSV

CSV エクスポートAPI は、同期型の API です。
リクエスト送信(API) リクエストに応じたCSVがダウンロードされます。

(1) CSV エクスポートAPIを実行する
(2) CSV が返却される

JSON

JSON エクスポートAPI は、非同期型の API です。
リクエスト送信(API) リクエストに応じたJSONが返却されます。

(1) JSON エクスポートAPIを実行する
(2) JSON が返却される

その他

「*」（アスタリスク）の取り扱いについて

原則としてアップロードする CSV のフィールド値に「*」を指定した場合、そのフィールド値は更新しないことを表します。ただし、ユーザー情報の CSV においては下記の2点で異なる挙動となります。ログイン名に「*」を指定することはできません。カスタマイズ項目に「*」を指定した場合、項目に「*」という文字として設定されます。