デバイス認証情報

概要

デバイス認証情報インターフェースは以下の要素で構成されます。

  • デバイスリクエストは、新規デバイスをテナントに登録する際に使用されます。
  • デバイス認証情報は、登録済みデバイスに認証情報を提供します。
  • デバイス認証情報は、一括認証情報プロビジョンにエンドポイントを提供します。

デバイス登録プロセスについて詳しくは「デバイス統合」セクションをご覧ください。

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

新規デバイスリクエストコレクション

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

新規デバイスリクエスト

NewDeviceRequest [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 - 新規デバイスリクエストを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は、通常、テナントへのアクセス権を持たないデバイスから利用されます。そのデバイスはあなたの認証情報を持たないため、このAPI固有の認証情報が使用してアクセスし、認証情報を取得します。このAPI固有の認証情報はサポート担当にお問い合わせいただければ取得可能です。他の一般ユーザーの認証情報ではこのAPIは使用できません。

DeviceCredentials [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 - デバイス識別情報リクエストを作成する

リクエスト本体:deviceCredentials

応答本体:deviceCredentials

要求されるロール: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つのセクションがなければなりません。

1つ目ののセクションはCSVの1行目です。この行は以下のカラム名(ヘッダー)を格納します。

名称 発生回数 説明
ID 1 デバイスの外部ID
CREDENTIALS 1 デバイスのユーザーが使用するパスワード
TENANT 0..1 登録実行対象のテナント名(マネジメントテナントに限り許可されます)
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 デバイスが追加されるグループ階層内のパス。パスは各グループの名称を格納し、「/」で以下のように区切られます:Main group/Subgroup/.../Last subgroup。グループが存在しない場合、インポートするとグループが作成されます。
SHELL 0..1 このカラムが値1を格納する場合、インポートするとデバイスに「シェル」機能が加わります(具体的にはc8y_SupportedOperationsフラグメント)。「Shell」値は各行に必須ではありません。下記のHTTPリクエストの例をご覧ください。

2つ目のセクションはCSVファイルの残り部分で、デバイス情報を格納します。値の順序と数量は、ヘッダーの順序および数量と同じでなければなりません。

セパレータはCSVファイルから自動的に取得されます。有効なセパレータ値は以下の通りです:'\t - タブ記号', '; - セミコロン' および ', - コンマ'。 CSVファイルは多くの形態で表示可能です(デバイス情報における任意のテナントカラムと発生回数に関して)。

  • ユーザーがマネジメントテナントとして記録される場合、「id」、「credentials」および「tenant」のカラムは必須です。デバイスの認証情報は「tenant」カラムに記載のテナントについて作成されます。
  • ユーザーが「非マネジメントテナント」として、すなわちsample_tenantとして記録される場合、「id」と「credentials」のカラムが必須です(ファイルに「tenant」カラムが含まれていても無視され、デバイスの認証情報はログイン中のテナントについて作成されます)。
  • ユーザーがデバイスに関する情報を追加したい場合、「type」と「name」のカラムがCSVファイルに表示されなければなりません。
  • ユーザーがSIMカードに関する情報を追加したい場合、「type」、「name」および「iccid」のカラムがCSVファイルに表示されなければなりません。
  • ユーザーが外部IDの種別を変更したい場合、「type」、「name」および「idtype」のカラムがCSVファイルに表示されなければなりません。
  • ユーザーがデバイスをグループに追加したい場合、「type」、「name」および「path」のカラムがCSVファイルに表示されなければなりません。
  • ユーザーがシェル機能を追加したい場合、「type」、「name」および「shell」のカラムがCSVファイルに表示され、「shell」カラムの値は1でなければなりません。

新しく生成したデバイスの登録の際、カスタムデバイスプロパティやカスタム外部IDマッピングを定義することができます:

  • カスタム外部IDマッピングを追加するには、外部IDタイプとして「external-」プレフィックスをつけ、上記ヘッダーに配置します。例えば、タイプ「c8y_Imei」の外部IDマッピングを追加する場合、上述のカラムヘッダーに「external-c8y_Imei」を追加します。この外部IDタイプの値は、データ行の対応するカラムに記述してください。
  • 登録されたデバイスにカスタムプロパティを追加するには、ヘッダーにカスタムプロパティ名を追加してください。例えば、「myCustomProperty」とし、その値を下の行に記述します。

BulkNewDeviceRequest [application/vnd.com.nsn.cumulocity.bulkNewDeviceRequest+json]

名称 種別 発生回数 説明
numberOfAll Number 1 CSVファイルから処理される行数、ただし1行目(カラムヘッダー)を除く
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

応答本体:bulkNewDeviceRequest

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