ユーザー

概要

ユーザーインターフェースは以下の要素で構成されます。

備考: ここのAPIでの「領域(realm)」は通常、テナントに相当します。

注記:すべてのPUT / POSTリクエストに対して「accept」ヘッダーを使用する必要があります。そうでない場合は、空の応答本体が返されます。

ユーザーAPI

ユーザーAPI [application/vnd.com.nsn.cumulocity.userApi+json]

名称 タイプ 発生回数 説明
self URL 1 このリソースへのリンク
userByName URI Template/User 1 タイプ「ユーザー」のリソースへの参照。このテンプレートに含まれるプレースホルダは{realm}と{userName}
users URI Template/UserCollection 1 ある領域(realm)に属するすべてのユーザーのコレクション。このテンプレートに含まれるプレースホルダは{realm}
currentUser URI Template/User 1 ログインユーザーのリソースへの参照
groupByName URI Template/Group 1 「グループ」のリソースへの参照。このテンプレートに含まれるプレースホルダは{realm}と{groupName}
groups URI Template/GroupCollection 1 ある領域に属するすべてのユーザーのコレクション。このテンプレートに含まれるプレースホルダは{realm}
roles URI Template/RoleCollection 1 すべてのロールのコレクション

GET - ユーザーAPIリソースの取得

応答本体: userApi

リクエスト例: ユーザーAPIリソースに関する情報を読み出す

GET /user
Host: [hostname]
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.nsn.cumulocity.userApi+json;ver=0.9

応答例:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.userApi+json;ver=0.9
Content-Length: nnn
{
     "self" : "<<UserAPI URL>>",
     "userByName" : "<<URL to the UserByName resource with realm and user name parameter>>",
     "users" : "<<URL to the UserCollection resource with realm parameter>>",
     "currentUser" : "<<URL to the CurrentUser resource>>",
     "groupByName" : "<<URL to the GroupByName resource with realm and group name parameter>>",
     "groups" : "<<URL to the GroupCollection resource with realm parameter>>",
     "roles" : "<<URL to the RoleCollection resource>>"
}

ユーザーコレクション

ユーザーコレクション [application/vnd.com.nsn.cumulocity.userCollection+json]

名称 タイプ 発生回数 説明
self URI 1 このリソースへのリンク
users User 0..n ユーザーのリスト
statistics PagingStatistics 1 ページング統計に関する情報
prev URI 0..1 ユーザーの前のページへのリンク(あれば)
next URI 0..1 ユーザーの次のページへのリンク(あれば)

GET - ユーザーコレクションの取得

応答本体: userCollection

リクエスト例: ユーザーコレクションに関する情報を読み出す

GET /user/<<tenant>>/users
Host: [hostname]
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.nsn.cumulocity.userCollection+json;ver=0.9

応答例:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.userCollection+json;ver=0.9
Content-Length: nnn
{
   "self":"[URL to this resource]",
   "users":[
        {
          "id" : "jsmith",
          "self" : "[URL to the resource]",
          "userName" : "jsmith",
          "firstName" : "John",
          "lastName" : "Smith",
          "phone" : "+1234567890",
          "email" : "jsmith@abc.com",
          "enabled" : true,
          "groups" : {[collection of groups the user belongs to]},
          "roles" : {[collection of roles the user has]},
          "devicePermissions": {}
        }, ... {
          "id" : "mblack",
          "self" : "[URL to the resource]",
          "userName" : "mblack",
          "firstName" : "Michael",
          "lastName" : "Black",
          "phone" : "+10988765432",
          "email" : "mblack@abc.com",
          "enabled" : true,
          "groups" : {[collection of groups the user belongs to]},
          "roles" : {[collection of roles the user has]},
          "devicePermissions": {}
        }
   ],
   "statistics" : {
       "totalPages" : 22,
       "pageSize" : 5,
       "currentPage : 1
   },
   "prev" : "[URL to previous page]",
   "next" : "[URL to next page]"
}

応答内のユーザーは、ユーザー名の昇順でソートされます。

ユーザーコレクションの検索パラメータ

ユーザーは次のパラメータでフィルタリングできます:

