开发者中心

租户

租户

租户接口组成:

  • 租户集合资源, 通过url /tenant/tenants 访问
  • 代表单个租户的租户资源, 通过url /tenant/tenants/{租户Id}访问
  • 租户应用程序集合资源, 通过url /tenant/tenants/{租户Id}/applications 访问
  • 代表租户的单个应用程序资源, 通过url /tenant/tenants/{租户Id}/applications/{应用程序Id}访问
  • 租户选项集合资源, 通过url /tenant/options访问
  • 代表租户的单个选项资源, 通过url /tenant/options/{optionCategory}/{optionKey} 访问
  • 租户使用量统计资源, 用于返回租户的请求负载和数据库使用量。

注意: 所有的PUT/POST请求必须设置accept头, 否则会返回空的应答正文。

租户集合

租户集合 [application/vnd.com.nsn.cumulocity.tenantCollection+json]
名称 类型 次数 描述
self URI 1 此资源链接地址。
tenants Tenant 0..n 租户的列表, 如下所示。
statistics PagingStatistics 1 分页统计信息。
prev URI 0..1 上一页链接。
next URI 0..1 下一页链接。
GET - 查询租户集合

应答正文: 租户集合

所需角色: ROLE_TENANT_MANAGEMENT_READ

请求示例: 查询租户。

GET /tenant/tenants
                        Host: ...
                        Authorization: Basic ...
                    

应答示例 :


HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.tenantCollection+json;ver=...
Content-Length: ...
{
"statistics": {
"currentPage": 1,
"pageSize": 5,
"totalPages": 1
},
"self": "<<集合URL>>",
"tenants": [
{
"adminName": "admin",
"allowCreateTenants": false,
"storageLimitPerDevice": 10485760,
"applications": {
"references": [],
"self":"<<此租户的应用程序集合URL>>",
},
"company": "sample_company",
"domain": "sample_domain.com",
"id": "sample_tenant",
"ownedApplications": {
"references": [
{
"application": {
"availability": "PRIVATE",
"id": "5",
"key": "<<哈希值>>",
"name": "sample_private_application",
"owner": {
"self":"<<应用程序所有者租户URL>>",
"tenant": {
"id": "sample_tenant"
}
},
"self":"<<应用程序5 URL>>",
"type": "EXTERNAL"
},
"self":"<<此租户用用程序5 URL>>",
},
...
],
"self":"<<此租户应用程序集合URL>>",
},
"self":"<<此租户URL>>",
"parent": "parentTenant",
"status": "ACTIVE"
},
{
"applications": {
"references": [],
"self": "<<此租户应用程序集合URL>>",
},
"company": "sample_company",
"domain": "sample_domain.com",
"id": "next_sample_tenant",
"ownedApplications": {
"references": [
{
"application": {
"availability": "MARKET",
"id": "6",
"key": "哈希值",
"name": "market_application",
"owner": {
"self":"<<应用程序所有者租户URL>>",
"tenant": {
"id": "next_sample_tenant"
}
},
"self":"<<应用程序6 URL>>",
"type": "EXTERNAL"
},
"self":"<<此租户应用程序6 URL>>",
}
],
"self":"<<此租户应用程序集合URL>>",
},
"self":"<<此租户URL>>",
},
...
]
}
POST - 创建新租户

请求正文: 租户

应答正文: 租户

所需角色: ROLE_TENANT_MANAGEMENT_ADMIN

请求示例:

POST /tenant/tenants
    Host: ...
    Authorization: Basic ...
    Content-Length: ...
    Content-Type: application/vnd.com.nsn.cumulocity.tenant+json;ver...

    {
    "id" : "sample_tenant",
    "company" : "sample_company",
    "domain" : "sample_domain.com",
    "contactName" : "Mr. Doe",
    "contactPhone" : "0123-4567829",
    "adminEmail" : "john.doe@sample_domain.com",
    "adminName" : "firstAdmin",
    "adminPass" : "myPassword",
    "customProperties" : {"referenceId":"1234567890"},
    "sendPasswordResetEmail": true
}

