开发者中心

设备凭证

设备凭证接口由以下部分组成:

  • 设备请求用于向租户注册新设备。
  • 设备凭证为注册的设备提供凭据。
  • 设备凭据为端点提供批量凭据配置。

有关注册设备的更多信息, 请参见 "设备集成"。

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

新设备请求集合

新设备请求集合 [application/vnd.com.nsn.cumulocity.newDeviceRequestCollection+json]
名称 类型 次数 描述
self URL 1 资源链接。
newDeviceRequests New device requests 0..n 新设备请求列表, 如下所示。
statistics PagingStatistics 1 分页统计信息。
prev URI 0..1 上一页链接。
next URI 0..1 下一页链接。
POST - 创建新设备请求

请求正文: 新设备请求

应答正文: 新设备请求

所需角色: ROLE_DEVICE_CONTROL_ADMIN

请求示例:

POST /devicecontrol/newDeviceRequests
                      Content-Type: application/vnd.com.nsn.cumulocity.newDeviceRequest+json;ver=...
                      Accept: application/vnd.com.nsn.cumulocity.newDeviceRequest+json;ver=...
                      Authorization: Basic ...
                      {
                      "id" : "1234",
                    }
                  

应答示例:

HTTP/1.1 201 Created
                    Content-Type: application/vnd.com.nsn.cumulocity.newDeviceRequest+json;ver=...
                    Content-Length: ...
                    {
                    "id" : "1234",
                    "self" : "<<URL of new request>>",
                    "status" : "WAITING_FOR_CONNECTION",
                  }
                
GET - 返回所有新设备请求

应答正文: 新设备请求集合

所需角色: ROLE_DEVICE_CONTROL_READ

请求示例:

GET /devicecontrol/newDeviceRequests
                  Accept: application/vnd.com.nsn.cumulocity.newDeviceRequestCollection+json;ver=...
                  Authorization: Basic ...
                

应答示例:

HTTP/1.1 200 OK
                  Location: <<URL of new operation>>
                  Content-Type: application/vnd.com.nsn.cumulocity.newDeviceRequestCollection+json;ver=...
                  Content-Length: ...
                  {
                  "newDeviceRequests": [{
                  "id" : "1234",
                  "self" : "<<URL of new request>>",
                  "status" : "WAITING_FOR_CONNECTION"
                }, {
                "id" : "12345",
                "self" : "<<URL of new request>>",
                "status" : "WAITING_FOR_CONNECTION" }]
              }
            

新设备请求

新设备请求 [application/vnd.com.nsn.cumulocity.newDeviceRequest+json]
名称 类型 次数 描述
id String 1 设备标识符。 最大: 1000字符, 如 IMEI
status String 1 注册状态, 以下中的一种: WAITING_FOR_CONNECTION, PENDING_ACCEPTANCE, ACCEPTED
self URL 1 资源链接。
GET - 返回新设备请求

应答正文: 新设备请求

所需角色: ROLE_DEVICE_CONTROL_READ

请求示例:

GET /devicecontrol/newDeviceRequests/<<requestId>>
              Authorization: Basic ...
              Accept: application/vnd.com.nsn.cumulocity.newDeviceRequest+json;ver=...
            

应答示例:

HTTP/1.1 200 OK
              Content-Type: application/vnd.com.nsn.cumulocity.newDeviceRequest+json;ver=...
              Content-Length: ...
              {
              "id" : "1234",
              "self" : "<<URL of new request>>",
              "status" : "WAITING_FOR_CONNECTION",
            }
          
DELETE - 删除新设备请求

请求正文: N/A

应答正文: N/A

所需角色: ROLE_DEVICE_CONTROL_ADMIN

请求示例:

DELETE /devicecontrol/newDeviceRequests/<<requestId>>
            Authorization: Basic ...
          

应答示例:

HTTP/1.1 200 OK
          
PUT - 更新新设备请求

请求正文: 新设备请求

应答正文: 新设备请求

所需角色: ROLE_DEVICE_CONTROL_READ