追加フラグ「withSubusersCount」 - 「true」 に設定すると、返される各ユーザー「subusersCount」というフィールドが追加されます(「subusersCount」とは直接のサブユーザー数(対応する"owner"を持つユーザー)のこと)。

リクエスト例: ユーザー名が「js」で始まり、グループ2、3、4のいずれかに属し、オーナーが 「admin」であり、デバイスユーザーではないユーザーを読み出します

GET /user/<<tenant>>/users?username=js&groups=2,3,4&owner=admin&withSubusersCount=true
Host: [hostname]
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.nsn.cumulocity.userCollection+json;ver=0.9

POST - コレクション内で新規ユーザーを作成

リクエスト本体: User

応答本体: User

リクエスト例: 新規ユーザーを作成する

POST /user/<<tenant>>/users
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Content-Length: nnn
 Content-Type: application/vnd.com.nsn.cumulocity.user+json;ver=0.9
{
  "userName" : "jsmith",
  "password" : "password",
  "firstName" : "John",
  "lastName" : "Smith",
  "phone" : "+1234567890",
  "customProperties" : {"language":"en"},
  "email" : "jsmith@abc.com",
  "enabled" : true,
  "sendPasswordResetEmail": true
}

応答例:

HTTP/1.1 201 Created
 Content-Type: application/vnd.com.nsn.cumulocity.user+json;ver=0.9
 Content-Length: nnn
 Location: [location]
{
  "id" : "jsmith",
  "self" : "[URL to this resource]",
  "userName" : "jsmith",
  "firstName" : "John",
  "lastName" : "Smith",
  "phone" : "+1234567890",
  "email" : "jsmith@abc.com",
  "customProperties" : {"language":"en"},
  "enabled" : true,
  "groups" : {[collection of groups the user belongs to]},
  "roles" : {[collection of roles the user has]},
  "devicePermissions": {}
}

ユーザー

ユーザー [application/vnd.com.nsn.cumulocity.user+json]

「ユーザー」リソースタイプは以下のフィールドを含みます。

名称 タイプ 発生回数 説明 PUT/POSTリクエストでの許可
id String 1 ユーザーを固有に識別します 許可なし
self URI 1 このリソースへのリンク 許可なし
userName String 1 任意のドメインにおいて一意のユーザー名。最大1000文字。空白、スラッシュ、+$ は使用できません。全角文字は利用しないでください POST: 必須 PUT: 許可なし
password String 1 ユーザーパスワード。6文字以上32文字以下。ラテン1の文字のみ使用できます POST: 必須 PUT: 任意
firstName String 1 ユーザーのファーストネーム 任意
lastName String 1 ユーザーのラストネーム 任意
phone String 1 ユーザーの電話番号。形式:「+ [国コード][番号]」。有効なMSIDNでなければなりません 任意
email String 1 ユーザーのメールアドレス 任意
enabled boolean 1 ユーザーの有効化状態(true/false) 任意
customProperties Object 1 カスタムプロパティのリストを維持します 任意
groups GroupReferenceCollection 1 グループリファレンスのリスト 許可なし
roles RoleReferenceCollection 1 ロールリファレンスのリスト 許可なし
devicePermissions Object 1 デバイスパーミッションのリスト 任意

組み込みユーザー はパスワードを除くすべてのプロパティを包含します。パスワードプロパティはGETユーザーに返されることは決してありません。

現ユーザー [application/vnd.com.nsn.cumulocity.currentUser+json]

「現ユーザー」リソースタイプは以下のフィールドを含みます。

名称 タイプ 発生回数 説明 PUT/POSTリクエストでの許可
id String 1 ユーザーを固有に識別します 許可なし
self URI 1 このリソースへのリンク 許可なし
userName String 1 任意のドメインにおいて固有のユーザー名。最大1000文字 POST: 必須 PUT: 許可なし
password String 1 ユーザーパスワード。6文字以上32文字以下。ラテン1の文字のみ使用できます POST: 必須 PUT: 任意
firstName String 1 ユーザーのファーストネーム 任意
lastName String 1 ユーザーのラストネーム 任意
phone String 1 ユーザーの電話番号。形式:「+ [国コード][番号]」。有効なMSIDNでなければなりません 任意
email String 1 ユーザーのメールアドレス 任意
enabled boolean 1 ユーザーの有効化状態(true/false) 任意
devicePermissions Object 1 デバイスパーミッションのリスト 任意
effectiveRoles Role 0..n 現ユーザーに(明示黙示を問わず、関連するグループ経由で)割り当てられているすべてのロールのリスト 許可なし

