User API の共通仕様

概要

ユーザーやグループ、組織、役職などのインポート／エクスポート機能を持った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()

認証時の優先順位について

優先順位は以下の通りです。

1. パスワード認証
2. セッション認証

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)など）

kintone.api() を使って URI の長さが 4KB を超える GET リクエストを送信する場合は、
X-HTTP-Method-Override ヘッダーが付与され POST リクエストが送信されます。