应答示例:

HTTP/1.1 201 Created
    Content-Type: application/vnd.com.nsn.cumulocity.tenant+json;ver=...
    Content-Length: ...
    Location: <<新租户URL>>

    {
    "id" : "sample_tenant",
    "allowCreateTenants": false,
    "self" : "<<新租户URL>>",
    "company" : "sample_company",
    "domain" : "tenant_nsn.com",
    "contactName" : "Mr. Doe",
    "contactPhone" : "0123-4567829",
    "status" : "ACTIVE",
    "adminName" : "firstAdmin",
    "parent": "parentTenant",
    "adminEmail" : "john.doe@sample_domain.com",
    "customProperties" : {"referenceId":"1234567890"}
}

租户

租户 [application/vnd.com.nsn.cumulocity.tenant+json]
名称 类型 次数 描述 可见性
self URI 0..1 此资源链接地址。 Public
id String: max length="32" 1 租户id Public
status String 1 租户状态, 值可能为 [ACTIVE, SUSPENDED]。 Private
adminName String: max length = "50" 1 管理员用户名 Private
adminEmail String 1 管理员Email Private
allowCreateTenants boolean 1 允许此租户创建子租户。 Private
storageLimitPerDevice number 1 每设备存储配额。 Private
adminPassword String 1 管理员密码 Private
sendPasswordResetEmail boolean 1 允许重置密码 Private
domain String: max length = "256" 1 租户域名URL。 Public
company String: max length = "256" 1 租户公司名称。 Public
contactName String: max length = "30" 1 联系人名称。 Public
contactPhone String: max length= "20" 1 联系人电话号码。 Public
applications ApplicationReferenceCollection 1 租户订阅的应用程序集合。 Private
ownedApplications ApplicationReferenceCollection 1 租户拥有的应用程序集合。 Public - 只针对MARKET应用程序 ,
customProperties Object 1 自定义属性列表 可选
parent String 1 父租户名称, 此租户的创建者。 Public
GET - 查询租户

应答正文: 租户

所需角色: ROLE_TENANT_MANAGEMENT_READ

请求示例: 查询单个租户。

GET /tenant/tenants/<<租户Id>>
                    Host: ...
                    Authorization: Basic ...
                    Accept: application/vnd.com.nsn.cumulocity.tenant+json;ver=...
                

应答示例:


   HTTP/1.1 200 OK
    Content-Type: application/vnd.com.nsn.cumulocity.tenant+json;ver=...
    Content-Length: ...
    {
    "adminName": "admin",
    "applications": {
    "references": [],
    "self":"<<此租户应用程序集合URL>>",
},
"company": "sample_company",
"domain": "sample_domain.com",
"allowCreateTenants": false,
  "storageLimitPerDevice": 10485760,
"id": "sample_tenant",
"ownedApplications": {
"references": [
{
    "application": {
    "availability": "PRIVATE",
    "id": "5",
    "key": "<<哈希值>>",
    "name": "sample_private_application",
    "owner": {
    "self":"<<应用程序所有者租户URL>>",
    "tenant": {
    "id": "sample_tenant"
}
},
"self":"<<应用程序5 URL>>",
"type": "EXTERNAL"
},
"self":"<<此租户应用程序5 URL>>",
},
...
],
"self":"<<此租户应用程序集合URL>>",
},
"self":"<<此租户URL>>",
"parent": "parentTenant",
"status": "ACTIVE"
}
PUT - 更新已有租户

请求正文: 租户

应答正文: 租户

所需租户: ROLE_TENANT_MANAGEMENT_ADMIN

请求示例:

PUT /tenant/tenants/<<租户Id>>
    Host: ...
    Authorization: Basic ...
    Content-Length: ...
    Accept: application/vnd.com.nsn.cumulocity.tenant+json;ver=...
    Content-Type: application/vnd.com.nsn.cumulocity.tenant+json;ver=...

    {
    "adminName" : "newAdmin"
}