ユーザー名 は最大1000文字まで使えます。

組み込みユーザー はパスワードを除くすべてのプロパティを包含します。パスワードプロパティはGETユーザーに返されることは決してありません。

デバイスパーミッション構造

[API:fragment_name:permission]

HTTPメソッド別に要求されるパーミッション

「 * 」はワイルドカードです。これを使用すると、あらゆるAPIおよびCRUDオブジェクトへ、それらに含まれるフラグメントに関係なくアクセスすることができます。

コレクションに対するクエリ

ユーザーが閲覧を許可されているオブジェクトに限り、ユーザーに返されます。ページ統計を基に、「next」リンクを使用して次のページを問い合わせることができます。重要な注意点として、この場合、「currentPage」フィールドは実際のページ番号ではなくオフセットを表します。

重要事項: あるオブジェクトがフラグメントを全く含まない場合、例えばそのオブジェクトを読み取るにはデバイスパーミッションのフラグメント名の部分にワイルドカードを使用し、例えば"10200”:[“MEASUREMENT:*:READ”]という形にしなければなりません。

監査ログ

ユーザーのロール、デバイスパーミッションおよびグループに何らかの変更が生じると、付随して、タイプ「ユーザー」とアクティビティ「ユーザー更新」を含む監査記録が作成されます。

GET - ユーザー情報の取得

応答本体: User

応答本体: ユーザーに関する情報を読み出す

GET /user/<<tenant>>/users/<<userId>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.user+json;ver=0.9

応答本体:

Content-Type: application/vnd.com.nsn.cumulocity.user+json;ver=0.9
Content-Length: nnn
{
  "id" : "jsmith",
  "self" : "[URL to this resource]",
  "userName" : "jsmith",
  "firstName" : "John",
  "lastName" : "Smith",
  "phone" : "+1234567890",
  "email" : "jsmith@abc.com",
  "enabled" : true,
  "groups" : {[collection of groups the user belongs to]},
  "roles" : {[collection of roles the user has]},
  "devicePermissions": {}
}

ユーザーパスワードはGET応答に含まれる形で返されることは決してありません。認証メカニズムは別のインターフェースによって提供されます。

GET - ユーザー情報を当人の名前で取得

応答本体: User

リクエスト例: ユーザーに関する情報を読み出す

GET /user/<<tenant>>/userByName/<<userName>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.user+json;ver=0.9

応答例:

Content-Type: application/vnd.com.nsn.cumulocity.user+json;ver=0.9
Content-Location: [location]
Content-Length: nnn
{
  "id" : "jsmith",
  "self" : "[URL to this resource]",
  "userName" : "jsmith",
  "firstName" : "John",
  "lastName" : "Smith",
  "phone" : "+1234567890",
  "email" : "jsmith@abc.com",
  "enabled" : true,
  "groups" : {[collection of groups the user belongs to]},
  "roles" : {[collection of roles the user has]},
  "devicePermissions": {}
}

PUT - ユーザーリソースを変更

リクエスト本体: User

応答本体: User

リクエスト例: ユーザーのファーストネームを変更する

PUT /user/<<tenant>>/users/<<userId>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.user+json;ver=0.9
 Content-Type: application/vnd.com.nsn.cumulocity.user+json;ver=0.9
 Content-Length: nnn
{
   "firstName" : "Robert"
}

応答例:

Content-Type: application/vnd.com.nsn.cumulocity.user+json;ver=0.9
Content-Length: nnn
{
  "id" : "jsmith",
  "self" : "[URL to this resource]",
  "userName" : "jsmith",
  "firstName" : "Robert",
  "lastName" : "Smith",
  "phone" : "+1234567890",
  {emailcloak=off}"email" : "jsmith@abc.com",
  "enabled" : true,
  "groups" : {[collection of groups the user belongs to]},
  "roles" : {[collection of roles the user has]},
  "devicePermissions": {}
}

ユーザーのパーミッションやグループの変更を更新すると、付随して、タイプ「ユーザー」とアクティビティ「ユーザー更新」を含む監査記録が作成されます。

