Membuat kueri menggunakan Federation API

Panduan ini menjelaskan cara membuat kueri data di Manufacturing Data Engine (MDE) menggunakan Federation API untuk kasus penggunaan umum.

Federasi menyediakan akses ke bagian data konfigurasi, data yang disimpan di BigQuery atau Bigtable.

Untuk menggunakan Federation API guna membuat kueri data di Bigtable, pastikan Anda telah men-deploy MDE dengan "ukuran" yang benar. Untuk mengetahui informasi selengkapnya, lihat bagian ukuran dan pilih ukuran yang men-deploy tugas penulis Dataflow yang diperlukan serta instance Bigtable. Biasanya, apa pun yang lebih besar dari Pilot menyertakan dependensi yang diperlukan.

Pengantar

Federation API adalah REST API umum yang menampilkan struktur JSON. Untuk mengakses API, gunakan proxy MDE atau ekspos menggunakan Identity-Aware Proxy.

Data yang tersedia melalui API adalah sebagai berikut:

Data yang Tersedia	Jalur root API menggunakan tunnel
Mendapatkan data dari BigLake	/data/v1/bigquery
Mendapatkan data dari Bigtable	/data/v1/bigtable
Mendapatkan instance metadata dari Pengelola Metadata	/data/v1/metadata
Mendapatkan jenis dan tag dari Config Manager	/data/v1/config

Dalam beberapa kasus, nama atribut disingkat untuk memastikan performa yang tepat saat mentransfer payload JSON besar di seluruh jaringan. Bagian header dapat disertakan dalam respons yang menjelaskan singkatan.

Parameter kueri umum yang digunakan di berbagai bagian API adalah:

Parameter kueri	Deskripsi
includeMetrics	Metrik yang terkait dengan kueri disertakan dalam respons.
includeHeader	Header disertakan dalam respons dengan penjelasan singkatan dan statistik respons.
includeMetadata	Saat menampilkan data, parameter ini menentukan apakah akan menyertakan kolom metadata dalam respons atau tidak. Hal ini dapat meningkatkan ukuran respons secara signifikan dan mungkin tidak diperlukan.
nextPageToken	Jika ada lebih banyak data yang tersedia daripada yang ditampilkan, nextPageToken akan ditampilkan yang dapat diberikan dalam permintaan berikutnya untuk mendapatkan halaman berikutnya. Untuk Bigtable, nextPageToken selalu diberikan karena tidak ada cara untuk mengetahui apakah ada lebih banyak data yang tersedia atau tidak.
includeIds	Sertakan ID baris dan ID pesan sumber.

Berikut adalah contoh permintaan dengan tiga parameter kueri yang disertakan:

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

Contoh respons dengan tiga parameter kueri yang disertakan akan terlihat mirip dengan contoh berikut:

{
  "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 ini mendukung pengurangan sampel sisi server. Untuk menggunakan fitur ini, tentukan interval pengurangan sampel dalam format:sample=Duration,Unit,Aggregation

Contoh: sample=[10,MINUTE,MEAN]

Parameter yang diizinkan:

• Duration: Int - Bilangan bulat yang merepresentasikan interval pengurangan sampel.
• Unit: {SECOND, MINUTE, HOUR} - Unit waktu untuk interval.
• Aggregation: {MEAN, SUM,MAX, MIN, COUNT} - Fungsi agregasi yang akan diterapkan.

Pengurangan frekuensi pengambilan sampel tersedia untuk data dari Bigtable dan Bigtable. Jenis agregasi yang tersedia juga bergantung pada Archetype.

Mendapatkan rekaman dari BigQuery

Berikut adalah contoh permintaan untuk mendapatkan data terbaru untuk sejumlah tag dengan kombinasi jenis dari 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

Contoh responsnya akan terlihat seperti berikut:

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

Berikut adalah contoh permintaan untuk mengambil rekaman untuk kombinasi jenis dan tag tertentu, serta rentang waktu mulai dan berakhir dari 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

Contoh respons sebagian akan terlihat seperti berikut:

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

Contoh permintaan berikut mengambil data untuk kombinasi tag dan jenis dari BigQuery dengan pengurangan sampel (nilai minimum untuk setiap interval lima menit dalam rentang waktu yang ditentukan):

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

Contoh responsnya akan terlihat seperti berikut:

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

Contoh permintaan berikut mendapatkan data untuk jenis berklaster berdasarkan dua nilai berklaster dari BigQuery:

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

Contoh respons sebagian akan terlihat seperti berikut:

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

Contoh permintaan berikut mendapatkan tag untuk suatu jenis:

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

Contoh respons sebagian akan terlihat seperti berikut:

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

Mendapatkan data dari Bigtable

Berikut adalah contoh permintaan untuk mendapatkan data untuk kombinasi tag, jenis, dan rentang waktu (waktu mulai dan berakhir) dari Bigtable:

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

Contoh respons sebagian akan terlihat seperti berikut:

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

Berikut adalah contoh permintaan untuk mendapatkan data terbaru untuk kombinasi tag dan jenis dari Bigtable:

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

Contoh responsnya akan terlihat seperti berikut:

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

Mendapatkan instance metadata dari pengelola metadata

Berikut adalah contoh permintaan untuk mendapatkan instance metadata dari pengelola metadata:

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

Contoh respons sebagian akan terlihat seperti berikut:

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

Mendapatkan jenis dan tag dari Config Manager

Berikut adalah contoh permintaan untuk mendapatkan tag dari Config Manager:

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

Contoh respons sebagian akan terlihat seperti berikut:

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

Berikut adalah contoh permintaan untuk mendapatkan jenis dari Config Manager:

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

Contoh responsnya akan terlihat seperti berikut:

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