开发者中心

身份标识

身份标识接口将外部IT系统和设备中使用的标识符与QuickIoE中使用的唯一标识符相关联。 它由三部分组成:

  • 身份标识API资源返回用于将外部标识符与唯一标识符相关联的URI和URI模板。
  • 外部ID集合资源包含唯一ID的一组外部ID。
  • 外部ID资源表示可以查询和删除的单个外部标识。

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

身份标识API

身份标识 [application/vnd.com.nsn.cumulocity.identityApi+json]
名称 类型 次数 描述
self URL 1 资源链接。
externalId ExternalID URI template 1 单个外部ID, 由外部ID的类型和外部ID的值表示, 均为字符串(占位符 {type} 和 {value})。
externalIdsOfGlobalId ExternalIDCollection URI template 1 表示指定全局ID的外部ID集合 (占位符 {globalId})。
GET - 查询身份标识API资源

应答正文: 身份识别Api

所需角色: ROLE_IDENTITY_READ

请求示例:

GET /identity
                        Host: ...
                        Authorization: Basic ...
                      

应答示例:


    HTTP/1.1 200 OK
    Content-Type: application/vnd.com.nsn.cumulocity.identityApi+json;ver=...
    Content-Length: ...
    {
    "self" : "<<Identity API URL>>",
    "externalId" : "<<ExternalId URL>>/{type}/{externaId}",
    "externalIdsOfGlobalId" : "<<GlobalIdCollection URL>>/{globalId}/externalIds"
      }
                      

外部ID集合

外部ID集合 [application/vnd.com.nsn.cumulocity.externalIdCollection+json]

由"externalIdsOfGlobalId"返回。

名称 类型 次数 描述
self URI 1 资源链接。
externalIds ExternalId 0..n 外部ID列表, 如下所示。
prev URI 0..1 上一页链接。
next URI 0..1 下一页链接。

集合中包含的外部ID包含属性"self", "externalId", "type"和对托管对象的引用。

GET - 查询外部Id集合

应答正文: 外部Id集合

所需角色: ROLE_IDENTITY_READ

应答示例:


        HTTP/1.1 200 OK
        Content-Type: application/vnd.com.nsn.cumulocity.externalIdCollection+json;ver=...
        Content-Length: ...
        {
        "self" : "<<ExternalIdCollection URL>>",
        "externalIds" :[
        {
        "self" : "<<ExternalId URL>>",
        "externalId" : "42",
        "type" : "theregate",
        "managedObject" : {        "id" : "24",
        "self" : "<<URL to the Managed Object>>"
      }
    },
    {
    ...
  }
  ]
}
                      
POST - 创建外部ID

请求正文: 外部Id

应答正文: 外部Id

所需角色: ROLE_IDENTITY_ADMIN

请求示例:


    POST /identity/globalIds/<<deviceId>>/externalIds
    Host: ...
    Authorization: Basic ...
    Accept: application/vnd.com.nsn.cumulocity.externalId+json;ver=...
    Content-Type: application/vnd.com.nsn.cumulocity.externalId+json;ver=...
    Content-Length: ...

    {
    "externalId" : "42",
    "type" : "theregate"
  }
                    

应答示例:


    HTTP/1.1 201 Created
    Content-Type: application/vnd.com.nsn.cumulocity.externalId+json;ver=...
    Content-Length: ...
    Location: <<URL of new ExternalId mapping>>

    {
    "self" : "<<URL of new ExternalId mapping>>",
    "externalId" : "42",
    "type" : "theregate",
    "managedObject" : {
    "id" : "24",
    "self" : "<<URL to the Managed Object>>"
  }
}
                    

注意, 必须首先创建托管对象, 然后可以注册映射。

外部ID

外部ID [application/vnd.com.nsn.cumulocity.externalId+json]
名称 类型 次数 描述 PUT/POST
externalId String 1 在QuarkIoE接口的外部系统中使用的标识符。 必选
self URI 1 资源链接。
type String 1 外部标识符的类型为字符串, 例如 "com_cumulocity_model_idtype_SerialNumber"。 必选
managedObject ManagedObject 1 托管对象链接到外部ID。 Mandatory
GET - 查询外部ID

应答正文: 外部Id

所需角色: ROLE_IDENTITY_READ

Example request:


    GET /identity/externalIds/<<externalIdType>>/<<externalId>>
    Host: ...
    Authorization: Basic ...
    Accept: application/vnd.com.nsn.cumulocity.externalId+json;ver=...
                    

应答示例:


    HTTP/1.1 200 OK
    Content-Type: application/vnd.com.nsn.cumulocity.externalId+json;ver=...
    Content-Length: ...

    {
    "externalId" : "42",
    "self" : "<<URL to this ExternalID mapping>>",
    "type" : "com_cumulocity_model_idtype_SerialNumber",
    "managedObject" : {
    "id" : "24",
    "self" : "<<URL to the Managed Object>>"
  }
}
                    
DELETE - 删除外部ID

请求正文: N/A.

应答正文: N/A.

所需角色: ROLE_IDENTITY_ADMIN

请求示例: Delete an External ID


  DELETE /identity/externalIds/<<externalIdType>>/<<externalId>>
  Host: [hostname]
  Authorization: Basic xxxxxxxxxxxxxxxxxxx
                    

应答示例:


  HTTP/1.1  204 NO CONTENT