第10章 ユーザー管理 API

10.1. 要件

ユーザーは、以下のパーミッションを持つ 1 つ以上のチームメンバーである必要があります。

  • Reseller

    • 管理 (表示 & 編集)

または

  • Customer

    • 管理 (表示 & 編集)

パーミッションについての詳細は、「チームおよびコラボレーション」を参照してください。

10.2. ユーザーの作成

10.2.1. 説明

指定された顧客に属する新規ユーザーを作成します。

10.2.2. エンドポイント

  • URI: /box/srv/1.1/admin/user/create
  • メソッド: POST

10.2.3. リクエストボディー

{
  // required
  "username": "unqiue user identifier",
  // optional, default is a randomly generated password
  // Useful to leave as default if User is to be sent an activation email,
  // allowing them to set the password as required upon activation
  "password": "<password>",
  //optional
  "email": "<email>",
  //optional
  "name": "<name>",
  // optional, default is ""
  // comma separated list of roles to assign new user
  "roles": "<roles>",
  // optional, default is ""
  // comma separated list of Auth policy guids to assign new user
  "authpolicies": "<authpolicies>",
  // optional, default is false
  // whether or not an activation invite email should be sent to the user
  "invite": false
}

10.2.4. レスポンスボディー

10.2.4.1. 成功

{
  "status": "ok",
  "username": "<user_name>"
}

10.2.4.2. エラー

{
  "status": "error",
  "message": "<error_message>"
}

10.3. ユーザーの更新

10.3.1. 説明

指定された顧客に属する既存ユーザーを更新します。

10.3.2. エンドポイント

  • URI: /box/srv/1.1/admin/user/update
  • メソッド: POST

10.3.3. リクエストボディー

{
  //required, and it can not be changed
  "username": "<unique user identifier>",
  // all fields are optional
  // email address of user to update
  "email": "<email>",
  "name": "<name>",
  "password": "<password>",
  //user won't be able to login if this is set to true
  "enabled": false,
  //if this is set to true, if will return a special flag next time the user logged in,
  //this flag can be used to delete application data on the device
  "blacklisted": false,
  // comma separated list of roles to set for this user for example, 'dev, analytics'
  "roles": "<roles>",
  // comma separated list of Auth policy guids to set for this user
  "authpolicies": "<authpolicies>"
}

10.3.4. レスポンスボディー

10.3.4.1. 成功

注記

teams フィールドは、チームがプラットフォーム上で有効にされている場合にのみ有効です。JSON チーム定義を表示するには、ここ をクリックしてください。

{
  "status": "ok",
  "fields": {
    "username": "<unique user identifier>",
    "email": "<email>",
    "name": "<name>",
    "enabled": false,
    "blacklisted": false,
    "roles": "<roles>",
    //An Array of JSON Team Definitions the User is a Member of.
    //Note: This is only included if Teams is enabled for the User.
     "teams": ["<JSON Team Definition>"]
  }
}

10.3.4.2. エラー

{
  "status": "error",
  "message": "<error_message>"
}

10.4. ユーザーの削除

10.4.1. 説明

ユーザーを削除します。ユーザーにはアプリが設定されていない状態にしておく必要があります。設定されているとこの削除が失敗します。

10.4.2. エンドポイント

  • URI: /box/srv/1.1/admin/user/delete
  • メソッド: POST

10.4.3. リクエストボディー

{
  // required
  // username of user to delete
  "username": "<unique user identifier>",
}

10.4.4. レスポンスボディー

10.4.4.1. 成功

{
  "status": "ok",
  "fields": {
    "username": "<unique user identifier>",
    "email": "<email>",
    "name": "<name>",
    "enabled": false,
    "blacklisted": false,
    "roles": "<roles>",
    "authpolicies": "<authpolicies>"
  }
}

10.4.4.2. エラー

{
  "status": "error",
  "message": "<error_message>"
}

10.5. ユーザーの読み込み

10.5.1. 説明

ユーザー名に基づいてユーザー情報を読み込みます。

10.5.2. エンドポイント

  • URI: /box/srv/1.1/admin/user/read
  • メソッド: POST

10.5.3. リクエストボディー

{
  // required
  // user name of the user to delete
  "username": "<unique user identifier>",
}

10.5.4. レスポンスボディー

{
  "status": "ok",
  "fields": {
    "username": "<unique user identifier>",
    "email": "<email>",
    "name": "<name>",
    "enabled": false,
    "blacklisted": false,
    "roles": [<an array of role string>],
    "authpolicies": [<an array of Auth policy guids>],
    "lastLogin" : "<timestamp of last login>"
  }
}

10.5.4.1. エラー

{
  "status": "error",
  "message": "<error_message>"
}

10.6. ユーザーの一覧表示

10.6.1. 説明

ユーザーを一覧表示します。

