JSON

JSON (JavaScript Object Notation) est un format d’échange de données léger couramment utilisé. ArcGIS Velocity peut ingérer des données d’observation IoT exprimées au format JSON à partir de nombreuses sources.

Le format de données JSON est pris en charge pour les types de flux et de source de données suivants :

  • Flux : Azure Event Hub, Azure Service Bus, AWS IoT, Disco Kinetic EFM, Site Web (Interrogation), Extrémité (Réception), Kafka, WebSocket, RabbitMQ, MQTT.
  • Sources de données : Stockage Azure Blob, Amazon S3, Site Web (Interrogation).

Spécifier la configuration JSON

Lors de la configuration d’un flux ou d’une source de données, un échantillonnage est effectué pour déterminer le type des données ingérées. Si, au cours de l’échantillonnage, le format de données JSON est identifié, d’autres propriétés de la configuration JSON peuvent être spécifiées.

Nœud racine

S’il y a lieu, spécifiez le nœud racine de votre structure JSON où les messages se trouvent. Ne renseignez pas ce champ si votre structure JSON contient tous les messages dans une matrice au niveau racine.

Prenons l’exemple des données JSON suivantes, comportant plusieurs niveaux et objets :

{
  "requestInfo": {
    "requestTime": 1573591345,
    "requestingUser": "Greg Smith"
  },
  "responseInfo": {
    "dataLastUpdated": 1573239432
  },
  "sensorData": [{
    "vehicleID": "17256",
    "driverName": "Peter Jones",
    "latitude": 35.21027,
    "longitude": -81.291326,
    "speed": 64.3,
    "heading": 161.34,
    "status": "Out for delivery",
    "lastBreak": 1573591581
  }, {
    "vehicleID": "11954",
    "driverName": "Frank Jenkins",
    "latitude": 35.23425,
    "longitude": -81.092657,
    "speed": 25.8,
    "heading": 54.64,
    "status": "Returning to warehouse",
    "lastBreak": 1573581253
  }]
}

Si un nœud racine sensorData a été spécifié, seules les données suivantes sont ingérées dans Velocity :

[{
  "vehicleID": "17256",  "driverName": "Peter Jones",  "latitude": 35.21027,  "longitude": -81.291326,  "speed": 64.3,  "heading": 161.34,  "status": "Out for delivery",  "lastBreak": 1573591581
}, {
  "vehicleID": "11954",  "driverName": "Frank Jenkins",  "latitude": 35.23425,  "longitude": -81.092657,  "speed": 25.8,  "heading": 54.64,  "status": "Returning to warehouse",  "lastBreak": 1573581253
}]

Une structure semblable à la suivante est alors dérivée :

Page Confirmer la structure résultante, avec nœud racine

Aplatir

Le paramètre Flatten (Aplatissement) détermine si les objets JSON imbriqués doivent être répartis ou non sur plusieurs champs. Le nom de ces nouveaux champs est créé en ajoutant un trait de soulignement, suivi des objets de niveau inférieur, à l’objet de niveau supérieur. L’exemple ci-dessous montre un objet position qui contient des objets latitude et longitude. Lors de l’aplatissement, l’objet position est divisé en deux champs, position_latitude et position_longitude.

Lors de l’aplatissement, les objets JSON peuvent être imbriqués avec plusieurs niveaux de profondeur. Les noms des nouveaux champs sont créés simplement en ajoutant un trait de soulignement, suivi des noms des objets, jusqu’à ce que l’objet le plus profond soit atteint.

Prenons l’exemple des données JSON suivantes, en nous intéressant particulièrement aux objets position et vehicleInformation :

[{
  "vehicleID": "17256",  "driverName": "Peter Jones",  "position": {
    "latitude": 35.21027,    "longitude": -81.291326  },  "vehicleInformation": {
    "lastService": 1571431836,    "warningCodes": 2  },  "speed": 64.3,  "heading": 161.34,  "status": "Out for delivery",  "lastBreak": 1573591581
}, {
  "vehicleID": "11954",  "driverName": "Frank Jenkins",  "position": {
    "latitude": 35.23425,    "longitude": -81.092657  },  "vehicleInformation": {
    "lastService": 1560531836,    "warningCodes": 2  },  "speed": 25.8,  "heading": 54.64,  "status": "Returning to warehouse",  "lastBreak": 1573581253
}]

Si la case Flatten (Aplatir) est cochée, l’exemple JSON ci-dessus est traité comme suit, avec les éléments des objets position et vehicleInformation répartis dans les champs correspondants :

[{
  "vehicleID": "17256",  "driverName": "Peter Jones",  "position_latitude": 35.21027,  "position_longitude": -81.291326,  "vehicleInformation_lastService": 1571431836,  "vehicleInformation_warningCodes": 2,  "speed": 64.3,  "heading": 161.34,  "status": "Out for delivery",  "lastBreak": 1573591581
}, {
  "vehicleID": "11954",  "driverName": "Frank Jenkins",  "position_latitude": 35.23425,  "position_longitude": -81.092657,  "vehicleInformation_lastService": 1560531836,  "vehicleInformation_warningCodes": 2,  "speed": 25.8,  "heading": 54.64,  "status": "Returning to warehouse",  "lastBreak": 1573581253
}]

La structure est alors ingérée comme suit. Notez que, s’ils sont tronqués dans l’interface utilisateur, les noms des champs vehicleInformation_lastService et vehicleInformation_warningCodes restent intacts dans l’application :

