Sdílet prostřednictvím

Rozhraní API pro dotazy Azure Time Series Insights Gen1

Upozornění

Toto je článek Gen1.

Tento článek popisuje různá rozhraní API pro dotazy REST. Rozhraní REST API jsou koncové body služby, které podporují sady operací HTTP (metod), které umožňují dotazovat se na prostředí Azure Time Series Insights Gen1.

Důležité

Získat rozhraní API pro prostředí

Rozhraní API pro získání prostředí vrátí seznam prostředí, ke kterým má volající oprávnění k přístupu.

  • Koncové body a provoz:

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

  • Příklad textu požadavku: Nelze použít

  • Příklad textu odpovědi:

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

    Poznámka:

    Vlastnost odpovědi environmentFqdn je jedinečný, plně kvalifikovaný název domény pro prostředí, které se používá v požadavcích rozhraní API pro dotazy pro jednotlivá prostředí.

Získání rozhraní API pro dostupnost prostředí

Rozhraní API Get Environment Availability vrací distribuci počtu událostí v průběhu časového razítka události $ts. Dostupnost prostředí je ukládána do mezipaměti a doba odezvy nezávisí na počtu událostí v prostředí.

Tip

Rozhraní API Get Environment Availability lze použít k inicializaci prostředí uživatelského rozhraní front-end.

  • Koncové body a provoz:

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

  • Příklad textu požadavku: Nelze použít

  • Příklad textu odpovědi:

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

    Prázdný objekt je vrácen pro prostředí bez událostí.

Získat rozhraní API metadat prostředí

Rozhraní API Get Environment Metadata vrací metadata prostředí pro daný rozsah vyhledávání. Metadata jsou vrácena jako sada odkazů na vlastnosti. Azure Time Series Insights Gen1 interně ukládá metadata do mezipaměti a aproximuje je a může vracet více vlastností, které se nacházejí v přesných událostech v rozsahu hledání.

  • Koncové body a provoz:

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

  • Vstupní struktura payloadu:

    • Klauzule o rozsahu vyhledávání (povinné)

  • Příklad textu požadavku:

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

  • Příklad textu odpovědi:

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

    Prázdné properties pole je vráceno, pokud je prostředí prázdné nebo pokud v rozsahu hledání nejsou žádné události.

    Předdefinované vlastnosti se v seznamu vlastností nevrátí.

Získání rozhraní API událostí prostředí

Rozhraní API Get Environment Events vrátí seznam nezpracovaných událostí, které odpovídají rozsahu hledání a predikátu.

  • Koncové body a provoz:

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

  • Vstupní struktura payloadu:

    • Klauzule o rozsahu vyhledávání (povinné)
    • Predikátová klauzule (volitelné)
    • Limitní klauzule (povinné)

  • Příklad textu požadavku:

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

    Poznámka:

    • Vnořené řazení (tj. řazení podle dvou nebo více vlastností) není v současné době podporováno.
    • Události lze třídit a omezovat na horní.
    • Řazení je podporováno u všech typů vlastností. Řazení závisí na relačních operátorech, které jsou definovány pro booleovské výrazy.

  • Příklad textu odpovědi:

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

Získání rozhraní API pro streamování událostí prostředí

Rozhraní API Get Environment Events Streamed vrátí seznam nezpracovaných událostí, které odpovídají rozsahu vyhledávání a predikátu.

Toto rozhraní API používá protokol WebSocket Secure Protocol k provádění streamování a vracení částečných výsledků. Vždy vrací další události. To znamená, že nová zpráva je aditivní k předchozí. Nová zpráva obsahuje nové události, které nebyly v předchozí zprávě. Předchozí zpráva by měla být zachována při přidání nové zprávy.

  • Koncové body a provoz:

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

  • Vstupní struktura payloadu:

    • Klauzule o rozsahu vyhledávání (povinné)
    • Predikátová klauzule (volitelné)
    • Limitní klauzule (povinné)

  • Příklad zprávy s požadavkem:

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

    Poznámka:

    • Vnořené řazení (tj. řazení podle dvou nebo více vlastností) není v současné době podporováno.
    • Události lze třídit a omezovat na horní.
    • Řazení je podporováno u všech typů vlastností. Řazení závisí na relačních operátorech, které jsou definovány pro booleovské výrazy.

  • Příklad zprávy odpovědi:

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

Získání rozhraní API pro agregace prostředí

Rozhraní API Get Environment Aggregates seskupuje události podle zadané vlastnosti, protože volitelně měří hodnoty jiných vlastností.

Poznámka:

