イベントの作成および管理方法
イベントは、関連付けられているルールまたはジオフェンスがデバイスの取り込みによってトリガーされるたびに作成されます。 トラッキングサービスには、次の4つのイベントカテゴリがあります。
| イベントタイプ | 説明 |
|---|---|
| ジオフェンス | デバイスが関連付けられたジオフェンスに出入りするたびに作成されます。 |
| センサー | 報告されたセンサーデータがいずれかのセンサールールをトリガーしたときに作成されます。 |
| ルール | 報告されたデバイスの動作が設定されたルールをトリガーしたときに作成されます。 |
| 出荷ステータス | 出荷ステータスが変更されたときに作成されます。 |
センサーイベントには、次のタイプがあります。
| イベントタイプ | 説明 |
|---|---|
| バッテリー、湿度、圧力、温度イベント | 対応するセンサーの読み取り値が許容範囲に入るか、範囲を超えたときに作成されます。 |
| 加速度 | 加速度センサーの読み取り値が加速度しきい値を超えると作成されます。 |
| 装着 | デバイスが接続または切断されたときに作成されます。 |
| 改ざん | デバイスのカバーが開閉されたときに作成されます。 |
ルールイベントには、次のタイプがあります。
| イベントタイプ | 説明 |
|---|---|
| 滞留 | デバイスが関連付けられているジオフェンス内に許容時間よりも長い間留まっている場合に作成されます。 |
| 留置 | デバイスがジオフェンスの内側にあるか外側にあるかにかかわらず、許容時間よりも長い間静止している場合に作成されます。 |
| 利用 | デバイスが静止後に移動を開始したときに作成されます。 |
| 在庫 | ジオフェンス内のデバイス数が、定義されているいずれかの在庫制限を超えると作成されます。 |
| オフライン | デバイスが次に予定されている取り込みの送信に遅れると作成されます。 |
| オンライン | デバイスがデータの取り込みを再開すると作成されます。 |
| 出荷スケジュール | 出荷が指定した出荷スケジュールから逸脱すると作成されます。 |
| 出荷予定変更 | 新たに計算された到着予定時間 (ETA) または出発予定時間 (ETD) が以前の予定と異なる場合に作成され、出荷スケジュールが調整される可能性があることを示します。 |
新しいイベントと既存のイベントの両方が、eventsエンドポイントを介して管理されます。 イベントはイベント出力ストリームを通じて取得することもできます。これにより、パフォーマンス上の利点が得られる場合があります。
出荷ステータス変更イベント
ルールおよびイベントAPIを介して管理されるイベントに加えて、Shipment status changeイベントはイベント出力ストリームからも利用できます。このイベントはストリーム経由でのみアクセスできます。
プロジェクトでこのイベントが有効になっている場合、コンテンツ、出荷ステータス、またはセグメントステータスに変更が発生するたびに、プロジェクトのすべての出荷に対するイベントがイベント出力ストリームに公開されます。
ただし、これは出荷ETD/ETA値の変更には適用されません。これらの変更は、Shipment estimate changeルールとイベントを使用して追跡できます。
Shipment status changeイベントの構造は他のイベントと同じ構造で、他のイベントと同じ共通のプロパティを持ちますが、値は次のようになります。
| プロパティ | タイプ | 説明 |
|---|---|---|
trackingId | String | 出荷ID |
timestamp | Integer | 変更が発生した正確なタイムスタンプ。1970年1月1日00:00:00 UTCから経過したミリ秒単位で返されます。 |
ruleId | uuid | 出荷状態変更イベントの場合、この値は常に00000000-0000-4000-8000-000000000001です。 |
initialState | Boolean | 出荷状態変更イベントの場合、この値は常にfalseです。 |
これらのイベントには変更された出荷/segmentオブジェクトのプロパティと、変更された出荷/segmentを識別するために必要なプロパティのみが含まれます。これらのプロパティは以下のとおりです。
trackingIdプロパティの出荷ID。extOrderIdプロパティの外部システムにおける任意の出荷ID。
特定のセグメントは以下で識別されます。
segmentIdプロパティのセグメントID。segmentIndexプロパティの出荷内のセグメントのインデックス。出荷内の最初のインデックスは0、2番目は1、以降同様です。- 出発地IDと任意の外部場所ID (
origin.idとorigin.extIdプロパティ) を持つセグメントの出発地。 - 目的地IDと任意の外部場所ID (
destination.idとdestination.extIdプロパティ) を持つセグメントの目的地。
詳細については、「shipment state change event OpenAPI schema」(出荷状態変更イベントのOpenAPIスキーマ) を参照してください。
出荷ステータス変更イベントを有効にする
Shipment status change eventイベントはプロジェクト機能のAPIを使用して、data.shipments.enableStateChangeEventsパラメーターをtrueに設定することで、プロジェクトのすべての出荷に対して有効にできます。リクエストはプロジェクトスコープのユーザートークンを使用して送信する必要があります。
以下は機能を有効にするためのcurlリクエストの例です。
userScopedToken="<project scoped user token>"
curl -X PATCH "https://tracking.hereapi.com/registry/v2/features" \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '"${userScopedToken}" \
-d '{"data":{"shipments":{"enableStateChangeEvents":true}}}'先月の更新