Azure Time Series Insights Gen1 Query API

Ez a cikk különböző REST Query API-kat ismertet. A REST API-k olyan szolgáltatásvégpontok, amelyek támogatják a HTTP-műveletek (metódusok) készleteit, amelyek lehetővé teszik Azure Time Series Insights Gen1-környezetek lekérdezését.

Környezetek API lekérése

A Környezetek lekérése API visszaadja azoknak a környezeteknek a listáját, amelyek eléréséhez a hívó jogosult.

• Végpont és művelet:

  GET https://api.timeseries.azure.com/environments?api-version=2016-12-12
  

• Példakérés törzsére: Nem alkalmazható

• Példa válasz törzse:

  {
    "environments": [
      {
        "displayName":"Sensors",
        "environmentFqdn": "00000000-0000-0000-0000-000000000000.env.timeseries.azure.com",
        "environmentId":"00000000-0000-0000-0000-000000000000",
        "resourceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/RdxProdAssetsEastUs/providers/Microsoft.TimeSeriesInsights/environments/Sensors",
        "roles": [
          "Reader",
          "Contributor"
        ]
      }
    ]
  }
  

  Megjegyzés

  A environmentFqdn választulajdonság egy egyedi, teljes tartománynév ahhoz a környezethez, amelyet a környezetenkénti lekérdezési API-kérésekben használnak.

Környezeti rendelkezésre állási API lekérése

A Get Environment Availability API az eseményszám eloszlását adja vissza az esemény időbélyeg -$ts. A környezet rendelkezésre állása gyorsítótárazva van, és a válaszidő nem függ a környezetben lévő események számától.

• Végpont és művelet:

  GET https://<environmentFqdn>/availability?api-version=2016-12-12
  

• Példakérés törzsére: Nem alkalmazható

• Példa válasz törzse:

  {
    "range": {
      "from": "2016-08-01T01:02:03Z",
      "to": "2016-08-31T03:04:05Z"
    },
    "intervalSize": "1h",
    "distribution": {
      "2016-08-01T00:00:00Z": 123,
      "2016-08-31T03:00:00Z": 345
    }
  }
  

  A program egy üres objektumot ad vissza az események nélküli környezetekhez.

Környezeti metaadatok API lekérése

A Környezet metaadatainak lekérése API egy adott keresési tartomány környezeti metaadatait adja vissza. A metaadatok tulajdonsághivatkozások halmazaként lesznek visszaadva. Azure Time Series Insights Gen1 belsőleg gyorsítótárazza és hozzávetőlegesen megjeleníti a metaadatokat, és további tulajdonságokat adhat vissza, amelyek a keresési tartomány pontos eseményeiben szerepelnek.

• Végpont és művelet:

  POST https://<environmentFqdn>/metadata?api-version=2016-12-12
  

• Bemeneti hasznos adatstruktúra:

  • Keresési span záradék (kötelező)

• Példakérés törzsére:

  {
     "searchSpan": {
       "from": {"dateTime":"2016-08-01T00:00:00.000Z"},
       "to": {"dateTime":"2016-08-31T00:00:00.000Z"}
     }
  }
  

• Példa válasz törzse:

  {
     "properties": [
       {
         "name": "sensorId",
         "type": "String"
       },
       {
         "name": "sensorValue",
         "type": "Double"
       },
       {
         "name": "iothub-connection-device-id",
         "type": "String"
       }
     ]
  }
  

  A rendszer üres properties tömböt ad vissza, ha a környezet üres, vagy nincsenek események a keresési tartományon belül.

  A beépített tulajdonságok nem jelennek meg a tulajdonságok listájában.

Környezeti események API lekérése

A Get Environment Events API a keresési tartománynak és a predikátumnak megfelelő nyers események listáját adja vissza.

• Végpont és művelet:

  POST https://<environmentFqdn>/events?api-version=<apiVersion>
  

• Bemeneti hasznos adatstruktúra:

  • Keresési span záradék (kötelező)
  • Predikátum záradék (nem kötelező)
  • Korlát záradék (kötelező)

• Példakérés törzsére:

  {
    "searchSpan": {
      "from": {
        "dateTime": "2019-12-30T00:00:00.000Z"
      },
      "to": {
        "dateTime": "2019-12-31T23:00:00.000Z"
      }
    },
    "predicateString": "PointValue.Double = 3.14",
    "top": {
      "sort": [
        {
          "input": {
            "builtInProperty": "$ts"
          },
            "order": "Asc"
          }
      ],
      "count": 1000
    }
  }
  

  Megjegyzés

  • A beágyazott rendezés (azaz két vagy több tulajdonság szerinti rendezés) jelenleg nem támogatott.
  • Az események felülre rendezhetők és korlátozhatók.
  • A rendezés minden tulajdonságtípus esetében támogatott. A rendezés logikai kifejezésekhez definiált összehasonlító operátorokra támaszkodik.