应答示例:

HTTP/1.1 200 OK
    Content-Type: application/vnd.com.nsn.cumulocity.tenant+json;ver=...
    Content-Length: ...
    {
    "id": "sample_tenant",
    "self":"<<此租户应用程序集合URL>>",
    "company": "sample_company",
    "domain": "sample_domain.com",
    "status": "ACTIVE",
    "self":"<<此租户URL>>",
    "allowCreateTenants": false,
"storageLimitPerDevice": 10485760, "parent": "parentTenant", "ownedApplications": { "references": [ { "application": { "availability": "PRIVATE", "id": "5", "key": "<<哈希值>>", "name": "sample_private_application", "owner": { "self":"<<应用程序所有者租户URL>>", "tenant": { "id": "sample_tenant" } }, "self":"<<应用程序5 URL>>", "type": "EXTERNAL" }, "self":"<<此租户应用程序5 URL>>", }, ... ], }, "adminName" : "newAdmin" }

DELETE - 删除租户

请求正文: N/A

应答正文: N/A

所需角色: ROLE_TENANT_MANAGEMENT_ADMIN

请求示例:

DELETE /tenant/tenants/<<租户Id>>
    Host: [主机名]
    Authorization: Basic xxxxxxxxxxxxxxxxxxx

应答示例:

HTTP/1.1  204 NO CONTENT

应用程序集合

应用程序集合 [application/vnd.com.nsn.cumulocity.applicationReferenceCollection+json].
名称 类型 次数 描述
self URI 1 此资源链接地址。
references ApplicationReference 0..n 选项列表, 如下所示。
statistics PagingStatistics 1 分页统计信息。
prev URI 0..1 上一页链接。
next URI 0..1 下一页链接。
GET - 查询应用程序集合

应答正文: 应用程序集合

所需角色: ROLE_TENANT_MANAGEMENT_READ

请求示例: 查询应用程序集合。

GET /tenant/tenants/<<租户Id>>/applications
    Host: ...
    Authorization: Basic ...
    Accept: application/vnd.com.nsn.cumulocity.applicationReferenceCollection+json;ver=...

应答示例:

HTTP/1.1 200 OK
    Content-Type: application/vnd.com.nsn.cumulocity.applicationReferenceCollection+json;ver=...
    Content-Length: ...
    {
    "self" : "<<集合URL>>",
    "references": [
    {
    "application": {
    "availability": "PRIVATE",
    "id": "5",
    "key": "<<哈希值>>",
    "name": "sample_private_application",
    "owner": {
    "self":"<<应用程序所有者租户URL>>",
    "tenant": {
    "id": "sample_tenant"
}
},
"self":"<<应用程序5 URL>>",
"type": "EXTERNAL"
},
"self":"<<此租户应用程序5 URL>>",
},
...
],
"statistics" : {
"totalPages" : 1,
"pageSize" : 5,
"currentPage" : 1
},
"next" : "...",
"prev" : "..."
}

应用程序

应用程序 [application/vnd.com.nsn.cumulocity.applicationReference+json].
名称 类型 次数 描述
self URI 1 此资源链接地址。
reference Application 0..n 引用的应用程序
GET - 查询应用程序

应答正文: 应用程序

所需角色: ROLE_TENANT_MANAGEMENT_READ

请求示例: 查询应用程序。

GET /tenant/tenants/<<租户Id>>/applications/<<应用程序Id>>
    Host: ...
    Authorization: Basic ...
    Accept: application/vnd.com.nsn.cumulocity.applicationReference+json;ver=...

应答示例:

HTTP/1.1 200 OK
    Content-Type: application/vnd.com.nsn.cumulocity.applicationReference+json;ver=...
    Content-Length: ...
    {
    "application": {
    "availability": "PRIVATE",
    "id": "5",
    "key": "<<哈希值>>",
    "name": "sample_private_application",
    "owner": {
    "self":"<<应用程序所有者租户URL>>",
    "tenant": {
    "id": "sample_tenant"
}
},
"self":"<<应用程序5 URL>>",
"type": "EXTERNAL"
},
"self":"<<此租户应用程序5 URL>>",
}

