Abfragen mit der Federation API

In diesem Leitfaden wird beschrieben, wie Sie Daten in der Manufacturing Data Engine (MDE) für typische Anwendungsfälle mit der Federation API abfragen.

Die Föderation ermöglicht den Zugriff auf Teile der Konfigurationsdaten sowie auf Daten, die in BigQuery oder Bigtable gespeichert sind.

Wenn Sie die Federation API verwenden möchten, um Daten in Bigtable abzufragen, müssen Sie MDE mit der richtigen „Größe“ bereitgestellt haben. Weitere Informationen finden Sie im Abschnitt zu den Größen. Wählen Sie eine Größe aus, mit der sowohl der erforderliche Dataflow-Writer-Job als auch eine Bigtable-Instanz bereitgestellt werden. Normalerweise sind in Versionen, die größer als Pilot sind, die erforderlichen Abhängigkeiten enthalten.

Einführung

Die Federation API ist eine typische REST API, die JSON-Strukturen zurückgibt. Um auf die API zuzugreifen, verwenden Sie entweder den MDE-Proxy oder stellen Sie die API über Identity-Aware Proxy bereit.

Die über die API verfügbaren Daten sind:

Verfügbare Daten	API-Stammpfad über Tunnel
Datensätze aus BigLake abrufen	/data/v1/bigquery
Datensätze aus Bigtable abrufen	/data/v1/bigtable
Metadateninstanz über den Metadatenmanager abrufen	/data/v1/metadata
Typen und Tags aus Config Manager abrufen	/data/v1/config

In einigen Fällen werden Attributnamen abgekürzt, um eine gute Leistung beim Übertragen großer JSON-Nutzlasten über das Netzwerk zu gewährleisten. Es ist möglich, in die Antwort einen Abschnitt mit Überschriften aufzunehmen, in dem die Abkürzungen erklärt werden.

Allgemeine Abfrageparameter, die in den verschiedenen Teilen der API verwendet werden:

Abfrageparameter	Beschreibung
includeMetrics	Messwerte für die Anfragen sind in der Antwort enthalten.
includeHeader	Die Antwort enthält einen Header mit einer Erklärung der Abkürzung und Antwortstatistiken.
includeMetadata	Gibt an, ob Metadatenfelder in die Antwort aufgenommen werden sollen, wenn Datensätze zurückgegeben werden. Dadurch kann die Größe der Antwort erheblich zunehmen, obwohl dies möglicherweise nicht erforderlich ist.
nextPageToken	Wenn mehr Daten verfügbar sind als zurückgegeben, wird ein „nextPageToken“ zurückgegeben, das in der nächsten Anfrage angegeben werden kann, um die nächste Seite abzurufen. Für Bigtable wird „nextPageToken“ immer angegeben, da nicht bekannt ist, ob weitere Datensätze verfügbar sind.
includeIds	Zeilen-IDs und Quellnachrichten-IDs einbeziehen

Hier sehen Sie ein Beispiel für eine Anfrage mit drei der enthaltenen Abfrageparameter:

GET http://localhost:8080/data/v1/bigquery/records/primepaintingrobot-01-airhumidity/default-numeric-records/latest?includeMetrics=true&includeHeader=true&includeMetadata=true

Eine Beispielantwort mit den drei enthaltenen Abfrageparametern würde so aussehen:

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

Die API unterstützt serverseitiges Downsampling. Wenn Sie diese Funktion verwenden möchten, geben Sie ein Downsampling-Intervall im folgenden Format an:sample=Duration,Unit,Aggregation

Beispiel: sample=[10,MINUTE,MEAN]

Zulässige Parameter:

• Duration: Int – Eine Ganzzahl, die das Downsampling-Intervall darstellt.
• Unit: {SECOND, MINUTE, HOUR} – Die Zeiteinheit für das Intervall.
• Aggregation: {MEAN, SUM,MAX, MIN, COUNT} – Die anzuwendende Aggregationsfunktion.

Downsampling ist für Daten aus Bigtable und Bigtable verfügbar. Die verfügbaren Aggregationstypen hängen auch vom Archetyp ab.

