租户接口组成:

• 租户集合资源, 通过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]

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]

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,

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].

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].

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].

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

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

缺省选项

选项 [application/vnd.com.nsn.cumulocity.option+json]

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

使用量统计

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

• "deviceCount", "deviceWithChildrenCount" 和 "storageSize" 每6小时更新。
• "storageSize" 受留存规则影响。也受定期执行的数据库优化函数影响。如果数值变小, 不一定意味着数据被删除了。
• 天数按服务器时区计算。

租户使用量统计集合 [application/vnd.com.nsn.cumulocity.tenantUsageStatisticsCollection+json]

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