Azure Time Series Insights Gen1 Query API

I den här artikeln beskrivs olika REST Query-API:er. REST-API:er är tjänstslutpunkter som stöder uppsättningar av HTTP-åtgärder (metoder), som gör att du kan fråga Azure Time Series Insights Gen1-miljöer.

Hämta miljö-API

API:et Get Environments returnerar listan över miljöer som anroparen har behörighet att komma åt.

• Slutpunkt och åtgärd:

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

• Exempel på begärandetext: Ej tillämpligt

• Exempel på svarstext:

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

  Anmärkning

  Svarsegenskapen environmentFqdn är ett unikt, fullständigt kvalificerat domännamn för den miljö som används i fråge-API-begäranden per miljö.

Hämta API för miljötillgänglighet

API:et Get Environment Availability returnerar fördelningen av antalet händelser över den tidsstämpel för händelsen som $ts. Miljötillgängligheten cachelagras och svarstiden beror inte på antalet händelser i en miljö.

• Slutpunkt och åtgärd:

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

• Exempel på begärandetext: Ej tillämpligt

• Exempel på svarstext:

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

  Ett tomt objekt returneras för miljöer utan händelser.

Hämta API för miljömetadata

API:et Get Environment Metadata returnerar miljömetadata för ett visst sökintervall. Metadata returneras som en uppsättning egenskapsreferenser. Azure Time Series Insights Gen1 cachelagrar och approximerar metadata internt och kan returnera fler egenskaper som finns i de exakta händelserna i sökintervallet.

• Slutpunkt och åtgärd:

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

• Struktur för inkommande nyttolast:

  • Sökspan-klausul (obligatoriskt)

• Exempel på begärandetext:

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

• Exempel på svarstext:

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

  En tom properties matris returneras när miljön är tom eller om det inte finns några händelser i ett sökintervall.

  Inbyggda egenskaper returneras inte i listan över egenskaper.

Hämta API för miljöhändelser

API:et Get Environment Events returnerar en lista över råhändelser som matchar sökintervallet och predikatet.

• Slutpunkt och åtgärd:

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

• Struktur för inkommande nyttolast:

  • Sökspan-klausul (obligatoriskt)
  • Predikatsats (valfritt)
  • Limit-klausul (obligatoriskt)

• Exempel på begärandetext:

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

  Anmärkning

  • Kapslad sortering (d.v.s. sortering efter två eller flera egenskaper) stöds för närvarande inte.
  • Händelser kan sorteras och begränsas till toppen.
  • Sortering stöds för alla egenskapstyper. Sorteringen är beroende av jämförelseoperatorer som har definierats för booleska uttryck.

• Exempel på svarstext:

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

Hämta strömmat API för miljöhändelser

API:et Get Environment Events Streamed returnerar en lista över råhändelser som matchar sökintervallet och predikatet.

Det här API:et använder WebSocket Secure Protocol för att utföra strömning och returnera partiella resultat. Den returnerar alltid ytterligare händelser. Det innebär att det nya meddelandet är ett tillägg till det föregående. Det nya meddelandet innehåller nya händelser som inte fanns i det tidigare meddelandet. Det tidigare meddelandet ska behållas när det nya meddelandet läggs till.

• Slutpunkt och åtgärd:

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

• Struktur för inkommande nyttolast:

  • Sökspan-klausul (obligatoriskt)
  • Predikatsats (valfritt)
  • Limit-klausul (obligatoriskt)

• Exempel på begäran:

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

  Anmärkning

  • Kapslad sortering (d.v.s. sortering efter två eller flera egenskaper) stöds för närvarande inte.
  • Händelser kan sorteras och begränsas till toppen.
  • Sortering stöds för alla egenskapstyper. Sorteringen är beroende av jämförelseoperatorer som har definierats för booleska uttryck.

• Exempel på svarsmeddelande:

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

Hämta API för miljöaggregeringar

API:et Get Environment Aggregates grupperar händelser efter en angiven egenskap eftersom det eventuellt mäter värdena för andra egenskaper.

• Slutpunkt och åtgärd:

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

• Struktur för inkommande nyttolast:

  • Sökspan-klausul (obligatoriskt)
  • Predikatsats (valfritt)
  • Aggregatklausul (obligatoriskt)

• Exempel på begärandetext:

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

