識別情報

概要

識別情報インターフェースは、外部のITシステムおよびデバイスで使用される識別情報を、Things Cloudで使用される固有の識別情報と関連付けます。 このインターフェースは以下の3つの要素で構成されます。

  • 「識別情報」APIは、外部識別情報を固有識別情報と関連付けるためのURIおよびURIテンプレートを返します。
  • 「外部IDコレクション」リソースは、1つの固有IDにおける一連の外部IDを格納します。
  • 「外部ID」リソースは、クエリおよび削除が可能な個々の外部IDを表わします。

注記:すべてのPUT/POSTリクエストについて、acceptヘッダーを使用すべきであり、さもなければ空の応答本体が返されます。

識別情報API

Identity [application/vnd.com.nsn.cumulocity.identityApi+json]

名称 種別 発生回数 説明
self URL 1 このリソースへのリンク
externalId ExternalID URI template 1 単一の外部IDを、外部IDの種別および値により、いずれも文字列として表わしたもの(プレースホルダ:{type} および{value})
externalIdsOfGlobalId ExternalIDCollection URI template 1 指定されたグローバルIDについての外部IDのコレクションを表わします(プレースホルダ:{globalId})

識別情報APIリソースをGETする

応答本体: identityApi

要求されるロール: 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 コレクション

ExternalIDCollection [application/vnd.com.nsn.cumulocity.externalIdCollection+json]

"externalIdsOfGlobalId"によって返されるもの

名称 種別 発生回数 説明
self URI 1 このリソースへのリンク
externalIds ExternalId 0..n 外部IDのリスト(下記参照)
prev URI 0..1 外部IDの潜在的な前のページへのリンク
next URI 0..1 外部IDの潜在的な次のページへのリンク

コレクションに含まれる外部IDは「self」、「externalId」、「type」のプロパティと、マネージドオブジェクトに対するリファレンスを含みます。

外部IDコレクションをGETする

応答本体:外部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

Example Request:

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

Example Response:

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

External ID [application/vnd.com.nsn.cumulocity.externalId+json]

名称 種別 発生回数 説明 PUT/POST
externalId String 1 Things Cloudがインターフェース接続する相手方である外部システムで使用される識別情報 必須
self URI 1 このリソースへのリンク 非必須
type String 1 文字列としての外部識別情報の種別。例:com_cumulocity_model_idtype_SerialNumber 必須
managedObject ManagedObject 1 外部IDにリンクされるマネージドオブジェクト 必須

外部IDをGETする

応答本体:外部ID

要求されるロール: ROLE_IDENTITY_READ

リクエスト例:

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

外部IDをDELETEする

リクエスト本体:N/A

応答本体:N/A

要求されるロール: ROLE_IDENTITY_ADMIN

リクエスト例:外部IDを削除する

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

応答例:

HTTP/1.1  204 NO CONTENT