选项集合

选项集合 [application/vnd.com.nsn.cumulocity.optionCollection+json].
名称 类型 次数 描述
self URI 1 此资源链接地址。
options Option 0..n 选项列表, 如下所示。
statistics PagingStatistics 1 分页统计信息。
prev URI 0..1 上一页链接。
next URI 0..1 下一页链接。
GET - 查询选项集合

应答正文: 选项集合

所需角色: ROLE_OPTION_MANAGEMENT_READ

请求示例: 查询选项。

GET /tenant/options
    Host: ...
    Authorization: Basic ...
    Accept: application/vnd.com.nsn.cumulocity.optionCollection+json;ver=...

应答示例:

HTTP/1.1 200 OK
    Content-Type: application/vnd.com.nsn.cumulocity.optionCollection+json;ver=...
    Content-Length: ...
    {
    "self" : "<<Collection URL>>",
    "options": [
    {
    "category": "access.control",
    "key": "allow.origin",
    "self": "<<Option access.control.allow.origin URL>>",
    "value": "*"
},
...
],
"statistics" : {
"totalPages" : 1,
"pageSize" : 5,
"currentPage" : 1
},
"next" : "...",
"prev" : "..."
}
POST - 创建选项

请求正文: 选项

应答正文: 选项

所需角色: ROLE_OPTION_MANAGEMENT_ADMIN

请求示例: 创建选项。

POST /tenant/options
    Host: ...
    Authorization: Basic ...
    Content-Type: application/vnd.com.nsn.cumulocity.option+json;ver=...
    Accept: application/vnd.com.nsn.cumulocity.option+json;ver=...
    {
    "category" : "alarm.type.mapping",
    "key": "temp_too_high",
    "value": "CRITICAL|temperature too high"
}

应答示例:

HTTP/1.1 200 OK
    Content-Type: application/vnd.com.nsn.cumulocity.option+json;ver=...
    Content-Length: ...
    {
    "self" : "<<Option alarm.type.mapping.temp_too_high URL>>"
    "category" : "alarm.type.mapping",
    "key": "temp_too_high",
    "value": "CRITICAL|temperature too high"
}

选项

选项是"类别-键-值"三元组, 保存租户配置。有些选项类别运行新创建, 有些只能是使用预定义键。

缺省选项
类别 缺省值 只能预定义 描述
access.control allow.origin * 逗号分隔的允许跨域访问(CORS)的域名列表。 支持通配符 (例如 *.cumulocity.com)
alarm.type.mapping <<alarmType>> 覆盖类型为"<<alarmType>>"的严重级别和报价文本。严重级别和文本是"<<alarmSeverity>>|<<alarmText>>"。如果文本为空则不覆盖。如果严重级别为"NONE", 则不报警。
选项 [application/vnd.com.nsn.cumulocity.option+json]
名称 类型 次数 描述
self URI 0..1 此资源链接地址。
category String 1 选项类别
key String 1 选项键
value String 1 选项值
GET - 查询选项

应答正文: 选项

所需角色: ROLE_OPTION_MANAGEMENT_READ 请求示例: 查询单个选项。

GET /tenant/options/<<类别>>/<<键>>
    Host: ...
    Authorization: Basic ...
    Accept: application/vnd.com.nsn.cumulocity.option+json;ver=...

应答示例:

HTTP/1.1 200 OK
    Content-Type: application/vnd.com.nsn.cumulocity.optionCollection+json;ver=...
    Content-Length: ...
    {
    "category": "access.control",
    "key": "allow.origin",
    "self": "<<Option access.control.allow.origin URL>>",
    "value": "*"
}
PUT - 更新选项

请求正文: 选项

应答正文: 选项

所需角色: ROLE_OPTION_MANAGEMENT_ADMIN 请求示例: 更新access.control.allow.origin选项。