• Exempel på svarstext:

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

  Om inga måttuttryck anges och listan över händelser är tom kommer svaret att vara tomt.

  Om det finns mått innehåller svaret en enda post med ett null dimensionsvärde, ett 0 värde för antal och ett null värde för andra typer av mått.

Hämta strömmat API för miljöaggregeringar

API:et Get Environment Aggregates Streamed grupperar händelser efter en angiven egenskap eftersom det eventuellt mäter värdena för andra egenskaper:

• Det här API:et använder WebSocket Secure Protocol för strömning och för att returnera partiella resultat.
• Den returnerar alltid en ersättning (ögonblicksbild) av alla värden.
• Tidigare paket kan tas bort av klienten.

• Slutpunkt och åtgärd:

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

• Struktur för inkommande nyttolast:

  • Sökspan-klausul (obligatoriskt)
  • Predikatsats (valfritt)
  • Aggregatklausul (obligatoriskt)

• Exempel på begäran:

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

• Exempel på svarsmeddelanden:

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

  Om inga måttuttryck anges och listan över händelser är tom kommer svaret att vara tomt.

  Om det finns mått innehåller svaret en enda post med ett null dimensionsvärde, ett 0 värde för antal och ett null värde för andra typer av mått.

Gränser

Följande gränser tillämpas under frågekörningen för att rättvist utnyttja resurser mellan flera miljöer och användare:

Felhantering och lösning

Beteendet Egenskapen hittades inte

För egenskaper som refereras i frågan, antingen som en del av predikat eller en del av aggregeringar (mått), försöker frågan som standard matcha egenskapen i miljöns globala sökintervall. Om egenskapen hittas lyckas frågan. Om egenskapen inte hittas misslyckas frågan.

Du kan dock ändra det här beteendet för att behandla egenskaper som befintliga men med null värden om de inte finns i miljön. Det gör du genom att ange det valfria begärandehuvudet x-ms-property-not-found-behavior med värdet UseNull.

Möjliga värden för begärandehuvudet är UseNull or ThrowError (standard). När du anger UseNull som värde lyckas frågan även om egenskaperna inte finns, och svaret innehåller varningar som visar de egenskaper som inte hittas.

Rapportera olösta egenskaper

Du kan ange egenskapsreferenser för predikat-, dimensions- och måttuttryck. Om en egenskap med ett visst namn och en viss typ inte finns för ett angivet sökintervall görs ett försök att matcha en egenskap under ett globalt tidsintervall.

Beroende på om lösningen lyckas kan följande varning eller fel utlösas:

• Om en egenskap finns i miljön under ett globalt tidsintervall löses den på rätt sätt och en varning genereras för att meddela dig att värdet för den här egenskapen är null för ett visst sökintervall.
• Om en egenskap inte finns i miljön genereras ett fel och frågekörningen misslyckas.

Felsvar

Om frågekörningen misslyckas innehåller JSON-svarsnyttolasten ett felsvar med följande struktur:

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

Här är innerError valfritt. Förutom grundläggande fel, till exempel en felaktig begäran, returneras följande fel:

Varningar

Ett Query API-svar kan innehålla en lista med varningar som "warnings" post under roten för HTTP-svaret eller WebSocket-svarsmeddelandet. För närvarande genereras varningar om egenskapen inte hittas för ett visst sökintervall utan hittas i en miljö för ett globalt tidsintervall. Den genereras också när rubriken x-ms-property-not-found-behavior är inställd UseNull på och en egenskap som refereras inte finns ens i det globala sökintervallet.

Varje varningsobjekt kan innehålla följande fält:

I följande kod visas exempel på varningar för predikat, predikatsträng i predikat, dimension och mått:

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

Se även

Mer information om programregistrering och Azure Active Directory-programmeringsmodellen finns i Azure Active Directory för utvecklare.

Mer information om parametrar för begäran och autentisering finns i Autentisering och auktorisering.

Verktyg som hjälper dig att testa HTTP-begäranden och svar är:

• Spelman. Den här kostnadsfria webbfelsökningsproxyn kan fånga upp dina REST-begäranden, så att du kan diagnostisera HTTP-begäran och svarsmeddelanden.
• JWT.io. Du kan använda det här verktyget för att snabbt dumpa anspråken i din ägartoken och sedan verifiera deras innehåll.
• Brevbärare. Det här är ett kostnadsfritt testverktyg för HTTP-begäran och svar för felsökning av REST-API:er.

Läs mer om Azure Time Series Insights Gen1 i Gen1-dokumentationen.