DELETE - ユーザーの削除

リクエスト本体: n/a

応答本体: n/a

リクエスト例: ユーザーを削除する

DELETE /user/<<tenant>>/users/<<userName>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx

応答例:

HTTP/1.1  204 NO CONTENT

GET - 現ユーザーリソースの取得

応答本体: user

または

応答本体: currentUser

リクエスト例: ログイン中のユーザーに関する情報を読み出す

GET /user/currentUser
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.user+json;ver=0.9

応答例:

HTTP/1.1 200 OK
 Content-Type: application/vnd.com.nsn.cumulocity.user+json;ver=0.9
 Content-Length: nnn

{
    "email": "jsmith@abc.com",
    "enabled": true,
    "firstName": "John",
    "devicePermissions": {},
    "groups": {
        "references": [...],
        "self": "[URL to User's Groups]"
    },
    "id": "jsmith",
    "lastName": "Smith",
    "phone": "+1234567890",
    "roles": {
        "references": [...],
        "self": "[URL to the User's Roles]"
    },
    "self": "[URL to the User resource]",
    "userName": "jsmith"}

PUT - 現ユーザーリソースの変更

リクエスト本体: user

応答本体: user

リクエスト例: ログインユーザーの名前を変更する

PUT /user/currentUser
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.user+json;ver=0.9
 Content-Type: application/vnd.com.nsn.cumulocity.user+json;ver=0.9
 Content-Length: nnn

{
   "firstName" : "Robert"
}

応答例:

HTTP/1.1 200 OK
 Content-Type: application/vnd.com.nsn.cumulocity.user+json;ver=0.9
 Content-Length: nnn

 {
    "email": "jsmith@abc.com",
    "enabled": true,
    "firstName": "Robert",
    "groups": {
        "references": [...],
        "self": "[URL to User's Groups]"
    },
    "id": "jsmith",
    "lastName": "Smith",
    "phone": "+1234567890",
    "roles": {
        "references": [...],
        "self": "[URL to the User's Roles]"
    },
    "self": "[URL to the User resource]",
    "userName": "jsmith",
    "devicePermissions": {}
 }

ユーザーリファレンスコレクション

ユーザーリファレンスコレクション [application/vnd.com.nsn.cumulocity.userReferenceCollection+json]

名称 タイプ 発生回数 説明
self URI 1 このリソースへのリンク
references UserReference 0..n ユーザーリファレンスのリスト
statistics PagingStatistics 1 ページング統計に関する情報
prev URI 0..1 ユーザーリファレンスの前のページへのリンク(あれば)
next URI 0..1 ユーザーリファレンスの次のページへのリンク(あれば)

POST - ユーザーをグループに追加

リクエスト本体: UserReference

応答本体: UserReference

リクエスト例: 新規ユーザーリファレンスを作成する

POST /user/<<tenant>>/groups/<<groupId>>/users
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Content-Length: nnn
 Content-Type: application/vnd.com.nsn.cumulocity.userReference+json;ver=0.9

{
  "user" : {
    "self" : "[URL to the User resource]"
  }
}

応答例:

HTTP/1.1 201 Created
 Content-Type: application/vnd.com.nsn.cumulocity.userReference+json;ver=0.9
 Content-Length: nnn
 Location: [location]

{
    "self": "[URL to this resource]",
    "user": {
        "email": "jsmith@abc.com",
        "enabled": true,
        "firstName": "John",
        "groups": {
            "references": [...],
            "self": "[URL to the User's Groups]"
        },
        "id": "jsmith",
        "lastName": "Smith",
        "phone": "+1234567890",
        "roles": {
            "references": [...],
            "self": "[URL to the User's Roles]"
        },
        "self": "[URL to the User resource]",
        "userName": "jsmith"
    }}

ユーザーがグループに追加されると、付随して、タイプ「ユーザー」とアクティビティ「ユーザー更新」を含む監査記録が作成されます。

DELETE - ユーザーをグループから削除

リクエスト本体: n/a

応答本体: n/a

リクエスト例: ユーザーリファレンスを削除する

 DELETE /user/<<tenant>>/groups/<<groupId>>/users/<<yourUserName>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx

応答例:

