ユーザー

概要

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

  • 「ユーザーAPI」リソースは、すべてのユーザー、グループ、ロールまたは特定の名称を有するグループのクエリが可能となるよう、ユーザー、グループおよびロールのコレクションにURIおよびURIテンプレートを返します。
  • 「ユーザーコレクション」リソースは一連のユーザーを読み出し、新規ユーザーの作成を可能にします。
  • 「ユーザー」リソースは、クエリおよび削除が可能な個々のユーザーを表わします。
  • 「ユーザーリファレンスコレクション」リソースは、ユーザーに対するリファレンスのセットを読み出します。これらは例えば特定のユーザーグループに属するユーザーである可能性もあります。コレクションに新規ユーザーを追加することも可能にします。
  • 「ユーザーリファレンス」リソースは、読み出しまたは削除が可能な、ユーザーに対する1つの個別のリファレンスを表わします。
  • 「現ユーザー」リソースは、クエリおよび修正され得る、ログイン中のユーザーを表わします。
  • 「グループコレクション」リソースは一連のグループを読み出し、新規グループの作成を可能にします。
  • グループ」リソースは、クエリおよび削除が可能な個々のグループを表わします。
  • 「グループリファレンスコレクション」リソースは、グループに対するリファレンスのセットを読み出します。これは例えば特定のユーザーが属するグループである可能性もあります。
  • 「グループリファレンス」リソースは、読み出しまたは削除が可能な、グループに対する1つの個別のリファレンスを表わします。
  • 「ロールコレクション」リスースは一連のリソースを読み出します。
  • 「ロール」リソースは、ユーザーまたはグループに対してクエリおよび割り当てが可能な、あるいはまだ割り当てられていない、個々のロールを表わします。
  • 「ロールリファレンスコレクション」リソースは、ロールに対するリファレンスのセットを読み出します。これらは例えば特定のユーザーまたはグループにロールである可能性もあります。
  • 「ロールリファレンス」リソースは、読み出し可能な、ロールに対する1つの個別のリファレンスを表わします。

Info:本APIでいう「領域(realm)」は通常、テナントに相当します。

注記:すべてのPUT/POSTリクエストについて、acceptヘッダーを使用すべきであり、さもなければ空の応答本体が返されます。

ユーザーAPI

UserAPI [application/vnd.com.nsn.cumulocity.userApi+json]

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

ユーザーAPIリソースをGETする

応答本体: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>>"
}

ユーザーコレクション

UserCollection [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する

応答本体:ユーザーコレクション

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

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]"
}

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

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

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

  • username - ユーザー名の接頭または全て
  • groups - カンマで区切られた数値グループ識別子; 結果には、指定したグループの少なくとも1つに属するユーザーのみが含まれます。
  • owner - 正確なユーザー名
  • onlyDevices - booleanフラグ。"true"に設定した場合、結果にはブートストラップ処理中に作成されたユーザーのみが含まれます("device_"で始まるもの)。 フラグがない、またはfalseの場合、結果には"device_"ユーザーは含まれません。

追加フラグ"withSubusersCount" - "true" に設定すると、返される各ユーザー"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 - コレクション内で新規ユーザーを作成する

リクエスト本体:ユーザー

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

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": {}
}

ユーザー

User [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] where:

  • APIは以下のいずれかの値に該当します:「OPERATION」、「ALARM」、「AUDIT」、「EVENT」、「MANAGED_OBJECT」、「MEASUREMENT」または「 * 」。
  • フラグメント名は例えば「c8y_Restart」または「 * 」など、任意の名称を使用可能です。
  • パーミッションは「ADMIN」、「READ」または「 * 」です。

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

  • POST - "ADMIN" または "*"
  • PUT - "ADMIN" または "*"
  • DELETE - "ADMIN" または "*"
  • GET - "READ" または "*"

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

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

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

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

監査ログ

ユーザーのロール、デバイスパーミッションおよびグループに何らかの変更が生じると、種別としての「ユーザー」と活動としての「ユーザー更新」、そして変更されたプロパティの種類に関する情報を含んだ、付随する監査記録が作成されます。

