エイリアス、メタデータ、ラベルを使用する

📘
注
エイリアスAPIエンドポイントは非推奨です。

トラッキングバックエンドを外部システムと統合するときは、多くの場合、トラッカーデバイスを外部システムIDと関連付ける必要があります。たとえば、外部管理システムのアセットIDや人間が読める名前を使用できます。

HERE Tracking APIでは、任意のtypeとexternalIdのペアをtrackingIdと関連付けることができます。これらの関連付けは「エイリアス」と呼ばれます。

エイリアスtypeとexternalIdを指定して、デバイスデータと一緒に保存できます。その後、そのエイリアスを参照することで、デバイスレコードを取得できます。

以下のリクエスト例では、エイリアスtypeはtestTypeで、externalIdはtestExternalIdです。 trackingIdはユーザーが登録した仮想デバイスのトラッキングIDです。

エイリアスはaliasesエンドポイントを介して作成されます。

curl -X PUT \
  https://{tcHost}/aliases/v2/{trackingId}/testType/testExternalId

これによりエイリアスが作成されます。エイリアスが作成されると、そのエイリアスを使用してデバイスの詳細を取得できます。

curl -X GET
  https://{tcHost}/aliases/v2/{trackingId}?type=testType&externalId=testExternalId

{
  "trackingId": "HERE-dummyTrackingId"
}

これにより、デバイスのtrackingIdが返されます。

メタデータ

これは、デバイスのIDやテレメトリーに直接関連しない、デバイスやジオフェンスに関するデータを保存するのにも便利です。たとえば、Webインターフェースに表示されるアイコンや、特定のジオフェンスに関する詳細なメモです。これにはメタデータサービスを使用します。デバイスに関するメタデータを保存するには、任意のJSONオブジェクトをmetadataエンドポイントに送信します。

curl -X PUT \
  https://{tcHost}/metadata/v2/devices/{trackingId} \
  -H 'Authorization: Bearer {userToken}' \
  -H 'Content-Type: application/json' \
  -d '{
    "deviceIcon": "car-icon.png"
}'

メタデータは同様の方法でジオフェンスに関連付けることができます。

curl -X PUT \
  https://{tcHost}/metadata/v2/geofences/{geofenceId} \
  -H 'Authorization: Bearer {userToken}' \
  -H 'Content-Type: application/json' \
  -d '{
    "geofenceIcon": "office-icon.png"
}'

ラベル

ラベルはキーと値のペアで、次のリソースタイプに関連付けることができます。

device
geofence
sensor
rule
location
shipment たとえば、デバイスを異なるグループにグループ化する必要がある場合、デバイスを「group」というラベルに関連付けることができます。この場合、ラベルの値はグループ名になります。ラベルは、labelsエンドポイントのPUTリクエストのパスでリソースタイプ、リソースID、およびラベルのキーと値のペアを指定することによって作成されます。次の例では、デバイスラベルを作成しています。ラベルkeyはgroupで、ラベルvalueはgroup-01です。 trackingIdはユーザーが登録した仮想デバイスのトラッキングIDです。

curl -X PUT \
  https://{tcHost}/labels/v4/device/{trackingId}/{key}/{value} \
  -H 'Authorization: Bearer {userToken}' \
  -H 'Content-Type: application/json'

特定のリソースタイプに関連付けられているすべてのラベルは、パス内のリソースタイプを含むlabelsエンドポイントを介して取得できます。ユーザーが複数のプロジェクトのメンバーである場合は、クエリパラメーターprojectIdでターゲットプロジェクトIDを指定する必要があります。

curl -X GET \
  https://{tcHost}/labels/v4/device?projectId=`projectId` \
  -H 'Authorization: Bearer {userToken}' \
  -H 'Content-Type: application/json'

{
 "limit":100,
 "count":1,
 "items":[{
  "resourceId":"HERE-dummyTrackingId",
  "resourceType":"device",
  "labels":{
  	"group":["group-01"]
  }
 }]
}

特定のリソースに関連付けられているラベルは、リソースタイプとリソースIDを含むlabelsエンドポイントを介して取得できます。

curl -X GET \
  https://{tcHost}/labels/v4/device/{trackingId} \
  -H 'Authorization: Bearer {userToken}' \
  -H 'Content-Type: application/json'

{
  "resourceId":"HERE-dummyTrackingId",
  "resourceType":"device",
  "labels":
  {
    "group":["group-01"],
    "priority":["high"]
  }
}