租户
租户接口组成:
- 租户集合资源, 通过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"
]
}