Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Federation API を使用してクエリする

このガイドでは、一般的なユースケースで Federation API を使用して Manufacturing Data Engine（MDE）のデータをクエリする方法について説明します。

フェデレーションは、構成データの一部、BigQuery または Bigtable に保存されているデータへのアクセスを提供します。

Federation API を使用して Bigtable のデータをクエリするには、正しい「サイズ」で MDE をデプロイしていることを確認してください。詳細については、サイズに関するセクションをご覧ください。必要な Dataflow ライタージョブと Bigtable インスタンスをデプロイするサイズを選択します。通常、Pilot より大きいものには必要な依存関係が含まれています。

はじめに

Federation API は、JSON 構造を返す一般的な REST API です。API にアクセスするには、MDE プロキシを使用するか、Identity-Aware Proxy を使用して公開します。

API で利用できるデータは次のとおりです。

利用可能なデータ	トンネルを使用する API ルートパス
BigLake からレコードを取得する	`/data/v1/bigquery`
Bigtable からレコードを取得する	`/data/v1/bigtable`
Metadata Manager からメタデータインスタンスを取得する	`/data/v1/metadata`
構成マネージャーからタイプとタグを取得する	`/data/v1/config`

ネットワーク経由で大きな JSON ペイロードを転送する際のパフォーマンスを確保するため、属性名が省略されることがあります。略語を説明するヘッダーセクションをレスポンスに含めることができます。

API のさまざまな部分で使用される一般的なクエリパラメータは次のとおりです。

クエリパラメータ	説明
`includeMetrics`	クエリに関連する指標がレスポンスに含まれます。
`includeHeader`	レスポンスには、略語の説明とレスポンスの統計情報を含むヘッダーが含まれます。
`includeMetadata`	レコードを返すときに、レスポンスにメタデータフィールドを含めるかどうかを指定します。これにより、レスポンスのサイズが大幅に増加し、不要になる可能性があります。
`nextPageToken`	返されたデータよりも多くのデータがある場合は、次のリクエストで指定して次のページを取得できる nextPageToken が返されます。Bigtable では、使用可能なレコードが他にもあるかどうかを判断する方法がないため、nextPageToken が常に提供されます。
`includeIds`	行 ID とソースメッセージ ID を含めます。

次の例は、3 つのクエリパラメータを含むリクエストの例です。

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

3 つのクエリパラメータを含むレスポンスの例は次のようになります。

{
  "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 の 2 つのクラスタ値に基づいて、クラスタ化されたタイプのレコードを取得します。

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

構成マネージャーからタイプとタグを取得する

以下は、Config Manager からタグを取得するリクエストのサンプルです。

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

Config Manager からタイプを取得するリクエストの例を次に示します。

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

Federation API を使用してクエリする

はじめに

BigQuery からレコードを取得する

Bigtable からレコードを取得する

メタデータ マネージャーからメタデータ インスタンスを取得する

構成マネージャーからタイプとタグを取得する

メタデータマネージャーからメタデータインスタンスを取得する