10.6.2. エンドポイント

  • URI: /box/srv/1.1/admin/user/list
  • メソッド: POST

10.6.3. リクエストボディー

{}

10.6.4. レスポンスボディー

10.6.4.1. 成功

{
  "status": "ok",
  "count": "<users total count>",
  "list": [{
    "fields": {
      "username": "<unique user identifier>",
      "email": "<email>",
      "name": "<name>",
      "enabled": false,
      "blacklisted": false,
      "authpolicies": [<an array of Auth policy guids>],
      "lastLogin" : "<timestamp of last login>"
    }
  }, ...]
}

10.6.4.2. エラー

{
  "status": "error",
  "message": "<error_message>"
}

10.7. ユーザーの有効化/無効化

10.7.1. 説明

既存ユーザーを有効/無効にします。

10.7.2. エンドポイント

  • URI: /box/srv/1.1/admin/user/update
  • メソッド: POST

10.7.3. リクエストボディー

{
  // required
  // username of user to update
  "username": "<unique user identifier>",
  "enabled": true/false
}

10.7.4. レスポンスボディー

10.7.4.1. 成功

{
  "status": "ok",
  "fields": {
    "username": "<unique user identifier>",
    "email": "<email>",
    "name": "<name>",
    "enabled": false,
    "blacklisted": false,
    "roles": [<an array of string>],
    "authpolicies": [<an array of Auth policy guids>]
  }
}

10.7.4.2. エラー

{
  "status": "error",
  "message": "<error_message>"
}

10.8. ロールの追加/削除

10.8.1. 説明

新規ロールを追加するか、またはユーザーの既存ロールを削除します。

10.8.2. エンドポイント

  • URI: /box/srv/1.1/admin/user/update
  • メソッド: POST

10.8.3. リクエストボディー

{
  // required
  // username of the user to update
  "username": "<unique user identifier>",
  // comma separated list of roles to set for this user for example, 'dev, analytics'
  "roles": "<roles>"
}

10.8.4. レスポンスボディー

10.8.4.1. 成功

{
  "status": "ok",
  "fields": {
    "username": "<unique user identifier>",
    "email": "<email>",
    "name": "<name>",
    "enabled": false,
    "blacklisted": false,
    "roles": [<an array of string>],
    "authpolicies": [<an array of Auth policy guids>]
  }
}

10.8.4.2. エラー

{
  "status": "error",
  "message": "<error_message>"
}

10.9. 認証ポリシーの追加/削除

10.9.1. 説明

新規の認証ポリシーをユーザーに追加するか、またはユーザーから既存の認証ポリシーを削除します。

10.9.2. エンドポイント

  • URI: /box/srv/1.1/admin/user/update
  • メソッド: POST

10.9.3. リクエストボディー

{
  // required
  // username of the user to update
  "username": "<unique user identifier>",
  // comma separated list of Auth policy guids to set for this user
  "authpolicies": "<authpolicies>"
}

10.9.4. レスポンスボディー

10.9.4.1. 成功

{
  "status": "ok",
  "fields": {
    "username": "<unique user identifier>",
    "email": "<email>",
    "name": "<name>",
    "enabled": false,
    "blacklisted": false,
    "roles": [<an array of string>],
    "authpolicies": [<an array of Auth policy guids>]
  }
}

10.9.4.2. エラー

{
  "status": "error",
  "message": "<error_message>"
}

10.10. ユーザーのデバイスの一覧表示

10.10.1. 説明

ユーザーのデバイスを一覧表示します。

10.10.2. エンドポイント

  • URI: /box/srv/1.1/admin/user/listdevices
  • メソッド: POST

10.10.3. リクエストボディー

{
  //required
  "username": "<unique user identifier>"
}

10.10.4. レスポンスボディー

10.10.4.1. 成功

{
  "status" : "ok",
  "list" : [{
      "guid" : "<device guid>",
      "cuid" : "<device id>",
      "name" : "<devicel lable>",
      "disabled" : "<is the device disabled>",
      "blacklisted" : "<is the device blacklisted>"
    }, ...]
}

10.10.4.2. エラー

{
  "status": "error",
  "message": "<error_message>"
}

10.11. ユーザーのストアアイテムの一覧表示

10.11.1. 説明

ユーザーがインストールしたアプリを一覧表示します (ただし、アプリは削除される可能性があります)。

10.11.2. エンドポイント

  • URI: /box/srv/1.1/admin/user/liststoreitems
  • メソッド: POST

10.11.3. リクエストボディー

{
  //required
  "username" : "<unique user identifier>"
}

10.11.4. レスポンスボディー

10.11.4.1. 成功

{
  "status" : "ok",
  "list" : [{
      "guid" : "<app guid>",
      "name" : "<app name>",
      "description" : "<app description>"
    }, ...]
}

10.11.4.2. エラー

{
  "status": "error",
  "message": "<error_message>"
}