Interroger à l'aide de l'API Federation
Ce guide explique comment interroger des données dans Manufacturing Data Engine (MDE) à l'aide de l'API Federation pour les cas d'utilisation typiques.
La fédération permet d'accéder à des parties des données de configuration, ainsi qu'aux données stockées dans BigQuery ou Bigtable.
Pour utiliser l'API Federation afin d'interroger des données dans Bigtable, assurez-vous d'avoir déployé MDE avec la "size" (taille) appropriée. Pour en savoir plus, consultez la section Tailles et choisissez une taille qui déploie la tâche d'écriture Dataflow requise ainsi qu'une instance Bigtable. En règle générale, tout ce qui est supérieur à Pilot inclut les dépendances requises.
Introduction
L'API Federation est une API REST typique qui renvoie des structures JSON. Pour accéder à l'API, utilisez le proxy MDE ou exposez-la à l'aide d'Identity-Aware Proxy.
Les données disponibles via l'API sont les suivantes :
| Données disponibles | Chemin racine de l'API à l'aide du tunnel |
|---|---|
| Obtenir des enregistrements à partir de BigLake | /data/v1/bigquery |
| Obtenir des enregistrements depuis Bigtable | /data/v1/bigtable |
| Obtenir une instance de métadonnées à partir du Gestionnaire de métadonnées | /data/v1/metadata |
| Obtenir des types et des tags à partir de Config Manager | /data/v1/config |
Dans certains cas, les noms d'attributs sont abrégés pour garantir des performances optimales lors du transfert de grandes charges utiles JSON sur le réseau. Il est possible d'inclure une section d'en-têtes dans la réponse qui explique les abréviations.
Voici les paramètres de requête généraux utilisés dans les différentes parties de l'API :
| Paramètre de requête | Description |
|---|---|
includeMetrics |
Les métriques liées aux requêtes sont incluses dans la réponse. |
includeHeader |
Un en-tête est inclus dans la réponse avec une explication de l'abréviation et des statistiques de réponse. |
includeMetadata |
Lors du renvoi d'enregistrements, cette option indique s'il faut inclure ou non les champs de métadonnées dans la réponse. Cela peut augmenter considérablement la taille de la réponse et n'est peut-être pas nécessaire. |
nextPageToken |
Si plus de données sont disponibles que celles renvoyées, un nextPageToken est renvoyé et peut être fourni dans la requête suivante pour obtenir la page suivante. Pour Bigtable, nextPageToken est toujours fourni, car il n'existe aucun moyen de savoir s'il existe d'autres enregistrements disponibles ou non. |
includeIds |
Incluez les ID de ligne et les ID de message source. |
Voici un exemple de requête avec trois des paramètres de requête inclus :
GET http://localhost:8080/data/v1/bigquery/records/primepaintingrobot-01-airhumidity/default-numeric-records/latest?includeMetrics=true&includeHeader=true&includeMetadata=true
Voici un exemple de réponse avec les trois paramètres de requête inclus :
{
"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
}
}
L'API est compatible avec le sous-échantillonnage côté serveur. Pour utiliser cette fonctionnalité, spécifiez un intervalle de sous-échantillonnage au format suivant :sample=Duration,Unit,Aggregation
Par exemple : sample=[10,MINUTE,MEAN]
Paramètres autorisés :
Duration:Int: entier représentant l'intervalle de sous-échantillonnage.Unit:{SECOND, MINUTE, HOUR}: unité de temps de l'intervalle.Aggregation:{MEAN, SUM,MAX, MIN, COUNT}: fonction d'agrégation à appliquer.
Le sous-échantillonnage est disponible pour les données provenant de Bigtable et de Bigtable. Les types d'agrégation disponibles dépendent également de l'archétype.
Obtenir des enregistrements à partir de BigQuery
Voici un exemple de requête permettant d'obtenir le dernier enregistrement pour un certain nombre de tags avec une combinaison de types à partir de 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
Voici un exemple de réponse :
{
"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
}
}
Voici un exemple de requête permettant de récupérer des enregistrements pour des combinaisons de balises et de types spécifiques, ainsi que des plages de dates de début et de fin dans 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
Voici un exemple de réponse partielle :
{
"tags": [
{
"tagName": "station-a-powerusage",
"data": [
{
"t": "1691061419653000",
"np": {
"v": 14.174
}
},
{
"t": "1691061418653000",
"np": {
"v": 17.979
}
},
L'exemple de requête suivant récupère les enregistrements d'une combinaison de tags et de types à partir de BigQuery avec sous-échantillonnage (valeur minimale pour chaque période de cinq minutes dans la plage de temps spécifiée) :
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
Voici un exemple de réponse :
{
"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"
}
L'exemple de requête suivant permet d'obtenir des enregistrements pour un type groupé en fonction de deux valeurs groupées de BigQuery :
GET http://localhost:8080/data/v1/bigquery/clusteredrecords/clustered-energy-consumption-numeric-records?clusterColumnValues=DK,AAR&startTimestamp=1691062260871&endTimestamp=1691065860871
Voici un exemple de réponse partielle :
{
"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
}
},
[...]
L'exemple de requête suivant permet d'obtenir les tags d'un type :
GET http://localhost:8080/data/v1/bigquery/tags/default-numeric-records?startTimestamp=1690942297865&endTimestamp=1691062297865&includeHeader=true
Voici un exemple de réponse partielle :
{
"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"
},
Obtenir des enregistrements depuis Bigtable
Voici un exemple de requête permettant d'obtenir des enregistrements pour une combinaison de tags, de type et de plage de temps (heure de début et de fin) à partir de Bigtable :
GET http://localhost:8080/data/v1/bigtable/records/default-numeric-records?startTimestamp=1687462558476&endTimestamp=1691062558476&tags=clearcoatingrobot-01-airpressure,primepaintingrobot-01-airhumidity
Voici un exemple de réponse partielle :
{
"tags": [
{
"tagName": "clearcoatingrobot-01-airpressure",
"data": [
{
"t": "1691062557069",
"np": {
"v": 757.18
}
},
{
"t": "1691062556068",
"np": {
"v": 763.71
}
},
Voici un exemple de requête permettant d'obtenir le dernier enregistrement pour une combinaison de tag et de type à partir de Bigtable :
GET http://localhost:8080/data/v1/bigtable/records/clearcoatingrobot-01-airpressure/default-numeric-records/latest?includeHeader=true
Voici un exemple de réponse :
{
"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"
}
]
}
Obtenir une instance de métadonnées à partir du gestionnaire de métadonnées
Voici un exemple de requête permettant d'obtenir une instance de métadonnées à partir du gestionnaire de métadonnées :
GET http://localhost:8080/data/v1/metadata/instances/41e9a32b-e85f-4a9a-a6a2-a3784855e859?includeHeader=true
Voici un exemple de réponse partielle :
{
"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"
}
]
}
Obtenir des types et des tags à partir de Config Manager
Voici un exemple de requête permettant d'obtenir des tags à partir de Config Manager :
GET http://localhost:8080/data/v1/config/tags?includeHeader=true&pageSize=10
Voici un exemple de réponse partielle :
{
"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"
}
Voici un exemple de requête permettant d'obtenir des types à partir de Config Manager :
GET http://localhost:8080/data/v1/config/types?includeHeader=true&pageSize=5
Voici un exemple de réponse :
{
"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="
}