Datensätze aus BigQuery abrufen

Im Folgenden sehen Sie eine Beispielanfrage zum Abrufen des neuesten Datensatzes für eine Reihe von Tags mit einer Typkombination aus 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

Eine Beispielantwort würde so aussehen:

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

Im Folgenden sehen Sie ein Beispiel für eine Anfrage zum Abrufen von Datensätzen für bestimmte Tags, Typkombinationen sowie Start- und Endzeitbereiche aus 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

Eine teilweise Beispielantwort würde so aussehen:

{
   "tags": [
      {
         "tagName": "station-a-powerusage",
         "data": [
            {
               "t": "1691061419653000",
               "np": {
                  "v": 14.174
               }
            },
            {
               "t": "1691061418653000",
               "np": {
                  "v": 17.979
               }
            },

Mit der folgenden Beispielanfrage werden Datensätze für eine Kombination aus Tags und Typ aus BigQuery mit Downsampling abgerufen (der Mindestwert für jedes 5‑Minuten-Fenster im angegebenen Zeitraum):

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

Eine Beispielantwort würde so aussehen:

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

Mit der folgenden Beispielanfrage werden Datensätze für einen geclusterten Typ basierend auf zwei geclusterten Werten aus BigQuery abgerufen:

GET http://localhost:8080/data/v1/bigquery/clusteredrecords/clustered-energy-consumption-numeric-records?clusterColumnValues=DK,AAR&startTimestamp=1691062260871&endTimestamp=1691065860871

Eine teilweise Beispielantwort würde so aussehen:

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

Mit der folgenden Beispielanfrage werden Tags für einen Typ abgerufen:

GET http://localhost:8080/data/v1/bigquery/tags/default-numeric-records?startTimestamp=1690942297865&endTimestamp=1691062297865&includeHeader=true

Eine teilweise Beispielantwort würde so aussehen:

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

Datensätze aus Bigtable abrufen

Im Folgenden finden Sie ein Beispiel für eine Anfrage zum Abrufen von Datensätzen für eine Kombination aus Tags, Typ und einem Zeitraum (Start- und Endzeit) aus Bigtable:

GET http://localhost:8080/data/v1/bigtable/records/default-numeric-records?startTimestamp=1687462558476&endTimestamp=1691062558476&tags=clearcoatingrobot-01-airpressure,primepaintingrobot-01-airhumidity

Eine teilweise Beispielantwort würde so aussehen:

{
   "tags": [
      {
         "tagName": "clearcoatingrobot-01-airpressure",
         "data": [
            {
               "t": "1691062557069",
               "np": {
                  "v": 757.18
               }
            },
            {
               "t": "1691062556068",
               "np": {
                  "v": 763.71
               }
            },

Im Folgenden finden Sie eine Beispielanfrage, um den neuesten Datensatz für eine Kombination aus einem Tag und einer Typkombination aus Bigtable abzurufen:

GET http://localhost:8080/data/v1/bigtable/records/clearcoatingrobot-01-airpressure/default-numeric-records/latest?includeHeader=true

Eine Beispielantwort würde so aussehen:

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

Metadateninstanz vom Metadatenmanager abrufen

Im Folgenden sehen Sie eine Beispielanfrage zum Abrufen einer Metadateninstanz aus dem Metadatenmanager:

GET http://localhost:8080/data/v1/metadata/instances/41e9a32b-e85f-4a9a-a6a2-a3784855e859?includeHeader=true

Eine teilweise Beispielantwort würde so aussehen:

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

Typen und Tags aus Config Manager abrufen

Im Folgenden sehen Sie ein Beispiel für eine Anfrage zum Abrufen von Tags aus Config Manager:

GET http://localhost:8080/data/v1/config/tags?includeHeader=true&pageSize=10

Eine teilweise Beispielantwort würde so aussehen:

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

Im Folgenden finden Sie ein Beispiel für eine Anfrage zum Abrufen von Typen aus Config Manager:

GET http://localhost:8080/data/v1/config/types?includeHeader=true&pageSize=5

Eine Beispielantwort würde so aussehen:

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