HTTP/1.1  204 NO CONTENT

ユーザーがグループから削除されると、付随して、タイプ「ユーザー」とアクティビティ「ユーザー更新」を含む監査記録が作成されます。

GET - グループに属するすべてのユーザーを取得

応答本体: UserReferenceCollection

リクエスト例: グループに属するすべてのユーザーに関する情報を読み出す

GET /user/management/groups/<<groupId>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.userReferenceCollection+json;ver=0.9

応答例:

Content-Type: application/vnd.com.nsn.cumulocity.userReferenceCollection+json;ver=0.9
Content-Length: nnn

{
  "self" : "[URL to this resource]",
  "references" : [
    {
      "self" : "[URL to this UserReference resource]",
      "user" : {
        "self" : "[URL to this User resource]",
        "id" : "1",
        "userName" : "jsmith",
        ...
      }
    }
  ],
  "statistics" : {
    "totalPages" : 3,
    "pageSize" : 5,
    "currentPage : 1
  },
  "prev" : "[URL to previous page]",
  "next" : "[URL to next page]"
}

ユーザーリファレンス

ユーザーリファレンス [application/vnd.com.nsn.cumulocity.userReference+json]

名称 タイプ 発生回数 説明
self URI 1 このリソースへのリンク
user User 1 参照されるユーザーリソース

グループコレクション

グループコレクション [application/vnd.com.nsn.cumulocity.groupCollection+json]

名称 タイプ 発生回数 説明
self URI 1 このリソースへのリンク
groups Group 0..n グループのリスト
statistics PagingStatistics 1 ページング統計に関する情報
prev URI 0..1 グループの前のページへのリンク(あれば)
next URI 0..1 グループの次のページへのリンク(あれば)

監査ログ

グループのロール、またはデバイスパーミッションに何らかの変更が生じると、付随して、変更されたプロパティに関する情報を含んだタイプ「グループ」とアクティビティ「グループ更新」を含む監査記録が作成されます。

GET - すべてのグループのリストアップ

応答本体: GroupCollection

リクエスト例: グループコレクションに関する情報を読み出す

GET /user/management/groups/
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.groupCollection+json;ver=0.9

応答例:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.groupCollection+json;ver=0.9
Content-Length: nnn

{
   "self":"[URL to this resource]",
   "groups": [
        {
          "id" : "1",
          "self" : "[URL to this resource]",
          "name" : "administrators",
          "roles" : [...],
          "users" : ["self" : "[URL to collection of Users in this Group]"],
          "devicePermissions": {}
        },
        {
          "id" : "2",
          "self" : "[URL to this resource]",
          "name" : "readers",
      "roles" : [...],
          "users" : ["self" : "[URL to collection of Users in this Group]"],
          "devicePermissions": {}
        }
   ],
   "statistics" : {
       "totalPages" : 2,
       "pageSize" : 5,
       "currentPage : 1
   },
  "prev" : "[URL to previous page]",
  "next" : "[URL to next page]"
}

POST - グループの作成

リクエスト本体: Group

応答本体: Group

リクエスト例: 新規グループを作成する

POST /user/management/groups
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Content-Length: nnn
 Content-Type: application/vnd.com.nsn.cumulocity.group+json;ver=0.9

{
  "name" : "monitoring"
}

応答例:

HTTP/1.1 201 Created
 Content-Type: application/vnd.com.nsn.cumulocity.group+json;ver=0.9
 Content-Length: nnn
 Location: [URL to the resource]

{
  "id" : "3",
  "self" : "[URL to this resource]",
  "name" : "monitoring"
  "users" : {
    "self" : "[URL to the UserReferenceCollection resource]",
    "references" : []
  },
  "roles" : {
    "self" : "[URL to the RoleReferenceCollection resource]",
    "references" : []
  },
  "devicePermissions": {}
}

グループ

グループ [application/vnd.com.nsn.cumulocity.group+json]

名称 タイプ 発生回数 説明 PUT/POSTリクエストでの許可
id String 1 グループを固有に識別します 許可なし
self URI 1 このリソースへのリンク 許可なし
name String 1 グループの記述名 必須
roles RoleReferenceCollection 1 ロールリファレンスのリスト 許可なし
devicePermissions Object 1 デバイスパーミッションのリスト 任意

