5.10. バッチオペレーション

POST /1/(tenantId)/users/_batch

複数ユーザを同時に追加・更新・削除する。

Request Headers:
 
  • X-Application-Id -- アプリケーションID(必須)
  • X-Application-Key -- マスターキー(必須)
  • Content-Type -- application/json
Request JSON Object:
 
  • request (array) -- オペレーションの配列
Status Codes:
Response JSON Object:
 
  • results (array) -- オペレーション実行結果の配列

リクエストボディ

リクエストボディの例を示す。

{
  "requests": [
    {
      "op": "insert",
      "user": {
        "_id": "xxxxxxxx",
        "username": "tarou",
        "email": "nichiden.tarou@example.com",
        "password": "Passw0rd",
        "groups": [
          "group1", "group2"
        ],
        "options": {
        "displayName": "日電 太郎",
          "division": "日電事業部"
        },
        "clientCertUser": true
      }
    },
    {
      "op": "update",
      "_id": "yyyyyyyy",
      "etag": "ff123cc6-01a9-11e4-9be6-d39577f35b51",
      "user": {
        "username": "tarou",
        "email": "nichiden.tarou@example.com",
        "password": "Passw0rd",
        "options": {
        "displayName": "日電 太郎",
          "division": "日電事業部"
        },
        "enabled": false
      },
    },
    {
      "op": "delete",
      "_id": "zzzzzzzz",
      "etag": "11b6cedc-01aa-11e4-88f1-0b3208ae4242"
    }
  ]
}

データは "requests" に配列で指定する。サーバ側ではこの配列の先頭から順に処理が実行される。

各要素には以下の要素を指定する。

  • op : 操作 (必須)
    • insert(追加), update(更新), delete(削除) のいずれかを指定
  • _id : 操作対象ユーザのユーザID
    • update, delete の場合は必須
    • insert の場合は不要
  • etag : ユーザ情報のETag (オプション)
    • update, delete の場合は、ETag の指定が可能。指定した場合は、楽観ロックが実施される(サーバ側ユーザ情報と ETag 照合がされる)。
  • user : ユーザ情報
    • insert の場合は、サインアップ のリクエストボディで指定するユーザ情報と同様
      • ユーザID("_id")の指定が可能。指定した場合は、指定したユーザIDでユーザ登録される。
    • update の場合は、ユーザ情報変更 (パスワード変更を含む) のリクエストボディで指定するユーザ情報と同様
      • 指定したフィールドのみが更新される
    • delete の場合は、本フィールドは不要
    • groups : 所属グループ (オプション)
      • insert の場合のみ指定可能
      • 登録するユーザを所属させるグループ名を指定
      • 既に作成済みのグループを指定すること
    • clientCertUser : クライアント証明書ユーザフラグ(boolean)
      • insert の場合のみ指定可能
      • クライアント証明書認証を行うユーザを登録する場合は true をセットすること
      • true の場合は、username は必須、email, password は不要

レスポンスボディの例

{
  "results": [
    {
      "result": "ok",
      "_id": "...",
      "etag": "...",
      "updatedAt": "...",
      "user": { /*USER*/ }
    },
    {
      "result": "conflict",
      " reasonCode ": " etag_mismatch ",
      "_id": "...",
      "etag": "...",
      "updatedAt": "...",
      "user": { /*USER*/ },
    },
    {
      "result": "serverError",
      "_id": "..."
    },
    {
      "result": "ok",
      "_id": "...",
      "etag": "...",
      "updatedAt": "...",
      "user": { /*USER*/ },
    }
  ]
}

results 配列に、リクエスト時のオペレーションに対応した個数の JSON データが格納される。 また、この並び順はリクエストの配列の順番に対応している。データには以下のフィールドが設定される。

  • result : 実行結果。以下のいずれか。
    • ok : 正常に操作が完了した。
    • conflict : 衝突が発生した。
    • notFound : 該当ユーザが存在しない
    • badRequest : リクエスト不正
    • forbidden : 権限不正
    • serverError : その他のエラー
  • reasonCode : conflictの理由。Resultがconflictの場合のみ付加。以下のいずれか。
    • unspecified : 不明（初期値）
    • request_conflicted : 更新・削除処理衝突（更新･削除中に該当ユーザに変更発生）
    • duplicate_key : ユニーク制約エラー（重複エラー）
    • etag_mismatch : ETagが衝突（比較エラー）
  • _id : ユーザID。insertでエラーとなった場合は付加されない。
  • etag : 更新後の ETag 値
  • updatedAt : 更新時刻
  • user :
    • resultがokの場合: 更新されたユーザ情報。作成・更新・削除 API のレスポンスボディと同じもの。
    • エラーの場合: "etag_mismatch" の場合のみユーザ情報が格納され、それ以外の場合はなし。

注意事項

  • insert とupdate (パスワード更新)の場合は、処理に時間がかかるため、一度のバッチにおけるユーザ数の上限を100件程度とすることを推奨する。
  • ユーザ登録・更新時の本人確認、本人通知メールは送信しない。
  • その他の注意事項についてはオペレーション(op)により、サインアップ(insert)、ユーザ情報変更(update)、ユーザ削除(delete)の節の注意事項を参照のこと。