JSON—ArcGIS Velocity | Documentation

JSON (JavaScript Object Notation) est un format d’échange de données léger couramment utilisé. ArcGIS Velocity peut utiliser un JSON généré à partir de données d’observation Internet of Things (IoT) provenant de diverses 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 Hubs, Azure Service Bus, AWS IoT, Cisco Edge Intelligence, Interrogation HTTP, Réception HTTP, Kafka, WebSocket, RabbitMQ, MQTT
Sources de données - Stockage Blob Azure, Amazon S3, Interrogation HTTP

Spécifier la configuration JSON

Lors de la configuration d’un flux ou d’une source de données, un échantillonnage est réalisé pour identifier le type des données utilisées. Si, au cours de l’échantillonnage, le format de données JSON est identifié, les paramètres supplémentaires suivants de la configuration JSON peuvent être définis :

Nœud racine

S’il y a lieu, spécifiez le nœud racine de la structure JSON dans laquelle les messages résident. Ne définissez pas ce paramètre si la structure JSON contient tous les messages dans une matrice au niveau racine. Par exemple, l’échantillon de code JSON suivant montre des données 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 utilisé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
}]

Il en résulte la dérivation de structure suivante :

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

Aplatir

Le paramètre Flatten (Aplatir) détermine si le JSON imbriqué est divisé en champs distincts. Le nom des nouveaux champs est créé par l’ajout d’un trait de soulignement, suivi des objets de niveau inférieur, à l’objet de niveau supérieur. Dans l’exemple ci-après, l’objet position contient les objets latitude et longitude. Après 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. Le nom des nouveaux champs aplatis est créé par l’ajout d’un trait de soulignement, suivi des noms des objets, jusqu’à ce que l’objet le plus profond soit atteint.

Par exemple, l’échantillon de code JSON suivant montre les 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
}]

Lorsque la case du paramètre Flatten (Aplatir) est cochée, l’exemple de code JSON ci-dessus est traité comme suit, montrant que les éléments des objets position et vehicleInformation sont divisés en 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 utilisée comme illustré ci-après. Bien que les noms des champs vehicleInformation_lastService et vehicleInformation_warningCodes soient tronqués dans l’interface utilisateur, ils restent inchangés dans l’application :

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

Exceptions d’aplatissement

Le paramètre Flattening Exemptions (Exceptions d’aplatissement) vous permet de spécifier un ou plusieurs noms d’élément JSON à conserver sous la forme d’un seul élément de chaîne, plutôt qu’à diviser en champs séparés (par exemple, 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
  }
}]

Lorsque la case du paramètre Flatten (Aplatir) est cochée, et qu’une valeur Flattening Exemptions (Exceptions d’aplatissement) de type geometry est définie, l’exemple de code JSON ci-dessus est traité comme illustré ci-après. Dans le champ last_known_position_geometry, l’objet JSON n’a pas été divisé par aplatissement. En effet, l’élément JSON geometry d’origine a été défini dans le paramètre Flattening Exemptions (Exceptions d’aplatissement). Cette fonction est utile pour conserver certains objets JSON. C’est souvent le cas lorsque l’objet de géométrie 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
}]

La structure est utilisée comme illustré ci-après, 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 seul champ.

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

Aplatir les matrices

Le paramètre Flatten arrays (Aplatir les matrices) détermine si les matrices sont aplaties en champs distincts. Le nom des nouveaux champs est créé par l’ajout d’un trait de soulignement, suivi du numéro de l’objet de matrice, à la valeur arrayName. Dans le cas d’une matrice d’objets, un trait de soulignement et le nom associé à la valeur sont également ajoutés au nom de champ. Lors de l’aplatissement de matrices d’objets, le JSON peut être imbriqué avec plusieurs niveaux de profondeur. Le nom des nouveaux champs aplatis est créé par l’ajout d’un trait de soulignement, suivi des noms des objets, jusqu’à ce que l’objet le plus profond soit atteint.

Par exemple, l’échantillon de code JSON suivant montre l’objet de matrice cargoInformation :

{
    "name": "iss",
    "id": 25544,
    "latitude": -13.210305423781,
    "longitude": -118.47517068897,
    "velocity": 27564.442053654,
    "visibility": "daylight",
    "cargoInformation": [{
            "sensorsID": 1,
            "age": 5432
        }, {
            "sensorsID": 2,
            "age": 9876
        }
    ],
    "footprint": 4521.609615023,
    "timestamp": 1654531549,
    "daynum": 2459737.170706,
    "solar_lat": 22.696540649846,
    "solar_lon": 298.23268983658,
    "units": "kilometers"
}

Lorsque la case du paramètre Flatten arrays (Aplatir les matrices) est cochée, l’exemple de code JSON ci-dessus est traité comme suit, montrant que les éléments de l’objet d’information sur la cargaison sont divisés en champs correspondants :

