‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

שאילתה באמצעות Federation API

במדריך הזה מוסבר איך לשלוח שאילתות לנתונים ב-Manufacturing Data Engine ‏ (MDE) באמצעות Federation API בתרחישי שימוש אופייניים.

הפדרציה מספקת גישה לחלקים מנתוני ההגדרה, לנתונים שמאוחסנים ב-BigQuery או ב-Bigtable.

כדי להשתמש ב-Federation API כדי לשלוח שאילתות לנתונים ב-Bigtable, צריך לוודא שפרסתם את MDE עם הערך הנכון של size. מידע נוסף זמין בקטע על הגדלים. צריך לבחור גודל שמאפשר פריסה של משימת כתיבה נדרשת של Dataflow וגם של מופע Bigtable. בדרך כלל, כל מה שגדול מ-Pilot כולל את התלות הנדרשת.

מבוא

‫Federation API הוא API טיפוסי בארכיטקטורת REST שמחזיר מבני JSON. כדי לגשת ל-API, צריך להשתמש ב-proxy של MDE או לחשוף אותו באמצעות שרת proxy לאימות זהויות (IAP).

הנתונים שזמינים דרך ה-API הם:

הנתונים הזמינים	נתיב הבסיס של ה-API באמצעות מנהרה
קבלת רשומות מ-BigLake	`/data/v1/bigquery`
קבלת רשומות מ-Bigtable	`/data/v1/bigtable`
אחזור מופע של מטא-נתונים מהמרכז לניהול מטא-נתונים	`/data/v1/metadata`
איך מקבלים סוגים ותגים מ-Config Manager	`/data/v1/config`

במקרים מסוימים, שמות המאפיינים מקוצרים כדי להבטיח ביצועים תקינים כשמעבירים מטען ייעודי (payload) גדול של JSON ברשת. אפשר לכלול בתגובה קטע של כותרות שמסביר את הקיצורים.

הפרמטרים הכלליים של שאילתות שמשמשים בחלקים השונים של ה-API הם:

פרמטר של שאילתה	תיאור
`includeMetrics`	התשובה כוללת מדדים שקשורים לשאילתות.
`includeHeader`	התגובה כוללת כותרת עם הסבר על הקיצור וסטטיסטיקות של התגובה.
`includeMetadata`	כשמחזירים רשומות, הפרמטר הזה מציין אם לכלול שדות של מטא-נתונים בתגובה. הפעולה הזו יכולה להגדיל באופן משמעותי את גודל התשובה, ויכול להיות שהיא לא נחוצה.
`nextPageToken`	אם יש נתונים נוספים מעבר לנתונים שמוחזרים, מוחזר nextPageToken שאפשר לספק בבקשה הבאה כדי לקבל את הדף הבא. ב-Bigtable, תמיד מסופק nextPageToken כי אין דרך לדעת אם יש רשומות נוספות זמינות או לא.
`includeIds`	צריך לכלול את מזהי השורות ואת מזהי ההודעות מהמקור.

בדוגמה הבאה מוצגת בקשה עם שלושה מפרמטרים השאילתה:

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

בדוגמה הבאה של בקשה מתקבלים רשומות של שילוב של תגים וסוג מ-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"
    }
  ]
}

איך מקבלים סוגים ותגים מ-Config Manager

הדוגמה הבאה היא בקשה לקבלת תגים מ-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"
}

זוהי דוגמה לבקשה לקבלת סוגים מאשף ההגדרות:

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