• Példa válasz törzse:

  {
    "warnings": [],
    "events": [
      {
        "schema": {
          "rid": 0,
          "$esn" : "buildingsensors",
          "properties" : [{
            "name" : "sensorId",
            "type" : "String"
          }, {
            "name" : "sensorValue",
            "type" : "String"
          }]
        },
        "$ts" : "2016-08-30T23:20:00Z",
        "values" : ["IndoorTemperatureSensor", 72.123]
      }, {
        "schemaRid" : 0,
        "$ts" : "2016-08-30T23:21:00Z",
        "values" : ["IndoorTemperatureSensor", 72.345]
      }
    ]
  }
  

Környezeti események streamelt API lekérése

A Környezeti események lekérése streamelt API a keresési tartománynak és a predikátumnak megfelelő nyers események listáját adja vissza.

Ez az API a WebSocket Secure Protocol használatával végez streamelést, és részleges eredményeket ad vissza. Mindig további eseményeket ad vissza. Vagyis az új üzenet adalék az előzőhöz. Az új üzenet olyan új eseményeket tartalmaz, amelyek nem voltak az előző üzenetben. Az előző üzenetet meg kell őrizni az új üzenet hozzáadásakor.

• Végpont és művelet:

  GET wss://<environmentFqdn>/events?api-version=<apiVersion>
  

• Bemeneti hasznos adatstruktúra:

  • Keresési span záradék (kötelező)
  • Predikátum záradék (nem kötelező)
  • Korlát záradék (kötelező)

• Példakérési üzenetre:

  {
    "headers" : {
      "Authorization":"Bearer <YOUR_AAD_OAUTH_TOKEN>",
      "x-ms-client-request-id" : "132gae-w343-41a1-2342-w23ta4532"
    },
    "content": {
      "searchSpan": {
        "from": "2017-04-30T23:00:00.000Z",
        "to": "2017-05-01T00:00:00.000Z"
      },
      "top": {
        "sort": [
          {
            "input": {
              "builtInProperty": "$ts"
            },
            "order": "Asc"
          }
        ],
        "count": 1000
      }
    }
  }
  

  Megjegyzés

  • A beágyazott rendezés (azaz két vagy több tulajdonság szerinti rendezés) jelenleg nem támogatott.
  • Az események felülre rendezhetők és korlátozhatók.
  • A rendezés minden tulajdonságtípus esetében támogatott. A rendezés logikai kifejezésekhez definiált összehasonlító operátorokra támaszkodik.

• Példa válaszüzenet:

  {
    "headers": {
      "x-ms-request-id": "a325-a345-sy43-w332-a4qat36a2262"
    },
    "content": {
      "events": [
        {
          "schema": {
            "rid": 0,
            "$esn": "devicedata",
            "properties": [
              {
                "name": "Id",
                "type": "String"
              },
              {
                "name": "TemperatureControlLevel",
                "type": "Double"
              },
              {
                "name": "Type",
                "type": "String"
              },
              {
                "name": "UnitVersion",
                "type": "String"
              },
              {
                "name": "Station",
                "type": "String"
              },
              {
                "name": "ProductionLine",
                "type": "String"
              },
              {
                "name": "Factory",
                "type": "String"
              },
              {
                "name": "Timestamp",
                "type": "DateTime"
              }
            ]
          },
          "$ts": "2017-04-30T23:00:00Z",
          "values": [
            "82faa3c1-f11d-44f5-a1ca-e448f6123eee",
            0.9835468282931982,
            "temp control rate",
            "1.1.7.0",
            "Station5",
            "Line1",
            "Factory2",
            "2017-04-30T23:00:00Z"
          ]
        },
        {
          "schemaRid": 0,
          "$ts": "2017-04-30T23:00:00Z",
          "values": [
            "acb2f926-62cc-4a88-9246-94a26ebcaee3",
            0.8542095381579537,
            "temp control rate",
            "1.1.7.0",
            "Station2",
            "Line1",
            "Factory3",
            "2017-04-30T23:00:00Z"
          ]
        }
      ]
    },
    "warnings": [],
    "percentCompleted": 100
  }
  

Környezeti összesítések API lekérése

A Get Environment Aggregates API egy megadott tulajdonság alapján csoportosítja az eseményeket, mivel opcionálisan más tulajdonságok értékeit méri.

• Végpont és művelet:

  POST https://<environmentFqdn>/aggregates?api-version=<apiVersion>
  

• Bemeneti hasznos adatstruktúra:

  • Keresési span záradék (kötelező)
  • Predikátum záradék (nem kötelező)
  • Összesítési záradék (kötelező)

