JSON—ArcGIS Velocity

JavaScript 对象表示法 (JSON) 是一种流行的轻量级数据交换格式。 ArcGIS Velocity 可以使用基于各种源的物联网 (IoT) 观测数据生成的 JSON。

以下源和数据源类型支持将 JSON 作为数据格式：

源 - Azure Event Hub、Azure Service Bus、AWS IoT、Cisco Edge Intelligence、HTTP 轮询器、HTTP 接收器、Kafka、WebSocket、RabbitMQ 和 MQTT
数据源 - Azure Blob 存储、Amazon S3 和 HTTP 轮询器

指定 JSON 配置

配置源或数据源时，将进行采样以识别正在使用的数据类型。如果采样将数据识别为 JSON，则可以指定 JSON 配置的其他参数：

根节点

如果适用，请指定消息驻留的 JSON 结构的根节点。如果 JSON 结构在根级别下包含数组中的所有消息，请将此项留空。例如，以下示例 JSON 显示具有多个级别和对象的数据：

{
  "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
  }]
}

如果已指定 sensorData 的根节点，则将仅在 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
}]

生成的方案派生如下所示：

展平

展平参数确定是否将嵌入的 JSON 划分为单独的字段。新字段通过将带有下划线的较低级别对象附加到较高级别对象进行命名。在下面的示例中，position 对象包含 latitude 和 longitude 对象。进行展平后，position 对象将划分为两个字段，即 position_latitude 和 position_longitude。

展平时，JSON 可以嵌套多个深度级别。展平后的新字段名称附加带下划线的对象名称，直到到达最深级别对象。

例如，以下示例 JSON 显示 position 和 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
}]

在选中展平参数后，上述示例 JSON 处理如下，其中 position 和 vehicleInformation 对象中的元素将划分为对应的字段：

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

所用方案如下所示。尽管用户界面截断了 vehicleInformation_lastService 和 vehicleInformation_warningCodes 字段名称，但是应用程序保持其完整无缺。

展平免除

展平免除参数用于指定一个或多个 JSON 元素名称，这些名称应保留为单个字符串元素，而不应划分为单独的字段，例如表示数组的 JSON 对象或包含其他元素的对象。考虑以下 JSON 示例：

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

当选中展平参数并且指定的展平免除值为 geometry，则上面的示例 JSON 将如下图所示。在 last_known_position_geometry 字段中，JSON 对象尚未通过展平进行划分。这是因为已在展平免除参数中指定原始 geometry JSON 元素。这在要保留 JSON 对象时很有用。通常，当几何对象表示要素的空间位置时就是如此。在这种情况下，此属性采用 GeoJSON 几何格式。

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

所用的方案如下所示，同时源或数据源位置信息可以设置为从单个字段派生。

展平数组

展平数组参数用于确定数组是否展平为单独的字段。新字段的命名方式为附加带下划线的 arrayName 值和数组对象编号。如果数组为对象数组，则字段名称还会附加下划线和与值关联的名称。展平对象数组时，JSON 可以嵌套多个深度级别。展平后的新字段名称附加带下划线的对象名称，直到到达最深对象。

例如，以下示例 JSON 显示 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"
}

在选中展平数组后，上述示例 JSON 处理如下，其中获取信息对象中的元素将划分为对应的字段：

{
    "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"
}

所用方案如下所示。尽管用户界面截断了 cargoInformation 字段名称，但是应用程序保持其完整无缺。

数组展平免除

数组展平免除参数用于指定一个或多个 JSON 数组名称，这些名称应保留为单个字符串元素而不是划分为单独的字段。考虑以下 JSON 示例：

{
    "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"
}

当选中展平数组参数并且指定的数组展平免除值为 sensorValues，则上面的示例 JSON 将如下图所示。在 sensorValues 数组中，数组对象未通过展平划分，而是保留为字符串。要指示多个数组从展平中免除，在数组展平免除参数中以逗号分隔这些数组。

{
    "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"
}

所用方案如下所示。

注意事项和限制

在 Velocity 中使用采用 JSON 格式的数据时，注意下述信息和限制。

包含数组的 JSON 数据

可在 JSON 中灵活使用数组，但当基于 JSON 数据构建 ArcGIS 要素时，由于数组的长度不确定，因此会带来挑战。如果整个文档或定义的根节点是一个对象的数组，则单个对象将视为单独的要素。 JSON 对象中的数组均派生为字符串。可以使用分析工具对字符串执行进一步处理。

空数据值

在 JSON 格式中，将使用名称值对表示数据。如果值为空，则以 JSON 格式创建数据的许多应用程序将省略名称对象。

首次配置或编辑源或数据源时，这具有隐含意义。 Velocity 会对数据流或文件进行采样，以确定数据格式和方案。如果采样过程中返回的所有样本都缺少 JSON 元素（因为这些样本具有空值），则将从源或源数据方案中省略这些字段。

这将导致稍后传入且具有这些 JSON 元素数据值的消息将无法解析为观测值或记录，这些观测值或记录可在 Velocity 中通过源或分析进行处理。

派生的字段类型

通用 JSON 数据并非强输入；可能需要更正样本派生的字段类型。应谨慎更改字段类型。建议使字段类型更具包容性，而非降低包容性。例如，一个小样本集可能无法揭示特定字段值应为 Float64，而非 Float32。

此外，建议不要将字段从浮点型（Float64 或 Float32）更改为整型（Int64 或 Int32）。对于数值的动态转换，同样建议不要更改字段类型。对于 JSON 数据，从浮点型降级为整型将导致该值的小数部分被舍弃而不舍入。要转换或变换数值，使用计算字段或映射字段。

JSON 文件大小

建议在 Velocity 中保持 JSON 文件的每个文件大小小于 100 MB。如果存在大量数据，将文件划分为每个文件的大小小于 100 MB。

有关此主题的反馈?