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

インポート

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点で異なる挙動となります。

• ログイン名に「*」を指定することはできません。
• カスタマイズ項目に「*」を指定した場合、項目に「*」という文字として設定されます。