연합 API를 사용하여 쿼리
이 가이드에서는 일반적인 사용 사례에 대해 페더레이션 API를 사용하여 제조 데이터 엔진 (MDE)에서 데이터를 쿼리하는 방법을 설명합니다.
제휴는 구성 데이터, BigQuery 또는 Bigtable에 저장된 데이터의 일부에 대한 액세스를 제공합니다.
연합 API를 사용하여 Bigtable에서 데이터를 쿼리하려면 올바른 '크기'로 MDE를 배포해야 합니다. 자세한 내용은 크기 섹션을 참고하여 필요한 Dataflow 작성기 작업과 Bigtable 인스턴스를 모두 배포하는 크기를 선택하세요. 일반적으로 Pilot보다 큰 항목에는 필수 종속 항목이 포함됩니다.
소개
연합 API는 JSON 구조를 반환하는 일반적인 REST API입니다. API에 액세스하려면 MDE 프록시를 사용하거나 Identity-Aware Proxy를 사용하여 노출하세요.
API를 통해 사용할 수 있는 데이터는 다음과 같습니다.
| 사용 가능한 데이터 | 터널을 사용하는 API 루트 경로 |
|---|---|
| BigLake에서 레코드 가져오기 | /data/v1/bigquery |
| Bigtable에서 레코드 가져오기 | /data/v1/bigtable |
| 메타데이터 관리자에서 메타데이터 인스턴스 가져오기 | /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
세 개의 쿼리 매개변수가 포함된 샘플 응답은 다음 예시와 비슷합니다.
{
"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
}
},
다음 샘플 요청은 다운샘플링 (지정된 시간 범위 내의 각 5분 간격의 최솟값)을 사용하여 BigQuery에서 태그 및 유형 조합의 레코드를 가져옵니다.
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의 두 클러스터링 값을 기반으로 클러스터링된 유형의 레코드를 가져옵니다.
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"
}
]
}
구성 관리자에서 유형 및 태그 가져오기
다음은 구성 관리자에서 태그를 가져오는 샘플 요청입니다.
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"
}
다음은 구성 관리자에서 유형을 가져오는 샘플 요청입니다.
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="
}