PUT /tenant/options/<<类别>>/<<键>>
    Host: ...
    Authorization: Basic ...
    Content-Type: application/vnd.com.nsn.cumulocity.option+json;ver=...
    Accept: application/vnd.com.nsn.cumulocity.option+json;ver=...
    {
    "value": "http://developer.cumulocity.com"
}

应答示例:

HTTP/1.1 200 OK
    Content-Type: application/vnd.com.nsn.cumulocity.option+json;ver=...
    Content-Length: ...
    {
    "category": "access.control",
    "key": "allow.origin",
    "self": "<<Option access.control.allow.origin URL>>",
    "value": "http://developer.cumulocity.com"
}
PUT - 更新类别中的多个选项

请求正文: 选项

应答正文: 选项

所需角色: ROLE_OPTION_MANAGEMENT_ADMIN 请求示例: 更新类别中的选项。

PUT /tenant/options/<<类别>>
    Host: ...
    Authorization: Basic ...
    Content-Type: application/vnd.com.nsn.cumulocity.option+json;ver=...
    Accept: application/vnd.com.nsn.cumulocity.option+json;ver=...
    {
    "key1": "value1",
    "key2": "value2",
    "key3": "value3",
    "key4": "value4"
}

应答示例:

HTTP/1.1 200 OK
    Content-Type: application/vnd.com.nsn.cumulocity.option+json;ver=...
GET - 查询类别中的选项

应答正文: 选项

所需角色: ROLE_OPTION_MANAGEMENT_READ 请求示例: 查询特定类别中的选项。

GET /tenant/options/<<类别>>
    Host: ...
    Authorization: Basic ...
    Accept: application/vnd.com.nsn.cumulocity.option+json;ver=...

应答示例:

HTTP/1.1 200 OK
    Content-Type: application/vnd.com.nsn.cumulocity.optionCollection+json;ver=...
    Content-Length: ...
    {
    "key1": "value1"
    "key2": "value2",
    "key3": "value3",
    "key4": "value4",
}

系统选项

平台设置的预定义只读属性。应答格式和选项集合相同。

应答正文: 选项集合

所需角色: ROLE_OPTION_MANAGEMENT_READ

请求示例: 查询系统选项。

GET /tenant/system/options
    Host: ...
    Authorization: Basic ...
    Accept: application/vnd.com.nsn.cumulocity.optionCollection+json;ver=...

应答示例:

HTTP/1.1 200 OK
    Content-Type: application/vnd.com.nsn.cumulocity.optionCollection+json;ver=...
    Content-Length: ...
    {
    "options": [
    {
    "category": "access.control",
    "key": "allow.origin",
    "value": "*"
},
...
],
}

也可以通过在url路径提供类别和id查询单个系统选项:

应答正文: 选项

所需角色: ROLE_OPTION_MANAGEMENT_READ 请求示例: 查询单个选项。

GET /tenant/system/option/<<类别>>/<<id>>
    Host: ...
    Authorization: Basic ...
    Accept: application/vnd.com.nsn.cumulocity.option+json;ver=...

应答示例:

HTTP/1.1 200 OK
    Content-Type: application/vnd.com.nsn.cumulocity.optionCollection+json;ver=...
    Content-Length: ...
    {
    "category": "access.control",
    "key": "allow.origin",
    "value": "*"
}

租户使用量统计

使用量统计
名称 类型 次数 描述
day String 1 统计的日期。
deviceCount Number 1 租户设备数 (c8y_IsDevice)。
deviceRequestCount Number 1 租户设备的请求数。
deviceWithChildrenCount Number 1 包括子设备的设备数。
requestCount Number 1 租户的请求数。
storageSize Number 1 租户使用的数据设备清单储, 单位字节。
subscribedApplications List 1 租户订阅的应用程序名称。

"requestCount" 和 "deviceRequestCount" 包含查询周期内的请求总和。 "deviceCount" 和 "storageSize" 包含查询周期的最后报告值。请注意:

  • "deviceCount", "deviceWithChildrenCount" 和 "storageSize" 每6小时更新。
  • "storageSize" 受留存规则影响。也受定期执行的数据库优化函数影响。如果数值变小, 不一定意味着数据被删除了。
  • 天数按服务器时区计算。
