API de requête Azure Time Series Insights Gen1

Cet article décrit différentes API de requête REST. Les API REST sont des points de terminaison de service qui prennent en charge des ensembles d’opérations HTTP (méthodes), qui vous permettent d’interroger Azure Time Series Insights environnements Gen1.

API Obtenir des environnements

L’API Get Environments retourne la liste des environnements auxquels l’appelant est autorisé à accéder.

• Point de terminaison et opération :

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

• Exemple de corps de demande : Non applicable

• Exemple de corps de réponse :

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

  Notes

  L’environnement de propriété de réponseFqdn est un nom de domaine complet unique pour l’environnement utilisé dans les demandes d’API de requête par environnement.

API Get Environment Availability

L’API Get Environment Availability retourne la distribution du nombre d’événements sur l’horodatage d’événement $ts. La disponibilité de l’environnement est mise en cache et le temps de réponse ne dépend pas du nombre d’événements dans un environnement.

• Point de terminaison et opération :

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

• Exemple de corps de demande : Non applicable

• Exemple de corps de réponse :

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

  Un objet vide est retourné pour les environnements sans événement.

Obtenir l’API de métadonnées d’environnement

L’API Get Environment Metadata retourne les métadonnées d’environnement pour une étendue de recherche donnée. Les métadonnées sont retournées sous la forme d’un ensemble de références de propriété. Azure Time Series Insights Gen1 met en cache et approximativement les métadonnées en interne, et peut retourner d’autres propriétés présentes dans les événements exacts de l’étendue de recherche.

• Point de terminaison et opération :

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

• Structure de charge utile d’entrée :

  • Clause d’étendue de recherche (obligatoire)

• Exemple de corps de requête :

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

• Exemple de corps de réponse :

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

  Un tableau vide properties est retourné lorsque l’environnement est vide ou qu’il n’y a aucun événement dans une étendue de recherche.

  Les propriétés intégrées ne sont pas retournées dans la liste des propriétés.

Get Environment Events API

L’API Get Environment Events retourne une liste d’événements bruts qui correspondent à l’étendue de recherche et au prédicat.

• Point de terminaison et opération :

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

• Structure de charge utile d’entrée :

  • Clause d’étendue de recherche (obligatoire)
  • Clause de prédicat (facultatif)
  • Clause limit (obligatoire)

• Exemple de corps de requête :

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

  Notes

  • Le tri imbriqué (c’est-à-dire le tri par deux propriétés ou plus) n’est actuellement pas pris en charge.
  • Les événements peuvent être triés et limités au sommet.
  • Le tri est pris en charge sur tous les types de propriétés. Le tri s’appuie sur des opérateurs de comparaison définis pour les expressions booléennes.

• Exemple de corps de réponse :

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

API Get Environment Events Streamed

L’API Get Environment Events Streamed retourne une liste d’événements bruts qui correspondent à l’étendue de recherche et au prédicat.

Cette API utilise le protocole sécurisé WebSocket pour effectuer la diffusion en continu et retourner des résultats partiels. Il retourne toujours des événements supplémentaires. Autrement dit, le nouveau message est additif au précédent. Le nouveau message contient de nouveaux événements qui ne se trouvaient pas dans le message précédent. Le message précédent doit être conservé lorsque le nouveau message est ajouté.

• Point de terminaison et opération :

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

• Structure de charge utile d’entrée :

  • Clause d’étendue de recherche (obligatoire)
  • Clause de prédicat (facultatif)
  • Clause limit (obligatoire)

• Exemple de message de demande :

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

  Notes

  • Le tri imbriqué (c’est-à-dire le tri par deux propriétés ou plus) n’est actuellement pas pris en charge.
  • Les événements peuvent être triés et limités au sommet.
  • Le tri est pris en charge sur tous les types de propriétés. Le tri s’appuie sur des opérateurs de comparaison définis pour les expressions booléennes.

• Exemple de message de réponse :

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

API Get Environment Aggregates

L’API Get Environment Aggregates regroupe les événements d’une propriété spécifiée, car elle mesure éventuellement les valeurs d’autres propriétés.

• Point de terminaison et opération :

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

• Structure de charge utile d’entrée :

  • Clause d’étendue de recherche (obligatoire)
  • Clause de prédicat (facultatif)
  • Clause Agrégats (obligatoire)

• Exemple de corps de requête :

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

• Exemple de corps de réponse :

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

  Si aucune expression de mesure n’est spécifiée et que la liste des événements est vide, la réponse est vide.

  Si des mesures sont présentes, la réponse contient un enregistrement unique avec une null valeur de dimension, une 0 valeur pour le nombre et une null valeur pour d’autres types de mesures.

API Get Environment Aggregates Streamed