グループの詳細の表示

応答本体: Group

リクエスト例: グループに関する情報を読み出す

GET /user/management/groups/<<groupId>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.group+json;ver=0.9

応答例:

Content-Type: application/vnd.com.nsn.cumulocity.group+json;ver=0.9
Content-Length: nnn

{
  "id" : "1",
  "self" : "[URL to this resource]",
  "name" : "administrators",
  "devicePermissions": {},
  "roles" : {
    "self" : "[URL to the RoleReferenceCollection resource]",
    "references" : [
    {
      "self" :  "[URL to the RoleReference resource]",
      "role" : {
          "self" :  "[URL to the Role resource]",
          "id" : "1",
          "name" : "ROLE_USER_MANAGEMENT_ADMIN"
      }
    },
    {
      "self" :  "[URL to the RoleReference resource]",
      "role" : {
            "self" :  "[URL to the Role resource]",
            "id" : "1",
            "name" : "ROLE_INVENTORY_MANAGEMENT_ADMIN"
          }
        },
    ...
     ]
}

GET - グループ情報を名前から取得

応答本体: Group

リクエスト例: グループに関する情報を読み出す

GET /user/<<tenant>>/groupByName/<<groupName>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.group+json;ver=0.9

応答例:

Content-Type: application/vnd.com.nsn.cumulocity.group+json;ver=0.9
Content-Location: [main URL of this resource]
Content-Length: nnn

{
  "id" : "1",
  "self" : "[URL to this resource]",
  "name" : "administrators",
  ...
}

DELETE - グループの削除

リクエスト本体: n/a

応答本体: n/a

リクエスト例: グループを削除する

DELETE /user/<<tenant>>/groups/<<groupId>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx

応答例:

HTTP/1.1  204 NO CONTENT

グループが削除されると、付随して、ユーザーがグループから削除された旨の情報を含んだタイプ「ユーザー」とアクティビティ「ユーザー更新」を含む監査記録が作成されます。

備考: ADMINS と DEVICES グループは削除できません。

PUT - グループの更新

リクエスト本体: Group

応答本体: Group

リクエスト例: グループ名を変更する

PUT /user/<<tenant>>/groups/<<groupId>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.group+json;ver=0.9
 Content-Type: application/vnd.com.nsn.cumulocity.group+json;ver=0.9
 Content-Length: nnn

{
   "name" : "PlatformAdministrators"
}

応答例:

Content-Type: application/vnd.com.nsn.cumulocity.group+json;ver=0.9
Content-Length: nnn

{
  "id" : "1",
  "self" : "[URL to this resource]",
  "name" : "PlatformAdministrators",
  ...
}

ロールまたはパーミッションの変更を伴ってグループが更新される場合、付随して、タイプ「グループ」とアクティビティ「グループ更新」を含む監査記録が作成されます。

グループリファレンスコレクション

グループリファレンスコレクション [application/vnd.com.nsn.cumulocity.groupReferenceCollection+json]

名称 タイプ 発生回数 説明
self URI 1 このリソースへのリンク
groups GroupReference 0..n グループリファレンスのリスト
statistics PagingStatistics 1 ページング統計に関する情報
prev URI 0..1 グループリファレンスの前のページへのリンク(あれば)
next URI 0..1 グループリファレンスの次のページへのリンク(あれば)

GET - ユーザーが属するすべてのグループを取得する

応答本体: GroupReferenceCollection

リクエスト例: ユーザーが属するすべてのグループに関する情報を読み出す

GET /user/<<tenant>>/users/<<userName>>/groups
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.groupReferenceCollection+json;ver=0.9

応答例:

Content-Type: application/vnd.com.nsn.cumulocity.groupReferenceCollection+json;ver=0.9
Content-Length: nnn

{
    "self" : "[URL to this resource]",
    "references": [
        {        
          "group": {            
            "id": 21,            
            "name": "admins",            
            "roles": {                
                "references": [...],                
                "self": "[URL to this Group's Roles]"            
            },            
            "self": "[URL to this Group]",            
            "users": {                
                "self": "[URL to this Group's Users]"            
            }        
          },        
          "self": "[URL to this User's Group]"    
        },   ...   ],   
    "statistics" : {
        "totalPages" : 1,
        "pageSize" : 5,
        "currentPage : 1
    },
    "prev" : "[URL to previous page]",
    "next" : "[URL to next page]"
}

グループリファレンス

グループリファレンス [application/vnd.com.nsn.cumulocity.groupReference+json]

名称 タイプ 発生回数 説明
self URI 1 このリソースへのリンク
group Group 1 参照されるグループリソース

ロールコレクション

ロールコレクション [application/vnd.com.nsn.cumulocity.roleCollection+json]

フィールド名 タイプ 発生回数 説明
self URI 1 このリソースへのリンク
roles Role 0..n ロールのリスト
statistics PagingStatistics 1 ページング統計に関する情報
prev URI 0..1 ロールの前のページへのリンク(あれば)
next URI 0..1 ロールの次のページへのリンク(あれば)

ロール

ロール [application/vnd.com.nsn.cumulocity.role+json]

名称 タイプ 発生回数 説明
id String 1 ロールを固有に識別します。
name String 1 ロールの記述名(ロールの命名パターンに従います)

GET - 利用可能なロールの取得

応答本体: RoleCollection

リクエスト例: ロールコレクションに関する情報を読み出す

 GET /user/roles
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx

応答例:

HTTP/1.1 200 OK
 Content-Type: application/vnd.com.nsn.cumulocity.roleCollection+json;ver=0.9
 Content-Length: nnn

{
   "self":"[URL to this resource]",
   "roles": [
     {
       "self" :  "[URL to the Role resource]",
       "id" : "ROLE_INVENTORY_ADMIN",
       "name" : "ROLE_INVENTORY_ADMIN"
     },
     {
       "self" :  "[URL to the Role resource]",
       "id" : "ROLE_USER_MANAGEMENT_ADMIN",
       "name" : "ROLE_USER_MANAGEMENT_ADMIN"
     },    ...
   ],
   "statistics" : {
       "totalPages" : 5,
       "pageSize" : 5,
       "currentPage : 1
   },
  "prev" : "[URL to previous page]",
  "next" : "[URL to next page]"
}

ロールをユーザーに割り当てる

リクエスト本体: RoleReference

応答本体: RoleReference

リクエスト例: 新規ロールリファレンスの作成

POST /user/<<tenant>>/users/<<userName>>/roles
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Content-Length: nnn
 Content-Type: application/vnd.com.nsn.cumulocity.roleReference+json;ver=0.9

{
  "role" : {
    "self" : "[URL to the Role resource]"
  }
}

応答例:

HTTP/1.1 201 Created
 Content-Type: application/vnd.com.nsn.cumulocity.roleReference+json;ver=0.9
 Content-Length: nnn
 Location: [URL to this resource]

{
  "self" : "[URL to this resource]",
  "role" : {
    "self" :  "[URL to the Role resource]",
    "id" : "ROLE_USER_MANAGEMENT_ADMIN",
    "name" : "ROLE_USER_MANAGEMENT_ADMIN"
  }
}

ロールがユーザーに割り当てられると、付随して、タイプ「ユーザー」とアクティビティ「ユーザー更新」を含む監査記録が作成されます。

ロールをグループに割り当てる

リクエスト本体: RoleReference

応答本体: RoleReference

リクエスト例: 新規ロールリファレンスを作成する

POST /user/<<tenant>>/groups/<<groupId>>/roles
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Content-Length: nnn
 Content-Type: application/vnd.com.nsn.cumulocity.roleReference+json;ver=0.9

{
  "role" : {
    "self" : "[URL to the Role resource]"
  }
}

応答例:

HTTP/1.1 201 Created
 Content-Type: application/vnd.com.nsn.cumulocity.roleReference+json;ver=0.9
 Content-Length: nnn
 Location: [URL to this resource]

{
  "self" : "[URL to this resource]",
  "role" : {
    "self" :  "[URL to the Role resource]",
    "id" : "ROLE_USER_MANAGEMENT_ADMIN",
    "name" : "ROLE_USER_MANAGEMENT_ADMIN"
  }
}

ロールがグループに割り当てられると、付随して、タイプ「グループ」とアクティビティ「グループ更新」を含む監査記録が作成されます。

ユーザーのロールを解除する

リクエスト本体: n/a

応答本体: n/a

リクエスト例: ロールリファレンスを削除する

DELETE /user/<<tenant>>/users/<<userName>>/roles/<<roleName>> (Example:ROLE_TENANT_MANAGEMENT_ADMIN)}}
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx

