使用 Federation API 进行查询
本指南介绍了如何针对典型使用情形，使用 Federation API 在 Manufacturing Data Engine (MDE) 中查询数据。
联合提供对部分配置数据（存储在 BigQuery 或 Bigtable 中的数据）的访问权限。
如需使用 Federation API 查询 Bigtable 中的数据，请确保您已部署具有正确“大小”的 MDE。如需了解详情，请参阅“规模”部分，然后选择一个既能部署所需的 Dataflow 写入器作业，又能部署 Bigtable 实例的规模。通常，大于 Pilot 的任何内容都包含所需的依赖项。
简介
Federation API 是一种典型的 REST API，可返回 JSON 结构。如需访问该 API，请使用 MDE 代理或通过 Identity-Aware Proxy 进行公开。
可通过 API 获取的数据如下：
| 可用数据 | 使用隧道的 API 根路径 |
|---|---|
| 从 BigLake 获取记录 | /data/v1/bigquery |
| 从 Bigtable 获取记录 | /data/v1/bigtable |
| 从元数据管理器获取元数据实例 | /data/v1/metadata |
| 从配置管理器获取类型和标记 | /data/v1/config |
在某些情况下，属性名称会缩写，以确保在通过网络传输大型 JSON 载荷时获得适当的性能。可以在响应中添加一个标题部分，用于说明缩写。
API 各部分通用的查询参数包括：
| 查询参数 | 说明 |
|---|---|
includeMetrics |
响应中包含与查询相关的指标。 |
includeHeader |
响应中包含一个标头，其中包含缩写说明和响应统计信息。 |
includeMetadata |
返回记录时，此参数用于指定是否在响应中包含元数据字段。这可能会大幅增加响应的大小，但可能并不需要。 |
nextPageToken |
如果可用的数据多于返回的数据，则会返回一个 nextPageToken，可在下一个请求中提供该令牌以获取下一页。对于 Bigtable，系统始终会提供 nextPageToken，因为无法知道是否还有更多记录。 |
includeIds |
包含行 ID 和源消息 ID。 |
以下是一个包含三个查询参数的示例请求：
GET http://localhost:8080/data/v1/bigquery/records/primepaintingrobot-01-airhumidity/default-numeric-records/latest?includeMetrics=true&includeHeader=true&includeMetadata=true
包含这三个查询参数的示例响应如下所示：
{
"header": {
"startTime": "1691060884507",
"endTime": "1691060884507",
"tagCount": 1,
"dataRecordCount": 1,
"dataFields": {
"d": "duration",
"dp": "discretePayload",
"cp": "continuousPayload",
"its": "ingestTimestamp",
"cmr": "cloudMetadataRef",
"sdi": "sourceMessageId",
"np": "numericPayload",
"id": "id",
"v": "value",
"em": "embeddedMetadata",
"et": "eventTimestampEnd",
"mcm": "materializedCloudMetadata",
"t": "eventTimestamp",
"st": "eventTimestampStart"
}
},
"tags": [
{
"tagName": "primepaintingrobot-01-airhumidity",
"data": [
{
"t": "1691060884507000",
"np": {
"v": 80.7
},
"em": "{\"datatype\":\"float\",\"description\":\"This is a fake prime painting robot on NodeRed\",\"deviceID\":\"75c18751-7a94-453e-86f5-67be2b0c8fd4\",\"deviceName\":\"primepaintingrobot-01\",\"headers\":{},\"messageClassName\":\"default-numeric-value\",\"metadata\":{\"brand\":\"Philips\",\"measurementUnit\":\"percentage\",\"sensorType\":\"humidity\",\"shift\":\"Shift 4\"},\"registerId\":\"a2635b62-0e89-40ff-b172-13eea37a92c2\",\"success\":true,\"unit\":\"percentage\"}",
"mcm": "{}",
"cmr": "{}"
}
],
"typeName": "default-numeric-records"
}
],
"metrics": {
"totalTimeMS": 2766
}
}
该 API 支持服务器端下采样。如需使用此功能，请指定下采样间隔，格式如下：sample=Duration,Unit,Aggregation
例如：sample=[10,MINUTE,MEAN]
允许的参数：
Duration：Int- 表示下采样间隔的整数。Unit：{SECOND, MINUTE, HOUR}- 时间间隔的时间单位。Aggregation：{MEAN, SUM,MAX, MIN, COUNT}- 要应用的聚合函数。
对于来自 Bigtable 和 Bigtable 的数据，都可以进行下采样。可用的聚合类型也取决于原型。
从 BigQuery 获取记录
以下是一个示例请求，用于从 BigQuery 获取具有类型组合的多个标记的最新记录：
GET http://localhost:8080/data/v1/bigquery/records/default-numeric-records?tags=station-a-powerusage,station-b-powerusage&startTimestamp=1691057738790&endTimestamp=1691061338790&pageSize=100
示例回答如下所示：
{
"header": {
"startTime": "1691061786759",
"endTime": "1691061786759",
"tagCount": 1,
"dataRecordCount": 1,
"dataFields": {
"d": "duration",
"dp": "discretePayload",
"cp": "continuousPayload",
"its": "ingestTimestamp",
"cmr": "cloudMetadataRef",
"sdi": "sourceMessageId",
"np": "numericPayload",
"id": "id",
"v": "value",
"em": "embeddedMetadata",
"et": "eventTimestampEnd",
"mcm": "materializedCloudMetadata",
"t": "eventTimestamp",
"st": "eventTimestampStart"
}
},
"tags": [
{
"tagName": "primepaintingrobot-01-airhumidity",
"data": [
{
"t": "1691061786759000",
"np": {
"v": 81.79
},
"em": "{\"datatype\":\"float\",\"description\":\"This is a fake prime painting robot on NodeRed\",\"deviceID\":\"75c18751-7a94-453e-86f5-67be2b0c8fd4\",\"deviceName\":\"primepaintingrobot-01\",\"headers\":{},\"messageClassName\":\"default-numeric-value\",\"metadata\":{\"brand\":\"Philips\",\"measurementUnit\":\"percentage\",\"sensorType\":\"humidity\",\"shift\":\"Shift 4\"},\"registerId\":\"a2635b62-0e89-40ff-b172-13eea37a92c2\",\"success\":true,\"unit\":\"percentage\"}",
"mcm": "{}",
"cmr": "{}"
}
],
"typeName": "default-numeric-records"
}
],
"metrics": {
"totalTimeMS": 2371
}
}
以下是一个示例请求，用于从 BigQuery 中检索特定标记、类型组合以及开始和结束时间范围的记录：
GET http://localhost:8080/data/v1/bigquery/records/default-numeric-records?tags=station-a-powerusage,station-b-powerusage&startTimestamp=1691057738790&endTimestamp=1691061338790&pageSize=100
部分示例响应如下所示：
{
"tags": [
{
"tagName": "station-a-powerusage",
"data": [
{
"t": "1691061419653000",
"np": {
"v": 14.174
}
},
{
"t": "1691061418653000",
"np": {
"v": 17.979
}
},
以下示例请求从 BigQuery 中获取指定时间范围内具有下采样（指定时间范围内每 5 分钟窗口的最小值）的标记和类型组合的记录：
GET http://localhost:8080/data/v1/bigquery/records/default-numeric-records?tags=station-a-powerusage,station-b-powerusage&startTimestamp=1691058375905&endTimestamp=1691061975905&pageSize=1000&sample=5,MINUTE,MIN
示例回答如下所示：
{
"tags": [
{
"tagName": "station-a-powerusage",
"data": [
{
"t": "1691061775669000",
"agg": {
"v": 12.019
}
},
{
"t": "1691061475669000",
"agg": {
"v": 12.022
}
}
]
},
{
"tagName": "station-b-powerusage",
"data": [
{
"t": "1691061775702000",
"agg": {
"v": 34.092
}
},
{
"t": "1691061475702000",
"agg": {
"v": 34.201
}
}
]
}
],
"nextPageToken": "LTU3NjUwMTA5OS4w"
}
以下示例请求基于 BigQuery 中的两个聚簇值获取聚簇类型的记录：
GET http://localhost:8080/data/v1/bigquery/clusteredrecords/clustered-energy-consumption-numeric-records?clusterColumnValues=DK,AAR&startTimestamp=1691062260871&endTimestamp=1691065860871
部分示例响应如下所示：
{
"tags": [
{
"tagName": "energymonitor2-line-total-energy",
"data": [
{
"t": "1691065853667000",
"np": {
"v": 15.148
}
},
[...]
{
"tagName": "energymonitor6-line-total-energy",
"data": [
{
"t": "1691065853710000",
"np": {
"v": 15.015
}
},
{
"t": "1691065852710000",
"np": {
"v": 18.468
}
},
[...]
以下示例请求用于获取某种类型的标记：
GET http://localhost:8080/data/v1/bigquery/tags/default-numeric-records?startTimestamp=1690942297865&endTimestamp=1691062297865&includeHeader=true
部分示例响应如下所示：
{
"header": {
"tagCount": 56,
"dataRecordCount": 56,
"dataFields": {
"typeName": "typeName",
"tagName": "tagName",
"version": "typeVersion"
}
},
"tags": [
{
"tagName": "sb01_d_voltage",
"typeVersion": "1",
"typeName": "default-numeric-records"
},
{
"tagName": "JGC_001",
"typeVersion": "1",
"typeName": "default-numeric-records"
},
从 Bigtable 获取记录
以下是一个示例请求，用于从 Bigtable 获取包含特定标记、类型和时间范围（开始时间和结束时间）的记录：
GET http://localhost:8080/data/v1/bigtable/records/default-numeric-records?startTimestamp=1687462558476&endTimestamp=1691062558476&tags=clearcoatingrobot-01-airpressure,primepaintingrobot-01-airhumidity
部分示例响应如下所示：
{
"tags": [
{
"tagName": "clearcoatingrobot-01-airpressure",
"data": [
{
"t": "1691062557069",
"np": {
"v": 757.18
}
},
{
"t": "1691062556068",
"np": {
"v": 763.71
}
},
以下是一个示例请求，用于从 Bigtable 获取指定标记和类型组合的最新记录：
GET http://localhost:8080/data/v1/bigtable/records/clearcoatingrobot-01-airpressure/default-numeric-records/latest?includeHeader=true
示例回答如下所示：
{
"header": {
"startTime": "1691062700094",
"endTime": "1691062700094",
"tagCount": 1,
"dataRecordCount": 1,
"dataFields": {
"d": "duration",
"dp": "discretePayload",
"cp": "continuousPayload",
"its": "ingestTimestamp",
"cmr": "cloudMetadataRef",
"sdi": "sourceMessageId",
"np": "numericPayload",
"id": "id",
"v": "value",
"em": "embeddedMetadata",
"et": "eventTimestampEnd",
"mcm": "materializedCloudMetadata",
"t": "eventTimestamp",
"st": "eventTimestampStart"
}
},
"tags": [
{
"tagName": "clearcoatingrobot-01-airpressure",
"data": [
{
"t": "1691062700094",
"np": {
"v": 764.91
}
}
],
"typeName": "default-numeric-records"
}
]
}
从元数据管理器获取元数据实例
以下是从元数据管理器获取元数据实例的请求示例：
GET http://localhost:8080/data/v1/metadata/instances/41e9a32b-e85f-4a9a-a6a2-a3784855e859?includeHeader=true
部分示例响应如下所示：
{
"header": {
"dataFields": {
"i": "instance",
"bv": "bucketVersion",
"bnam": "bucketName",
"bnum": "bucketNumber",
"nk": "naturalKey",
"ct": "createdTimestamp",
"iid": "instanceId"
}
},
"metadataInstances": [
{
"iid": "41e9a32b-e85f-4a9a-a6a2-a3784855e859",
"bnum": 357,
"bnam": "source",
"bv": 1,
"nk": "mce",
"i": "{\"source\":\"Manufacturing Connect edge\"}",
"ct": "1689781556451"
}
]
}
从配置管理器获取类型和标记
以下是用于从配置管理器获取标记的请求示例：
GET http://localhost:8080/data/v1/config/tags?includeHeader=true&pageSize=10
部分示例响应如下所示：
{
"header": {
"tagCount": 10,
"dataFields": {
"types": "types",
"createdTimestamp": "createdTimestamp",
"tagName": "tagName",
"id": "id"
}
},
"tags": [
{
"id": "613db120-fed4-4584-a3b1-9468d7228edb",
"tagName": "MCe-tag-single-string",
"types": ["default-discrete-records"],
"createdTimestamp": "1689781665469"
},
{
"id": "3b42c8c3-3261-4a30-8af8-d2bde1ca72de",
"tagName": "MCe-tag-array-event-3",
"types": ["default-discrete-records"],
"createdTimestamp": "1689781665458"
},
{
"id": "73e198c8-0ffc-4064-bf42-6c60e413c845",
"tagName": "MCe-tag-array-event-2",
"types": ["default-discrete-records"],
"createdTimestamp": "1689781665541"
},
{
"id": "01822a93-f917-4c9c-a1a9-49ba7ee98bff",
"tagName": "MCe-tag-array-event-0",
"types": ["default-discrete-records"],
"createdTimestamp": "1689781665470"
},
{
"id": "7bccbbd2-9e65-4bb5-b0c7-48ab9531712d",
"tagName": "MCe-tag-array-numeric",
"types": ["default-complex-numeric-records"],
"createdTimestamp": "1689781667366"
},
{
"id": "85804705-64a6-494b-a105-c5b8b52ae147",
"tagName": "stampingmachine-09-vibration",
"types": ["default-complex-numeric-records"],
"createdTimestamp": "1689781667445"
},
{
"id": "c33732fb-28b3-43d6-a9ed-8d0c228f1eeb",
"tagName": "primepaintingrobot-01-viscosity",
"types": ["default-numeric-records"],
"createdTimestamp": "1689781669547"
},
{
"id": "50bbb41e-c378-4740-ba9e-0c6f84b44ca7",
"tagName": "MCe-tag-array-event-1",
"types": ["default-discrete-records"],
"createdTimestamp": "1689781665555"
},
{
"id": "39666ff1-738a-4c12-b1d9-370c41ca777f",
"tagName": "MCe-tag-single-event",
"types": ["default-discrete-records"],
"createdTimestamp": "1689781665543"
},
{
"id": "45ea101b-d077-4a91-96d7-aca35b5f20c1",
"tagName": "stampingmachine-09-vibration-1",
"types": ["default-numeric-records"],
"createdTimestamp": "1689781669291"
}
],
"nextPageToken": "LTE4MDA5NTU0MzAuQUFBQUFhRnhTRlYwREFuRnVQcjBBMGx5K1JDVURPdFBtbmN0RW5lUHRGV2o3OE5M"
}
以下是用于从配置管理器获取类型的请求示例：
GET http://localhost:8080/data/v1/config/types?includeHeader=true&pageSize=5
示例回答如下所示：
{
"header": {
"typeCount": 5,
"dataFields": {
"active": "active",
"typeName": "typeName",
"archetypeName": "archetypeName",
"createdTimestamp": "createdTimestamp",
"id": "id"
}
},
"types": [
{
"typeName": "default-complex-numeric-records",
"archetypeName": "DISCRETE_DATA_SERIES",
"createdTimestamp": "1689781557147",
"id": "4ec777fc-f078-4465-81fd-d70e7a1df329",
"active": true
},
{
"typeName": "default-continuous-records",
"archetypeName": "CONTINUOUS_DATA_SERIES",
"createdTimestamp": "1689781557805",
"id": "d684637a-b751-49d5-82c2-8941aa4c1ef4",
"active": true
},
{
"typeName": "default-clustered-numeric-records",
"archetypeName": "CLUSTERED_NUMERIC_DATA_SERIES",
"createdTimestamp": "1689781557979",
"id": "e2dbbab1-ad15-4445-b0db-59bb17b96a54",
"active": true
},
{
"typeName": "default-numeric-records",
"archetypeName": "NUMERIC_DATA_SERIES",
"createdTimestamp": "1689781556887",
"id": "0f6fc49f-a463-4948-ab65-e4c4f66192b9",
"active": true
},
{
"typeName": "default-discrete-records",
"archetypeName": "DISCRETE_DATA_SERIES",
"createdTimestamp": "1689781557444",
"id": "94327246-5ec3-4777-9154-a968dd546c90",
"active": true
}
],
"nextPageToken": "LTYxMjI4MTg4OC5BQUFBQVVzR25vRVpkMGplSU9FZUc1N2VJY2h0clNqQXhUOUN4QmYxSXZ6UGpjY3U="
}