L’API Get Environment Aggregates Streamed regroupe les événements par une propriété spécifiée, car elle mesure éventuellement les valeurs d’autres propriétés :

• Cette API utilise le protocole sécurisé WebSocket pour la diffusion en continu et pour retourner des résultats partiels.
• Il retourne toujours un remplacement (instantané) de toutes les valeurs.
• Les paquets précédents peuvent être ignorés par le client.

• Point de terminaison et opération :

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

• Structure de charge utile d’entrée :

  • Clause d’étendue de recherche (obligatoire)
  • Clause de prédicat (facultatif)
  • Clause Agrégats (obligatoire)

• Exemple de message de demande :

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

• Exemples de messages de réponse :

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

  Si aucune expression de mesure n’est spécifiée et que la liste des événements est vide, la réponse est vide.

  Si des mesures sont présentes, la réponse contient un enregistrement unique avec une null valeur de dimension, une 0 valeur pour le nombre et une null valeur pour d’autres types de mesures.

limites

Les limites suivantes sont appliquées lors de l’exécution de la requête pour utiliser équitablement les ressources entre plusieurs environnements et utilisateurs :

Gestion et résolution des erreurs

Comportement de propriété introuvable

Pour les propriétés référencées dans la requête, soit dans le cadre de prédicats, soit dans le cadre d’agrégats (mesures), par défaut, la requête tente de résoudre la propriété dans l’étendue recherche globale de l’environnement. Si la propriété est trouvée, la requête réussit. Si la propriété est introuvable, la requête échoue.

Toutefois, vous pouvez modifier ce comportement pour traiter les propriétés comme existantes, mais avec null des valeurs si elles ne sont pas présentes dans l’environnement. Pour ce faire, définissez l’en-tête x-ms-property-not-found-behavior de demande facultatif avec la valeur UseNull.

Les valeurs possibles pour l’en-tête de requête sont UseNull ou ThrowError (valeur par défaut). Lorsque vous définissez UseNull comme valeur, la requête réussit même si les propriétés n’existent pas, et la réponse contient des avertissements qui affichent les propriétés introuvables.

Signaler les propriétés non résolues

Vous pouvez spécifier des références de propriété pour les expressions de prédicat, de dimension et de mesure. Si une propriété avec un nom et un type spécifiques n’existe pas pour une étendue de recherche spécifiée, une tentative est effectuée pour résoudre une propriété sur un intervalle de temps global.

Selon la réussite de la résolution, l’avertissement ou l’erreur suivant peut être émis :

• Si une propriété existe dans l’environnement sur un intervalle de temps global, elle est résolue de manière appropriée et un avertissement est émis pour vous avertir que la valeur de cette propriété est null pour une étendue de recherche donnée.
• Si aucune propriété n’existe dans l’environnement, une erreur est émise et l’exécution de la requête échoue.

Réponses d’erreur

Si l’exécution de la requête échoue, la charge utile de réponse JSON contient une réponse d’erreur avec la structure suivante :

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

Ici, innerError est facultatif. En plus des erreurs de base, telles qu’une requête incorrecte, les erreurs suivantes sont retournées :

Avertissements

Une réponse d’API de requête peut contenir une liste d’avertissements sous "warnings" la racine de la réponse HTTP ou du message de réponse WebSocket. Actuellement, des avertissements sont générés si la propriété est introuvable pour une étendue de recherche donnée, mais qu’elle se trouve dans un environnement pour l’intervalle de temps global. Elle est également générée lorsque l’en-tête x-ms-property-not-found-behavior est défini UseNull sur et qu’une propriété référencée n’existe pas même dans l’étendue recherche globale.

Chaque objet d’avertissement peut contenir les champs suivants :

Le code suivant présente des exemples d’avertissements pour le prédicat, la chaîne de prédicat dans le prédicat, la dimension et la mesure :

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

Voir aussi

Pour plus d’informations sur l’inscription des applications et le modèle de programmation Azure Active Directory, consultez Azure Active Directory pour les développeurs.

Pour en savoir plus sur les paramètres de demande et d’authentification, consultez Authentification et autorisation.

Les outils qui vous aident à tester les requêtes et réponses HTTP sont les suivants :

• Fiddler. Ce proxy de débogage web gratuit peut intercepter vos requêtes REST, ce qui vous permet de diagnostiquer les messages de requête et de réponse HTTP.
• JWT.io. Vous pouvez utiliser cet outil pour vider rapidement les revendications dans votre jeton du porteur, puis valider leur contenu.
• Postman. Il s’agit d’un outil de test de requête et de réponse HTTP gratuit pour le débogage des API REST.

Pour en savoir plus sur Azure Time Series Insights Gen1, consultez la documentation gen1.