応答例:

HTTP/1.1  204 NO CONTENT

グループのロールを解除する

リクエスト本体: n/a

応答本体: n/a

リクエスト例: ロールリファレンスを削除する

DELETE /user/<<tenant>>/groups/<<groupId>>/roles/<<roleName>> (Example:ROLE_TENANT_MANAGEMENT_ADMIN)}}
 Authorization: Basic xxxxxxxxxxxxxxxxxxx

応答例:

HTTP/1.1  204 NO CONTENT

ロールがグループから解除されると、付随して、タイプ「グループ」とアクティビティ「グループ更新」を含む監査記録が作成されます。

ロールリファレンスコレクション

ロールリファレンスコレクション [application/vnd.com.nsn.cumulocity.roleReferenceCollection+json]

名称 タイプ 発生回数 説明
self URI 1 このリソースへのリンク
references RoleReference 0..n ロールリファレンスのリスト
statistics PagingStatistics 1 ページング統計に関する情報
prev URI 0..1 ロールリファレンスの前のページへのリンク(あれば)
next URI 0..1 ロールリファレンスの次のページへのリンク(あれば)

GET - ユーザーのすべてのロールを取得

応答本体: RoleReferenceCollection

リクエスト例: ロールリファレンスコレクションに関する情報を読み出す