• Példakérés törzsére:

  {
   "searchSpan": {
     "from": {
       "dateTime": "2019-12-30T00:00:00.000Z"
     },
     "to": {
       "dateTime": "2019-12-31T23:00:00.000Z"
     }
   },
   "predicateString": "PointValue.Double > 1000",
   "aggregates": [
     {
       "dimension": {
         "uniqueValues": {
           "input": {
             "property": "iothub-connection-device-id",
             "type": "String"
           },
           "take": 100
         }
       },
       "aggregate": {
         "dimension": {
           "dateHistogram": {
             "input": {
               "builtInProperty": "$ts"
             },
             "breaks": {
               "size": "1h"
             }
           }
         },
         "measures": [
           {
             "min": {
               "input": {
                 "property": "series.flowRate",
                 "type": "Double"
               }
             }
           },
           {
             "count": {}
           }
         ]
       }
     }
   ]
  }
  

• Példa válasz törzse:

  {
    "aggregates": [
      {
        "dimension": [
          "Test-Device-A11342"
        ],
        "aggregate": {
          "dimension": [
            "2019-12-30T23:00:00Z",
            "2019-12-31T00:00:00Z"
          ],
          "measures": [
            [
              [
                0.319668575730514,
                2678
              ],
              [
                0.08442680357734211,
                1238
              ]
            ]
          ]
        }
      }
    ],
    "warnings": []
  }
  

  Ha nincs megadva mértékkifejezés, és az események listája üres, a válasz üres lesz.

  Ha mértékek vannak jelen, a válasz egyetlen rekordot tartalmaz dimenzióértékkel null , a 0 darabszám értékét és más null típusú mértékek értékét.

Környezeti összesítések streamelt API lekérése

A Get Environment Aggregates Streamed API egy megadott tulajdonság alapján csoportosítja az eseményeket, mivel opcionálisan más tulajdonságok értékeit is méri:

• Ez az API a WebSocket Secure Protocol protokollt használja a streameléshez, és részleges eredményeket ad vissza.
• Mindig az összes érték pótlását (pillanatképét) adja vissza.
• Az ügyfél elvetheti a korábbi csomagokat.

• Végpont és művelet:

  GET wss://<environmentFqdn>/aggregates?api-version=<apiVersion>
  

• Bemeneti hasznos adatstruktúra:

  • Keresési span záradék (kötelező)
  • Predikátum záradék (nem kötelező)
  • Összesítési záradék (kötelező)

• Példakérési üzenetre:

  {
    "headers":{  
      "Authorization":"Bearer <YOUR_AAD_OAUTH_TOKEN>"
    },
    "content":{  
      "predicate":{  
        "predicateString":""
      },
      "searchSpan":{  
        "from":"2017-04-30T23:00:00.000Z",
        "to":"2017-05-01T00:00:00.000Z"
      },
      "aggregates":[{  
        "dimension":{  
          "dateHistogram":{  
            "input":{  
              "builtInProperty":"$ts"
            },
            "breaks":{  
              "size":"1m"
            }
          }
        },
        "measures":[{  
          "count":{}
        }]
      }]
    }
  }
  

• Példa válaszüzenetek:

  {  
    "headers":{  
      "x-ms-request-id":"abc3243-23af-23ad-3224s-a32525age"
    },
    "content":[  
      {  
        "dimension":[  
          "2017-04-30T23:00:00Z",
          "2017-04-30T23:01:00Z",
          "2017-04-30T23:02:00Z",
          "2017-04-30T23:03:00Z",
          "2017-04-30T23:04:00Z"
        ],
        "measures":[  
          [ 722 ],
          [ 721 ],
          [ 722 ],
          [ 721 ],
          [ 722 ]
        ]
      }
    ],
    "warnings":[ ],
    "percentCompleted":100
  }
  

  Ha nincs megadva mértékkifejezés, és az események listája üres, a válasz üres lesz.

  Ha mértékek vannak jelen, a válasz egyetlen rekordot tartalmaz dimenzióértékkel null , a 0 darabszám értékét és más null típusú mértékek értékét.

Korlátok

A lekérdezés végrehajtása során a következő korlátok vonatkoznak az erőforrások több környezet és felhasználó közötti igazságos használatára:

Hibakezelés és megoldás

A tulajdonság nem található viselkedése

A lekérdezésben hivatkozott tulajdonságok esetében, akár predikátumok részeként, akár az összesítések (mértékek) részeként, a lekérdezés alapértelmezés szerint megpróbálja feloldani a tulajdonságot a környezet globális keresés tartományában. Ha a tulajdonság megtalálható, a lekérdezés sikeres lesz. Ha a tulajdonság nem található, a lekérdezés meghiúsul.