请求示例:

PUT /devicecontrol/newDeviceRequests/<<requestId>>
            Content-Type: application/vnd.com.nsn.cumulocity.newDeviceRequest+json;ver=...
            Accept: application/vnd.com.nsn.cumulocity.newDeviceRequest+json;ver=...
            Authorization: Basic ...
            {
            "status" : "ACCEPTED",
          }
        

应答示例:

HTTP/1.1 200 OK
          Content-Type: application/vnd.com.nsn.cumulocity.newDeviceRequest+json;ver=...
          Content-Length: ...
          {
          "id" : "1234",
          "self" : "<<URL of new request>>",
          "status" : "ACCEPTED",
        }
      

设备凭证

可以由没有用于访问租户的凭证的设备查询设备凭证。 由于设备没有凭证, 因此为此API使用一组固定凭证。 凭证可以通过support@cumulocity.com获得。 不要在此API中使用您的租户凭证。

设备凭证 [application/vnd.com.nsn.cumulocity.deviceCredentials+json]
名称 类型 次数 描述
id String 1 设备标识符, 如 IMEI
tenantId String 1 用于身份验证的租户ID
username String 1 新用户名
password String 1 新密码
self URL 1 资源链接
POST - 创建设备凭证请求

请求正文: 设备凭证

应答正文: 设备凭证

所需角色: ROLE_DEVICE_BOOTSTRAP

请求示例:

POST /devicecontrol/deviceCredentials
        Content-Type: application/vnd.com.nsn.cumulocity.deviceCredentials+json;ver=...
        Accept: application/vnd.com.nsn.cumulocity.deviceCredentials+json;ver=...
        Authorization: Basic ...
        {
        "id" : "12345",
      }
    

应答示例:

HTTP/1.1 201 CREATED
      Content-Type: application/vnd.com.nsn.cumulocity.deviceCredentials+json;ver=...
      Content-Length: ...
      {
      "id" : "12345",
      "tenantId" : "test",
      "username" : "device_1234",
      "password" : "3rasfst4swfa",
      "self" : "<<URL to this device credentials>>"
    }
  

批量设备凭据

设备凭证和设备表示可以从CSV文件提供。 CSV文件必须有2个部分。

第一部分是csv文件的第一行。 此行包含列名称(头):

名称 次数 描述
ID 1 设备的外部id
CREDENTIALS 1 设备用户的密码
TENANT 0..1 执行注册的租户的名称(仅由management租户允许)
TYPE 0..1 设备表示的类型
NAME 0..1 设备表示的名称
ICCID 0..1 设备iccid(sim卡号码)。如果文件中出现'iccid', 导入增加片段'c8y_Mobile.iccid'。 没每行的'Iccid'非必需, 请参看以下的http请求示例
IDTYPE 0..1 外部Id类型。如果文件中没有'idtype', 则使用缺省值。缺省值是'c8y_Serial'。每行的'Idtype'非必需, 请参看以下的http请求示例
PATH 0..1 添加设备的群组层次结构中的路径。 路径包含用'/'分隔的每个组的名称, 即:主群组/子群组/.../最后一个子裙组。 如果裙组不存在, 导入将创建群组
SHELL 0..1 如果此列包含值1,则导入将添加设备'Shell'功能(具体为:c8y_SupportedOperations片段)。 每行的'Shell'非必需, 请参见下面的http请求示例

第二部分是csv文件的其余部分。 第二部分包含设备信息。 值的顺序和数量必须与标题的顺序和数量相同。

分隔符从CSV文件自动获取。 有效的分隔符值为:'\t - 制表符','; - 分号'和', - 逗号'。

