Consultar usando a API Federation
Este guia explica como consultar dados no Manufacturing Data Engine (MDE) usando a API Federation para casos de uso típicos.
A federação fornece acesso a partes dos dados de configuração, dados armazenados no BigQuery ou no Bigtable.
Para usar a API Federation e consultar dados no Bigtable, verifique se você implantou o MDE com o "tamanho" correto. Para mais informações, consulte a seção de tamanhos e escolha um tamanho que implante o job de gravador do Dataflow necessário e uma instância do Bigtable. Normalmente, qualquer coisa maior que Pilot inclui as dependências necessárias.
Introdução
A API Federation é uma API REST típica que retorna estruturas JSON. Para acessar a API, use o proxy do MDE ou exponha usando o Identity-Aware Proxy.
Os dados disponíveis pela API são os seguintes:
| Dados disponíveis | Caminho raiz da API usando túnel |
|---|---|
| Receber registros do BigLake | /data/v1/bigquery |
| Extrair registros do Bigtable | /data/v1/bigtable |
| Receber uma instância de metadados do Gerenciador de metadados | /data/v1/metadata |
| Receber tipos e tags do Gerenciador de configurações | /data/v1/config |
Em alguns casos, o nome do atributo é abreviado para garantir o desempenho adequado ao transferir payloads JSON grandes pela rede. É possível incluir uma seção de cabeçalhos na resposta que explique as abreviações.
Os parâmetros de consulta gerais usados nas diferentes partes da API são:
| Parâmetro de consulta | Descrição |
|---|---|
includeMetrics |
As métricas relacionadas às consultas são incluídas na resposta. |
includeHeader |
Um cabeçalho é incluído na resposta com a explicação da abreviação e as estatísticas de resposta. |
includeMetadata |
Ao retornar registros, isso especifica se os campos de metadados devem ser incluídos na resposta. Isso pode aumentar substancialmente o tamanho da resposta e talvez não seja necessário. |
nextPageToken |
Se houver mais dados disponíveis do que os retornados, um nextPageToken será retornado e poderá ser fornecido na próxima solicitação para receber a próxima página. No Bigtable, o nextPageToken é sempre fornecido porque não há como saber se há mais registros disponíveis ou não. |
includeIds |
Inclua IDs de linha e de mensagem de origem. |
Confira a seguir um exemplo de solicitação com três dos parâmetros de consulta incluídos:
GET http://localhost:8080/data/v1/bigquery/records/primepaintingrobot-01-airhumidity/default-numeric-records/latest?includeMetrics=true&includeHeader=true&includeMetadata=true
Uma resposta de exemplo com os três parâmetros de consulta incluídos seria semelhante ao exemplo a seguir:
{
"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
}
}
A API é compatível com a redução da resolução do lado do servidor. Para usar esse recurso, especifique um intervalo de subamostragem no formato:sample=Duration,Unit,Aggregation
Por exemplo: sample=[10,MINUTE,MEAN]
Parâmetros permitidos:
Duration:Int: um número inteiro que representa o intervalo de subamostragem.Unit:{SECOND, MINUTE, HOUR}: a unidade de tempo do intervalo.Aggregation:{MEAN, SUM,MAX, MIN, COUNT}: a função de agregação a ser aplicada.
A redução da taxa de amostragem está disponível para dados do Bigtable e do Bigtable. Os tipos de agregação disponíveis também dependem do arquétipo.
Extrair registros do BigQuery
Confira a seguir um exemplo de solicitação para receber o registro mais recente de várias tags com combinação de tipos do 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
Uma resposta de exemplo seria semelhante a esta:
{
"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
}
}
Confira a seguir um exemplo de solicitação para recuperar registros de tags específicas, combinação de tipos e intervalos de tempo de início e término do 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
Uma resposta parcial de exemplo seria semelhante a esta:
{
"tags": [
{
"tagName": "station-a-powerusage",
"data": [
{
"t": "1691061419653000",
"np": {
"v": 14.174
}
},
{
"t": "1691061418653000",
"np": {
"v": 17.979
}
},
A solicitação de exemplo a seguir recebe registros de uma combinação de tags e tipo do BigQuery com downsampling (o valor mínimo para cada janela de cinco minutos no intervalo de tempo especificado):
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
Uma resposta de exemplo seria semelhante a esta:
{
"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"
}
A solicitação de amostra a seguir recebe registros de um tipo em cluster com base em dois valores em cluster do BigQuery:
GET http://localhost:8080/data/v1/bigquery/clusteredrecords/clustered-energy-consumption-numeric-records?clusterColumnValues=DK,AAR&startTimestamp=1691062260871&endTimestamp=1691065860871
Uma resposta parcial de exemplo seria semelhante a esta:
{
"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
}
},
[...]
A solicitação de amostra a seguir recebe tags para um tipo:
GET http://localhost:8080/data/v1/bigquery/tags/default-numeric-records?startTimestamp=1690942297865&endTimestamp=1691062297865&includeHeader=true
Uma resposta parcial de exemplo seria semelhante a esta:
{
"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"
},
Extrair registros do Bigtable
Confira a seguir um exemplo de solicitação para receber registros de uma combinação de tags, tipo e um período (horário de início e término) do Bigtable:
GET http://localhost:8080/data/v1/bigtable/records/default-numeric-records?startTimestamp=1687462558476&endTimestamp=1691062558476&tags=clearcoatingrobot-01-airpressure,primepaintingrobot-01-airhumidity
Uma resposta parcial de exemplo seria semelhante a esta:
{
"tags": [
{
"tagName": "clearcoatingrobot-01-airpressure",
"data": [
{
"t": "1691062557069",
"np": {
"v": 757.18
}
},
{
"t": "1691062556068",
"np": {
"v": 763.71
}
},
Confira um exemplo de solicitação para receber o registro mais recente de uma combinação de uma tag e um tipo do Bigtable:
GET http://localhost:8080/data/v1/bigtable/records/clearcoatingrobot-01-airpressure/default-numeric-records/latest?includeHeader=true
Uma resposta de exemplo seria semelhante a esta:
{
"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"
}
]
}
Receber instância de metadados do gerenciador de metadados
Confira a seguir um exemplo de solicitação para receber uma instância de metadados do gerenciador de metadados:
GET http://localhost:8080/data/v1/metadata/instances/41e9a32b-e85f-4a9a-a6a2-a3784855e859?includeHeader=true
Uma resposta parcial de exemplo seria semelhante a esta:
{
"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"
}
]
}
Receber tipos e tags do Gerenciador de configurações
Confira a seguir um exemplo de solicitação para receber tags do Config Manager:
GET http://localhost:8080/data/v1/config/tags?includeHeader=true&pageSize=10
Uma resposta parcial de exemplo seria semelhante a esta:
{
"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"
}
Confira a seguir um exemplo de solicitação para receber tipos do Config Manager:
GET http://localhost:8080/data/v1/config/types?includeHeader=true&pageSize=5
Uma resposta de exemplo seria semelhante a esta:
{
"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="
}