租户使用量统计集合 [application/vnd.com.nsn.cumulocity.tenantUsageStatisticsCollection+json]
名称 类型 次数 描述
self URI 1 此资源链接地址。
usageStatistics UsageStatistics 0..n 使用量统计列表, 如下所示。
statistics PagingStatistics 1 分页统计信息。
prev URI 0..1 上一页链接。
next URI 0..1 下一页链接。
GET - 查询租户使用量统计集合

应答正文: 租户使用量统计集合

所需角色: ROLE_TENANT_STATISTICS_READ

请求示例: 查询当前租户从2014年8月1日到今天的使用量统计信息。

GET /tenant/statistics?dateFrom=2014-08-01
    Host: ...
    Authorization: Basic ...

应答示例:

HTTP/1.1 200 OK
    Content-Type: application/vnd.com.nsn.cumulocity.tenantUsageStatisticsCollection+json; charset=UTF-8; ver=0.9
    Content-Length: ...
    {
    "statistics": {
    "currentPage": 1,
    "pageSize": 5,
    "totalPages": 5
},
"self": "<<Collection URL>>",
"usageStatistics": [ {
"day": "2014-08-12T00:00:00.000+02:00",
"deviceCount": 5,
"deviceRequestCount": 101966,
"deviceWithChildrenCount": 5,
"requestCount": 103966,
"self": "...",
"storageSize": 1005442845,
"subscribedApplications": [
"testadmin"
]
},
{
    "day": "2014-08-07T00:00:00.000+02:00",
    "deviceCount": 30,
    "deviceRequestCount": 114378,
    "deviceWithChildrenCount": 38,
    "requestCount": 116378,
    "self": "...",
    "storageSize": 1151862557,
    "subscribedApplications": [
    "testadmin"
    ]
},
...
]
}
GET - 查询所有租户使用量统计概要

应答正文: application/json

所需角色: ROLE_TENANT_MANAGEMENT_READ

请求示例: 查询所有租户从2014年8月1日到今天的统计信息。

GET /tenant/statistics/allTenantsSummary?dateFrom=2014-08-01
    Host: ...
    Authorization: Basic ...

应答示例:

HTTP/1.1 200 OK
    Content-Type: application/json
    Content-Length: ...
    [
    {
    "deviceCount": "5",
    "deviceRequestCount": 114338,
    "deviceWithChildrenCount": 5,
    "requestCount": 116378,
    "tenantId": "tenant1",
    "storageSize": 1151862557,
    "subscribedApplications": [
    "testadmin"
    ]
},
{
    "deviceCount": "2",
    "deviceRequestCount": 114338,
    "deviceWithChildrenCount": 2,
    "requestCount": 116378,
    "tenantId": "tenant2",
    "storageSize": 1151862557,
    "subscribedApplications": [
    "testadmin"
    ]
},
...
]
租户使用量统计信息概要 [application/vnd.com.nsn.cumulocity.tenantUsageStatisticsSummary+json]
GET - 查询租户使用量统计信息概要

应答正文: 租户使用量统计信息概要

所需角色: ROLE_TENANT_STATISTICS_READ

请求示例: 查询本月直到今天的请求和数据库使用量概要信息。

GET /tenant/statistics/summary
    Host: ...
    Authorization: Basic ...

应答示例:

HTTP/1.1 200 OK
    Content-Type: application/vnd.com.nsn.cumulocity.tenantUsageStatisticsSummary+json; charset=UTF-8; ver=0.9
    Content-Length: ...

    {
    "self": "...",
    "day": "2014-08-21T00:00:00.000+02:00",
    "deviceCount": 30,
    "deviceRequestCount": 15006838,
    "deviceWithChildrenCount": 38,
    "requestCount": 15013818,
    "storageSize": 983856925,
    "subscribedApplications": [
    "testadmin"
    ]
}