Ezt a viselkedést azonban módosíthatja úgy, hogy meglévőként, de értékekkel null kezelje a tulajdonságokat, ha azok nincsenek jelen a környezetben. Ehhez állítsa be az opcionális kérelemfejlécet x-ms-property-not-found-behavior a következő értékre UseNull: .

A kérelem fejlécének UseNull lehetséges értékei a vagy ThrowError (alapértelmezett). Ha értékként van beállítva UseNull , a lekérdezés akkor is sikeres lesz, ha a tulajdonságok nem léteznek, és a válasz figyelmeztetéseket tartalmaz, amelyek a nem található tulajdonságokat jelenítik meg.

Megoldatlan tulajdonságok jelentése

Megadhatja a predikátumok, dimenziók és mértékkifejezések tulajdonsághivatkozásait. Ha egy adott névvel és típussal rendelkező tulajdonság nem létezik egy adott keresési tartományhoz, a rendszer megkísérel feloldani egy tulajdonságot egy globális időtartamon keresztül.

A megoldás sikerességétől függően a következő figyelmeztetés vagy hiba jelenhet meg:

• Ha egy tulajdonság globális időtartományon keresztül létezik a környezetben, a rendszer megfelelően feloldja azt, és egy figyelmeztetés jelenik meg, amely tájékoztatja arról, hogy a tulajdonság értéke egy adott keresési tartományra vonatkozik null .
• Ha egy tulajdonság nem létezik a környezetben, hibaüzenet jelenik meg, és a lekérdezés végrehajtása meghiúsul.

Hibaválaszok

Ha a lekérdezés végrehajtása sikertelen, a JSON-válasz hasznos adata a következő struktúrával rendelkező hibaválaszt tartalmaz:

{
  "error" : {
    "code" : "...",
    "message" : "...",
    "innerError" : {  
      "code" : "...",
      "message" : "...",
    }
  }
}

innerError Itt nem kötelező megadni. Az alapszintű hibák, például a hibásan formázott kérések mellett a következő hibák jelennek meg:

Figyelmeztetések

A Lekérdezési API-válasz tartalmazhat figyelmeztetések listáját bejegyzésként "warnings" a HTTP-válasz vagy a WebSocket válaszüzenet gyökerében. Jelenleg figyelmeztetések jönnek létre, ha a tulajdonság nem található egy adott keresési tartományhoz, de globális időtartományra vonatkozó környezetben található. Akkor is létrejön, ha a fejléc x-ms-property-not-found-behaviorUseNull értéke, és a hivatkozott tulajdonság még a globális keresés spanban sem létezik.

Minden figyelmeztető objektum a következő mezőket tartalmazhatja:

Az alábbi kód példákat mutat be a predikátumra, a predikátumon belüli predikátumi sztringre, a dimenzióra és a mértékre vonatkozó figyelmeztetésekre:

"warnings": [
  {
    "code": "PropertyNotFound",
    "message": "Predicate property 'X' of type 'String' is not found in local search span.",
    "target": "predicate.and[0].eq.left.property.name"
  },
  {
    "code": "PropertyNotFound",
    "message": "Predicate string property 'X' is not found in local search span.",
    "target": "predicate.and[1].predicateString",
    "warningDetails": {
      "startPos": 1,
      "endPos": 2,
      "line": 1,
      "col": 1
    }
  },
  {
    "code": "PropertyNotFound",
    "message": "Dimension property 'X' of type 'String' is not found in local search span.",
    "target": "aggregates.dimension.uniqueValues.input.property"
  },
  {
    "code": "PropertyNotFound",
    "message": "Measure property 'X' of type 'String' is not found in local search span.",
    "target": "aggregates.aggregates.measures[0].min.input.property"
  }
]

Lásd még

További információ az alkalmazásregisztrációról és az Azure Active Directory programozási modellről: Azure Active Directory fejlesztőknek.

A kérelem- és hitelesítési paraméterekkel kapcsolatos további információkért lásd: Hitelesítés és engedélyezés.

A HTTP-kérések és -válaszok tesztelését segítő eszközök a következők:

• Fiddler. Ez az ingyenes webes hibakeresési proxy elfoghatja a REST-kéréseket, így diagnosztizálhatja a HTTP-kéréseket és a válaszüzeneteket.
• JWT.io. Ezzel az eszközzel gyorsan lerakhatja a jogcímeket a tulajdonosi jogkivonatban, majd ellenőrizheti azok tartalmát.
• Postás. Ez egy ingyenes HTTP-kérés- és választesztelési eszköz a REST API-k hibakereséséhez.

Az 1. generációs Azure Time Series Insights a Gen1 dokumentációjának áttekintésével talál további információt.