Page Confirmer la structure produite à partir d’un fichier JSON aplati.

Exceptions d’aplatissement

Les exceptions d’aplatissement vous permettent de spécifier un ou plusieurs noms d’élément JSON à conserver en tant qu’élément unique, sans les répartir dans des champs séparés. Il peut par exemple s’agir d’un objet JSON représentant une matrice ou un objet contenant d’autres éléments.

Examinons l’exemple JSON suivant :

[{
  "ship_ID": "17256",  "call_sign": "3FCB8",  "ship_type": "Cargo",  "last_known_position": {
    "timestamp": "2019-06-24T18:30:56+00:00",    "geometry": {
      "type": "Point",      "coordinates": [        79.19315,        7.18374      ]    },    "heading": 109  }
}, {
  "ship_ID": "29435",  "call_sign": "9GEF3",  "ship_type": "Passenger",  "last_known_position": {
    "timestamp": "2019-06-24T18:30:47+00:00",    "geometry": {
      "type": "Point",      "coordinates": [        73.24954,        10.43512      ]    },    "heading": 120  }
}]

Si la case Flatten (Aplatir) est cochée et qu’une l’exception d’aplatissement a été spécifiée pour geometry, l’exemple JSON ci-dessus est traité comme suit. Notez que, dans le champ last_known_position_geometry, l’objet JSON n’a pas été décomposé par aplatissement. En effet, l’élément JSON initial, geometry, a été spécifié pour le paramètre Flattening Exemptions (Exceptions d’aplatissement). Cette fonction est utile dans les situations où vous voulez conserver certains objets JSON. Cela est souvent souhaitable pour l’objet de géométrie qui représente l’emplacement spatial des entités. Dans ce cas, le format de géométrie GeoJSON est utilisé pour cet attribut.

[{
  "ship_ID": "17256",  "call_sign": "3FCB8",  "ship_type": "Cargo",  "last_known_position_timestamp": "2019-06-24T18:30:56+00:00",  "last_known_position_geometry": {
    "type": "Point",    "coordinates": [      79.19315,      7.18374    ]  },  "last_known_position_heading": 109
}, {
  "ship_ID": "29435",  "call_sign": "9GEF3",  "ship_type": "Passenger",  "last_known_position_timestamp": "2019-06-24T18:30:47+00:00",  "last_known_position_geometry": {
    "type": "Point",    "coordinates": [      73.24954,      10.43512    ]  },  "last_known_position_heading": 120
}]

Cette structure est ingérée comme illustré ci-dessous et les informations d’emplacement du flux ou de la source de données peuvent être configurées comme étant dérivées d’un champ unique.

Page Confirmer la structure produite à partir d’un fichier JSON aplati (exception faite du champ de géométrie).

Considérations et limitations

Les limites et informations importantes ci-dessous doivent être prises en compte lors de l’utilisation de données au format JSON dans Velocity.

Vos données JSON ont-elles des matrices ?

Les matrices permettent une grande flexibilité des données JSON. Elles sont , néanmoins à l’origine d’un défi lors de la construction d’entités ArcGIS à partir de données JSON, en raison de leur longueur indéterminée. Si l’ensemble du document ou un nœud racine défini est une matrice d’objets, chaque objet est traité comme entité distincte. Les matrices dans l’objet JSON seront dérivées sous forme de chaînes. Il est possible de traiter davantage les chaînes à l’aide d’outils d’analyse.

Les échantillons JSON sont-ils représentatifs de l’ensemble de la structure ?

Dans le format de données JSON, les données sont représentées par des paires nom-valeur. En cas de valeur nulle, la plupart des applications qui créent des données au format JSON se contentent d’omettre entièrement le nom de l’objet.

Cela a un impact lors de la configuration initiale ou de la mise à jour d’un flux ou d’une source de données. Velocity échantillonne le flux de données ou les fichiers pour déterminer au mieux le format et la structure des données. Si, dans tous les échantillons renvoyés par le processus d’échantillonnage, il manque des éléments JSON car ces échantillons contiennent des valeurs nulles, ces champs ne sont pas intégrés dans la structure du flux ou de la source de données.

Par conséquent, les messages arrivés ultérieurement, dans lesquels ces éléments JSON ont une valeur, ne peuvent pas être convertis en observations ou enregistrements pouvant être traités par les flux ou les analyses dans Velocity.

Modifiez-vous les types de champ dérivés des données JSON ?

Les données JSON génériques n’étant pas fortement typées, il peut être nécessaire dans certains cas de corriger les types de champ dérivés des échantillons. Soyez néanmoins prudent lorsque vous modifiez les types de champ : il est conseillé de les rendre plus inclusifs, et non l’inverse. Par exemple, un petit échantillon peut ne pas révéler qu’un champ doit être de type Float64, et non Float32.

En outre, passer d’un type à virgule flottante (Float32 ou Float64) à un type entier (Int32 ou Int64) n’est pas conseillé. La modification des types de champ n’est pas prévue pour la conversion à la volée des valeurs numériques. Dans le cas des données JSON, si vous modifiez un champ à virgule flottante en champ entier, la partie décimale de la valeur sera ignorée sans arrondissement. Pour convertir ou transformer des valeurs numériques, utilisez Calculer un champ ou Apparier les champs dans une analyse.

Taille des fichiers JSON

La taille de chaque fichier JSON doit être inférieure à 100 Mo. Si vous avez davantage de données à ingérer, il est recommandé de les fractionner pour créer des fichiers d’une taille inférieure à 100 Mo chacun.