GET /user/<<tenant>>/users/<<userName>>/roles
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.roleReferenceCollection+json;ver=0.9

応答例:

HTTP/1.1 200 OK
 Content-Type: application/vnd.com.nsn.cumulocity.roleReferenceCollection+json;ver=0.9
 Content-Length: nnn
{
   "self":"[URL to this resource]",
   "references": [
     {
       "self" :  "[URL to the Role Reference resource]",
       "role" : {
          "self" :  "[URL to the Role resource]",
          "id" : "ROLE_INVENTORY_ADMIN",
          "name" : "ROLE_INVENTORY_ADMIN"
       }
     },
     {
       "self" :  "[URL to the Role Reference resource]",
       "role" : {
          "self" :  "[URL to the Role resource]",
          "id" : "ROLE_USER_MANAGEMENT_ADMIN",
          "name" : "ROLE_USER_MANAGEMENT_ADMIN"
       }
     }
   ],
   "statistics" : {
       "totalPages" : 1,
       "pageSize" : 5,
       "currentPage : 1
   },
  "prev" : "[URL to previous page]",
  "next" : "[URL to next page]"
}

GET - グループのすべてのロールを取得

応答本体: RoleReferenceCollection

リクエスト例: ロールリファレンスコレクションに関する情報を読み出す

GET /user/<<tenant>>/groups/<<groupId>>/roles
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.roleReferenceCollection+json;ver=0.9

応答例:

HTTP/1.1 200 OK
 Content-Type: application/vnd.com.nsn.cumulocity.roleReferenceCollection+json;ver=0.9
 Content-Length: nnn

{
   "self":"[URL to this resource]",
   "references": [
     {
       "self" :  "[URL to the Role Reference resource]",
       "role" : {
          "self" :  "[URL to the Role resource]",
          "id" : "ROLE_INVENTORY_ADMIN",
          "name" : "ROLE_INVENTORY_ADMIN"
       }
     },
     {
       "self" :  "[URL to the Role Reference resource]",
       "role" : {
          "self" :  "[URL to the Role resource]",
          "id" : "ROLE_USER_MANAGEMENT_ADMIN",
          "name" : "ROLE_USER_MANAGEMENT_ADMIN"
       }
     }
   ],
   "statistics" : {
       "totalPages" : 1,
       "pageSize" : 5,
       "currentPage : 1
   },
  "prev" : "[URL to previous page]",
  "next" : "[URL to next page]"
}

ロールリファレンス

ロールリファレンス[application/vnd.com.nsn.cumulocity.roleReference+json]

名称 タイプ 発生回数 説明
self URI 1 このリソースへのリンク
role Role 1 参照されるロールリファレンス