Hranice segmentu podporují hodnoty 10ⁿ, 2×10ⁿ nebo 5×10ⁿ , aby byly zarovnány s číselnými histogramy a lépe je podporovaly.

  • Koncové body a provoz:

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

  • Vstupní struktura payloadu:

    • Klauzule o rozsahu vyhledávání (povinné)
    • Predikátová klauzule (volitelné)
    • Kamenivo doložka (povinné)

  • Příklad textu požadavku:

    {
 "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říklad textu odpovědi:

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

    Pokud nejsou zadány žádné výrazy míry a seznam událostí je prázdný, odpověď bude prázdná.

    Pokud jsou k dispozici míry, odpověď obsahuje jeden záznam s null hodnotou dimenze, 0 hodnotou pro počet a null hodnotou pro jiné druhy měr.

Získání rozhraní API pro agregace prostředí

Rozhraní API Get Environment Aggregates Streamed seskupuje události podle zadané vlastnosti, protože volitelně měří hodnoty jiných vlastností:

  • Toto rozhraní API používá protokol WebSocket Secure Protocol pro streamování a vracení částečných výsledků.
  • Vždy vrací náhradu (snapshot) všech hodnot.
  • Předchozí pakety mohou být klientem zahozeny.

Poznámka:

Hranice segmentu podporují hodnoty 10ⁿ, 2×10ⁿ nebo 5×10ⁿ , aby byly zarovnány s číselnými histogramy a lépe je podporovaly.

  • Koncové body a provoz:

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

  • Vstupní struktura payloadu:

    • Klauzule o rozsahu vyhledávání (povinné)
    • Predikátová klauzule (volitelné)
    • Kamenivo doložka (povinné)

  • Příklad zprávy s požadavkem:

    {
  "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říklady odpovědí:

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

    Pokud nejsou zadány žádné výrazy míry a seznam událostí je prázdný, odpověď bude prázdná.

    Pokud jsou k dispozici míry, odpověď obsahuje jeden záznam s null hodnotou dimenze, 0 hodnotou pro počet a null hodnotou pro jiné druhy měr.

Omezení

Následující limity se používají během provádění dotazu pro spravedlivé využití zdrojů mezi více prostředími a uživateli:

Použitelná rozhraní API Název limitu Hodnota limitu Ovlivněné SKU Poznámky
Všechno Maximální velikost požadavku 32 kB S1, S2
Získání dostupnosti prostředí, získání metadat prostředí, získání událostí prostředí, streamování agregací prostředí Maximální počet souběžných požadavků na prostředí 10 S1, S2
Získání událostí prostředí, streamování agregací prostředí Maximální velikost odpovědi 16 MB S1, S2
Získání událostí prostředí, streamování agregací prostředí Maximální počet odkazů na jedinečné vlastnosti v predikátu, včetně řetězcových výrazů predikátu 50 S1, S2
Získání událostí prostředí, streamování agregací prostředí Max. počet fulltextových vyhledávacích termínů bez odkazu na vlastnost v řetězci predikátu 2 S1, S2 Příklad: HAS 'abc', 'abc'
Získání událostí prostředí Maximální počet událostí v odpovědi 10 000 S1, S2
Získání streamu agregací prostředí Max. počet rozměrů 5 S1, S2
Získání streamu agregací prostředí Maximální celková mohutnost ve všech dimenzích 150,000 S1, S2
Získání streamu agregací prostředí Max. počet opatření 20 S1, S2

Zpracování a řešení chyb

Chování Vlastnost nenalezena

U vlastností, na které dotaz odkazuje, ať už jako na součást predikátů nebo jako na součást agregací (měr), se ve výchozím nastavení dotaz pokusí přeložit vlastnost v globálním rozsahu vyhledávání prostředí. Pokud je vlastnost nalezena, dotaz je úspěšný. Pokud vlastnost není nalezena, dotaz se nezdaří.

Toto chování však můžete upravit tak, aby se s vlastnostmi zacházelo jako s existujícími, ale s null hodnotami, pokud nejsou v prostředí přítomny. To lze provést nastavením volitelné hlavičky x-ms-property-not-found-behavior požadavku s hodnotou UseNull.

Možné hodnoty pro hlavičku požadavku jsou UseNull or ThrowError (výchozí). Pokud hodnotu nastavíte UseNull jako hodnotu, dotaz bude úspěšný, i když vlastnosti neexistují, a odpověď bude obsahovat upozornění, která zobrazí vlastnosti, které nebyly nalezeny.

Hlášení nevyřešených vlastností

Můžete určit odkazy na vlastnosti pro výrazy predikátu, dimenze a míry. Pokud vlastnost s určitým názvem a typem pro zadaný rozsah hledání neexistuje, je proveden pokus o překlad vlastnosti v globálním časovém rozsahu.

V závislosti na úspěšnosti řešení může být vygenerováno následující upozornění nebo chyba:

  • Pokud vlastnost existuje v prostředí v globálním časovém období, je správně vyřešena a je vygenerováno upozornění, které vás upozorní, že hodnota této vlastnosti platí null pro daný rozsah hledání.
  • Pokud vlastnost v prostředí neexistuje, je vygenerována chyba a provedení dotazu se nezdaří.

Chybové odpovědi

Pokud se spuštění dotazu nezdaří, datová část odpovědi JSON obsahuje chybovou odpověď s následující strukturou:

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

innerError Zde je volitelné. Kromě základních chyb, jako je například chybně formátovaný požadavek, jsou vráceny následující chyby:

Stavový kód HTTP Kód chyby Příklad chybové zprávy Možné kódy vnitřních chyb
400 Neplatná verze API "Rozhraní API verze 2016 není podporováno. Podporované verze jsou '2016-12-12'."
400 Neplatný vstup "Nelze analyzovat řetězec predikátu." PredicateStringParseError
400 Neplatný vstup "Nelze přeložit řetězec predikátu." InvalidTypes, LimitExceeded, MissingOperand, InvalidPropertyType, InvalidLiteral, PropertyNotFound
400 Neplatný vstup "Více agregací není podporováno."
400 Neplatný vstup "Predikátová vlastnost nebyla nalezena." PropertyNotFound
400 Neplatný vstup "Změřte majetek nebyl nalezen." PropertyNotFound
400 Neplatný vstup "Vlastnost kóty nebyla nalezena." PropertyNotFound
400 Neplatný vstup "Počet opatření překročen limit." NumberOfMeasuresExceededLimit
400 Neplatný vstup "Souhrnná hloubka překročila limit." AggregateDepthExceededLimit
400 Neplatný vstup "Celková mohutnost překročila limit." TotalCardinalityExceededLimit
400 Neplatný vstup "Chybí majetek 'z'." BreaksPropertyMissing
400 Neplatný vstup "Chybí majetek 'to'." BreaksPropertyMissing
400 Neplatný vstup "Velikost požadavku byla překročena." RequestSizeExceededLimit
400 Neplatný vstup "Velikost odpovědi byla překročena." ResponseSizeExceededLimit
400 Neplatný vstup "Počet událostí byl překročen." EventCountExceededLimit
400 Neplatný vstup "Počet odkazů na nemovitost byl překročen." PropertyReferenceCountExceededLimit
400 Neplatná metoda "Na cestě 'aggregates' jsou povoleny pouze požadavky WebSocket."
400 Neplatná adresa "Adresu URL požadavku '/a/b' nelze analyzovat."
408 RequestTimeout "Vypršel časový limit požadavku po '30' sekundách."
503 Příliš mnoho požadavků "Počet souběžných požadavků '10' byl překročen pro prostředí '95880732-01b9-44ea-8d2d-4d764dfe1904'." EnvRequestLimitExceeded

Varování

Odpověď rozhraní API pro dotazy může obsahovat seznam upozornění jako "warnings" položku v kořenovém adresáři odpovědi HTTP nebo zprávy odpovědi protokolu WebSocket. V současné době jsou generována upozornění, pokud vlastnost není nalezena pro daný rozsah hledání, ale je nalezena v prostředí pro globální časové rozpětí. Generuje se také v případě, že je záhlaví x-ms-property-not-found-behavior nastaveno na UseNull hodnotu a odkazovaná vlastnost neexistuje ani v globálním rozsahu vyhledávání.

Každý varovný objekt může obsahovat následující pole:

Název pole Typ pole Poznámky
kód Řetězec Jeden z předdefinovaných varovných kódů
zpráva Řetězec Podrobná varovná zpráva
cílové Řetězec Cesta JSON oddělená tečkami k položce vstupní datové části JSON způsobuje upozornění
warningDetails slovníku Volitelný; Další podrobnosti upozornění (například pozice v řetězci predikátu)

Následující kód uvádí příklady upozornění pro predikát, řetězec predikátu v predikátu, dimenzi a míru:

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

Viz také

Další informace o registraci aplikace a programovacím modelu Azure Active Directory najdete v tématu Azure Active Directory pro vývojáře.

Další informace o parametrech požadavků a ověřování najdete v tématu Ověřování a autorizace.

Mezi nástroje, které pomáhají s testováním požadavků a odpovědí HTTP, patří:

  • Šumař. Tento bezplatný proxy server pro ladění webu dokáže zachytit vaše požadavky REST, takže můžete diagnostikovat zprávy požadavků a odpovědí HTTP.
  • JWT.io. Tento nástroj můžete použít k rychlému výpisu deklarací identity ve vašem nosném tokenu a následnému ověření jejich obsahu.
  • Pošťák. Jedná se o bezplatný nástroj pro testování požadavků a odpovědí HTTP pro ladění rozhraní REST API.

Další informace o Azure Time Series Insights Gen1 najdete v dokumentaci ke Gen1.

  • Last updated on