識別情報

概要

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

注記:すべてのPUT / POSTリクエストに対して「accept」ヘッダーを使用する必要があります。そうでない場合は、空の応答本体が返されます。

識別情報API

識別情報 [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}).

GET - 識別情報APIリソースの取得

応答本体: 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 コレクション

外部 ID コレクション [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」のプロパティと、マネージドオブジェクトに対するリファレンスを含みます。

GET - 外部IDコレクションの取得

応答本体: ExternalIdCollection

要求されるロール: 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を作成する

リクエスト本体: ExternalId

応答本体: ExternalId

要求されるロール: 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 Things Cloudがインターフェース接続する相手方である外部システムで使用される識別情報 必須
self URI 1 このリソースへのリンク なし
type String 1 文字列としての外部識別情報のタイプ。例:com_cumulocity_model_idtype_SerialNumber 必須
managedObject ManagedObject 1 外部IDにリンクされるマネージドオブジェクト 必須

GET - 外部IDの取得

応答本体: ExternalId

要求されるロール: 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>>"
  }
}

DELETE - 外部IDの削除

リクエスト本体: N/A.

応答メッセージ本体: N/A.

要求されるロール: ROLE_IDENTITY_ADMIN

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

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

応答例:

HTTP/1.1  204 NO CONTENT