ユーザー情報をGETする

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

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する

応答本体:ユーザー リクエスト例:ユーザーに関する情報を取得する

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する

リクエスト本体:ユーザー

応答本体:ユーザー

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

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する

リクエスト本体:適用外

応答本体:適用外 リクエスト例:ユーザーをDELETEする

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

応答例:

HTTP/1.1  204 NO CONTENT

現ユーザーリソースをGETする

応答本体:ユーザー

または

応答本体:現ユーザー

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

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する

リクエスト本体:ユーザー

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

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": {}
 }

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

UserReferenceCollection [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 /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する

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

応答例:

HTTP/1.1  204 NO CONTENT

ユーザーがグループから削除されると、種別としての「ユーザー」および活動としての「ユーザー更新」を含んだ付随する監査記録が作成されます。

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

応答本体:ユーザーリファレンスコレクション リクエスト例:グループに属するすべてのユーザーに関する情報を取得する

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]"
}

ユーザーリファレンス

UserReference [application/vnd.com.nsn.cumulocity.userReference+json]

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

グループコレクション

GroupCollection [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 /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 /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": {}
}

グループ

Group [application/vnd.com.nsn.cumulocity.group+json]

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

グループの詳細を表示する

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

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する

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

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する

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

応答例:

HTTP/1.1  204 NO CONTENT

グループが削除されると、種別としての「ユーザー」および活動としての「ユーザー更新」、そしてユーザーがグループから削除された旨の情報を含んだ、付随する監査記録が作成されます。

Info: ADMINS と DEVICES グループは削除できないことに注意してください。

グループを更新する

応答本体:グループ

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

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",
  ...
}

ロールまたはパーミッションの変更を伴ってグループが更新される場合、種別としての「グループ」および活動としての「グループ更新」を含んだ、付随する監査記録が作成されます。

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

GroupReferenceCollection [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する

応答本体:グループリファレンスコレクション リクエスト例:ユーザーが属するすべてのグループに関する情報を読み出す

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]"
}

グループリファレンス

GroupReference [application/vnd.com.nsn.cumulocity.groupReference+json]

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

ロールコレクション

RoleCollection [application/vnd.com.nsn.cumulocity.roleCollection+json]

フィールド名 種別 発生回数 説明
self URI 1 このリソースへのリンク
roles Role 0..n v
statistics PagingStatistics 1 ページング統計に関する情報
prev URI 0..1 ロール追加に伴う潜在的な前のページへのリンク
next URI 0..1 ロール追加に伴う潜在的な次のページへのリンク

ロール

Role [application/vnd.com.nsn.cumulocity.role+json]

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

利用可能なロールをすべてGETする

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

 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]"
}

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

リクエスト本体:ロールリファレンス

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

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"
  }
}

ロールがユーザーに割り当てられると、種別としての「ユーザー」および活動としての「ユーザー更新」を含んだ、付随する監査記録が作成されます。

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

リクエスト本体:ロールリファレンス

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

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"
  }
}

ロールがグループに割り当てられると、種別としての「グループ」および活動としての「グループ更新」を含んだ、付随する監査記録が作成されます。

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

リクエスト本体:適用外

応答本体:適用外 リクエスト例:ロールリファレンスをDELETEする

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

応答例:

HTTP/1.1  204 NO CONTENT

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

リクエスト本体:適用外

応答本体:適用外 リクエスト例:ロールリファレンスをDELETEする

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

応答例:

HTTP/1.1  204 NO CONTENT

ロールがグループから解除されると、種別としての「グループ」および活動としての「グループ更新」を含んだ、付随する監査記録が作成されます。

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

RoleReferenceCollection [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する

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

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する

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

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]"
}

ロールリファレンス

RoleReference [application/vnd.com.nsn.cumulocity.roleReference+json]

名称 種別 発生回数 説明
self URI 1 このリソースへのリンク
role Role 1 参照されるロールリソース