カテゴリー内の他の記事

User API の共通仕様

フォローする

Index

概要

ユーザーやグループ、組織、役職などのインポート/エクスポート機能を持った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形式のデータを直接送信することができます。
importjson.png
(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点で異なる挙動となります。

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

記事に関するフィードバック

直接的に記事と関連がないご質問はcybozu developer コミュニティをご活用ください。

ログインしてコメントを残してください。