CSV文件可以以多种形式显示(根据可选租户列和设备信息是否出现):

  • 当用户作为management租户登录时,列'id', 'credentials'和'tenant'是必需的, 并且将为'tenant'列中提及的租户创建设备凭证,
  • 当用户以'非management'租户如sample_tenant身份登录时, 列: 'id'和'credentials'是必需的(如果文件包含"tenant"列, 则会被忽略, 并且将为登陆的租户创建设备凭证),
  • 当用户想要添加关于设备的信息时, 列的类型和名称必须出现在csv文件中,
  • 当用户想要添加关于SIM卡号的信息时, 列'type', 'name'和'iccid'必须出现在csv文件中,
  • 当用户想要改变外部id的类型时,列的'type', 'name'和'idtype'必须出现在csv文件中,
  • 当用户想要将设备添加到组时, 列的'type', 'name' 和'path'必须出现在csv文件中,
  • 当用户想要添加shell功能时, 列的'type', 'name'和'shell'必须出现在csv文件中, 列'shell'必须包含值1。
批量新设备请求 [application/vnd.com.nsn.cumulocity.bulkNewDeviceRequest+json]
名称 类型 次数 描述
numberOfAll Number 1 从CSV文件处理的行数, 不包括第一行(列抬头)
numberOfCreated Number 1 创建的设备凭证数
numberOfFailed Number 1 设备凭证创建失败的次数
numberOfSuccessful Number 1 成功创建设备凭证的数量, 包含创建和更新操作
credentialUpdatedList List 0..n 已更新设备凭证的阵列
credentialUpdatedList.bulkNewDeviceStatus String 1 设备凭证创建状态, 可能的值: CREATED, FAILED, CREDENTIAL_UPDATED
credentialUpdatedList.deviceId String 1 设备Id
failedCreationList List 0..n 已更新的设备凭证的阵列
failedCreationList.bulkNewDeviceStatus String 1 设备凭证创建状态, 可能的值: CREATED, FAILED, CREDENTIAL_UPDATED
failedCreationList.deviceId String 0..1 设备Id, 如果应用程序可以从文件获取则出现
failedCreationList.failureReason String 1 失败原因
failedCreationList.line String 1 有错误的行
POST - 创建批量设备凭证请求

请求正文: multipart/form-data

应答正文: 批量新设备请求

所需角色: ROLE_DEVICE_CONTROL_ADMIN

请求示例:

POST /devicecontrol/bulkNewDeviceRequests
    Content-Type: multipart/form-data; boundary=myBoundary
    Accept: application/json
    Authorization: Basic ...

    --myBoundary
    Content-Disposition: form-data; name="file"
    Content-Type: plain/text

    ID;CREDENTIALS;TYPE;NAME;ICCID;IDTYPE;PATH;SHELL
    id_101;abcd1234;type_of_device;Device 101;111111111;;csv device/subgroup0;1
    id_102;abcd1234;type_of_device;Device 102;222222222;;csv device/subgroup0;0
    id_111;abcd1234;type_of_device;Device 111;333333333;c8y_Imei;csv device1/subgroup1;0
    id_112;abcd1234;type_of_device;Device 112;444444444;;csv device1/subgroup1;1
    id_121;abcd1234;type_of_device;Device 121;555555555;;csv device1/subgroup2;1
    id_122;abcd1234;type_of_device;Device 122;;;csv device1/subgroup2;
    id_131;abcd1234;type_of_device;Device 131;;;csv device1/subgroup3;
    --myBoundary
  

应答示例:

HTTP/1.1 201 CREATED
    Content-Type: application/vnd.com.nsn.cumulocity.bulkNewDeviceRequest+json;ver=...
    Content-Length: ...
    {
    "credentialUpdatedList" : [
    {
    "bulkNewDeviceStatus" : "CREDENTIAL_UPDATED",
    "deviceId" : "id04"
  }
  ],
  "failedCreationList" : [
  {
  "bulkNewDeviceStatus" : "FAILED",
  "deviceId" : "id04",
  "failureReason" : "failure",
  "line" : "DeviceInfo{id='id5', credentials='credentials3', tenant='tenant3'}"
}
],
"numberOfAll" : 5,
"numberOfCreated" : 3,
"numberOfFailed" : 1,
"numberOfSuccessful" : 4
}