{
    "name": "iss",
    "id": 25544,
    "latitude": -13.210305423781,
    "longitude": -118.47517068897,
    "velocity": 27564.442053654,
    "visibility": "daylight",
    "cargoInformation_0_sensorsID": 1,
    "cargoInformation_0_age": 5432,
    "cargoInformation_1_sensorsID": 2,
    "cargoInformation_1_age": 9876,
    "footprint": 4521.609615023,
    "timestamp": 1654531549,
    "daynum": 2459737.170706,
    "solar_lat": 22.696540649846,
    "solar_lon": 298.23268983658,
    "units": "kilometers"
}

La structure est utilisée comme illustré ci-après. Bien que les noms de champ cargoInformation soient tronqués dans l’interface utilisateur, ils restent inchangés dans l’application :

Exceptions d’aplatissement de matrice

Le paramètre Array flattening exemptions (Exceptions d’aplatissement de matrice) vous permet de spécifier un ou plusieurs noms de matrice JSON à conserver sous la forme d’un seul élément de chaîne, plutôt qu’à diviser en champs séparés. Examinons l’exemple JSON suivant :

{
    "name": "iss",
    "id": 25544,
    "latitude": -13.210305423781,
    "longitude": -118.47517068897,
    "velocity": 27564.442053654,
    "visibility": "daylight",
    "cargoInformation": [{
            "sensorsID": 1,
            "age": 5432
        }, {
            "sensorsID": 2,
            "age": 9876
        }
    ],
    "sensorValues": [1,2,3,4,5],
    "footprint": 4521.609615023,
    "timestamp": 1654531549,
    "daynum": 2459737.170706,
    "solar_lat": 22.696540649846,
    "solar_lon": 298.23268983658,
    "units": "kilometers"
}

Lorsque la case du paramètre Flatten arrays (Aplatir les matrices) est cochée, et qu’une valeur Array flattening exemptions (Exceptions d’aplatissement de matrice) de type sensorValues est définie, l’exemple de code JSON ci-dessus est traité comme illustré ci-après. Dans la matrice sensorValues, l’objet de matrice n’est pas divisé par aplatissement ; il est conservé sous forme de chaîne. Pour indiquer plusieurs matrices à dispenser d’aplatissement, séparez-les par une virgule dans le paramètre Array flattening exemptions (Exceptions d’aplatissement de matrice).

{
    "name": "iss",
    "id": 25544,
    "latitude": -13.210305423781,
    "longitude": -118.47517068897,
    "velocity": 27564.442053654,
    "visibility": "daylight",
    "cargoInformation_0_sensorsID": 1,
    "cargoInformation_0_age": 5432,
    "cargoInformation_1_sensorsID": 2,
    "cargoInformation_1_age": 9876,
    "sensorValues": [1,2,3,4,5],
    "footprint": 4521.609615023,
    "timestamp": 1654531549,
    "daynum": 2459737.170706,
    "solar_lat": 22.696540649846,
    "solar_lon": 298.23268983658,
    "units": "kilometers"
}

La structure est utilisée comme illustré ci-après.

Exception d’aplatissement de matrice JSON

Considérations et limitations

Pour l’utilisation de données au format JSON dans Velocity, tenez compte des informations et limites décrites ci-après.

Matrices contenant des données JSON

Malgré leur souplesse d’utilisation avec les données JSON, les matrices sont problématiques lorsqu’il s’agit de construire des 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 une entité distincte. Les matrices de l’objet JSON sont dérivées sous forme de chaînes. Vous pouvez exécuter d’autres traitements sur les chaînes à l’aide d’outils d’analyse.

Valeurs de données nulles

Au format JSON, les données sont représentées par des paires nom-valeur. En cas de valeur nulle, de nombreuses applications qui créent des données au format JSON omettent 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 de données pour déterminer le format et la structure des données. S’il manque des éléments JSON dans tous les échantillons renvoyés par le processus d’échantillonnage, car ces échantillons contiennent des valeurs nulles, ces champs ne sont pas intégrés dans la structure du flux ou des données sources.

Il en résulte que les messages arrivés ultérieurement, dans lesquels ces éléments JSON ont une valeur de données, ne peuvent pas être convertis en observations ou enregistrements traitables par les flux ou les analyses dans Velocity.

Types de champ dérivés

Les données JSON génériques n’étant pas fortement typées, il peut être nécessaire de corriger les types de champ dérivés des échantillons. Faites preuve de prudence lorsque vous modifiez des types de champ. Il est conseillé de rendre un type de champ plus inclusif, et non l’inverse. Par exemple, un petit échantillon peut ne pas faire apparaître que la valeur d’un champ donné doit être Float64, et non Float32.

De plus, il n’est pas conseillé de passer d’un type de champ à virgule flottante (Float64 ou Float32) à un type de champ entier (Int64 ou Int32). Il n’est pas recommandé non plus de changer les types de champ 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 est ignorée sans arrondissement. Pour convertir ou transformer des valeurs numériques, utilisez l’outil Calculer un champ ou Apparier des champs.

Taille des fichiers JSON

Comme cela est conseillé, conservez chacun des fichiers JSON à une taille inférieure à 100 Mo dans Velocity. Si vous avez un plus grand volume de données, divisez les fichiers en fichiers d’une taille inférieure à 100 Mo chacun.

Vous avez un commentaire à formuler concernant cette rubrique ?