API de données de référence Azure Time Series Insights Gen1

Article
07/19/2023

Attention

Il s’agit d’un article Gen1.

Cet article décrit l’API de référence Gestion des données Azure Time Series Insights Gen1 utilisée pour gérer les éléments d’un jeu de données de référence. Il suppose que le jeu de données de référence a déjà été créé dans l’environnement.

Les données de référence incluent des données de fabricant ou d’emplacement qui changent rarement. Les données de référence sont utilisées pour contextualiser les données de télémétrie et servent à comparer les données de télémétrie.

Conseil

Pour créer un jeu de données de référence, consultez Création d’un jeu de données de référence.

Étant donné que les jeux de données sont préexistants et fixes, chaque paquet de données envoyé par un appareil contiendrait des informations identiques. Par conséquent, les données de référence ne sont pas envoyées à partir d’appareils et vous les gérez à l’aide de l’API de Gestion des données de référence ou de l’Portail Azure.

Présentation de l’API

L’API reference Gestion des données est une API de traitement par lots.

Important

Toutes les opérations sur cette API sont des opérations HTTP POST.
Chaque opération accepte des objets JSON comme charge utile de la requête.
Les objets JSON de requête HTTP définissent un nom de propriété unique qui spécifie l’opération à exécuter par l’API.

Les noms de propriétés d’opération de requête JSON valides sont les suivants :

Mettre
Patch
Supprimer des propriétés
Supprimer
Get

Important

La valeur de la propriété est un tableau d’éléments de données de référence sur lesquels l’opération doit être appliquée.
Chaque élément est traité individuellement, et une erreur avec un élément n’empêche pas l’écriture des autres éléments. Par exemple, si votre demande contient 100 éléments et qu’un élément a une erreur, 99 éléments sont écrits et un élément est rejeté.
Les éléments de données de référence sont interrogés à l’aide de leurs propriétés de clé entièrement énumérées.

Notes

Tous les exemples de corps JSON suivants supposent un jeu de données de référence avec une clé de propriété unique avec le nom deviceId et le type String.

Placer des éléments de données de référence

Insère ou remplace l’ensemble de l’élément $.put[i] de données de référence (le ^ième élément du tableau par la clé mise). L’unité de validation est L’opération $.put[i]. est idempotente.

Point de terminaison et opération :

POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12

Exemple de corps de la demande :

{
  "put": [{
    "deviceId": "Fan1",
    "color": "Red",
    "maxSpeed": 5
  },
  {
    "deviceId": "Fan2",
    "color": "White",
    "floor": 2
  }]
}

Exemple de réponse :
```
{
  "put": [
    null,
    null
  ]
}
```

Éléments de données de référence des correctifs

Mises à jour et insère des propriétés spécifiques pour l’élément $.patch[i]de données de référence .

Point de terminaison et opération :

POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12

Exemple de corps de la demande :

{
  "patch": [
    {
      "deviceId": "Fan1",
      "maxSpeed": 108
    },
    {
      "deviceId": "Fan2",
      "floor": 18
    }
  ]
}

Exemple de corps de réponse :

{
  "patch": [
    null,
    null
  ]
}

Supprimer des propriétés dans les éléments de données de référence

Supprime les propriétés spécifiées de l’élément $.deleteproperties[i]de données de référence .

Point de terminaison et opération :

POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12

Exemple de corps de la demande :

{
  "deleteProperties":[
    {
      "key":{
        "deviceId":"Fan2"
      },
      "properties":[
        "floor"
      ]
    }
  ]
}

Exemple de corps de réponse :

{
  "deleteProperties": [
    null
  ]
}

Supprimer des éléments de données de référence

Supprime l’élément de données de référence entier identifié par les valeurs de propriété de clé spécifiées dans chaque $.delete[i].

Point de terminaison et opération :

POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12

Exemple de corps de la demande :

{
  "delete": [{
    "deviceId": "Fan1"
  }]
}

Exemple de corps de réponse :
```
{
  "delete": [
    null
  ]
}
```

Obtenir des éléments de données de référence

Obtient l’élément de données de référence entier identifié par les valeurs de propriété de clé spécifiées dans chaque $.get[i].

Point de terminaison et opération :

POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12

Exemple de corps de la demande :

{
  "get": [{
    "deviceId": "Fan1"
  },
  {
    "deviceId": "Fan2"
  }]
}

Exemple de corps de réponse :

{
  "get": [
    {
      "code": "InvalidInput",
      "message": "Key not found.",
      "target": null,
      "details": null,
      "innerError": null
    },
    {
      "id": "Fan2",
      "floor": 18
    }
  ]
}

Validation et gestion des erreurs

L’API Reference Gestion des données traite chaque élément individuellement, et une erreur avec un élément n’empêche pas l’écriture des autres éléments. Par exemple, si votre demande contient 100 éléments et qu’un élément a une erreur, 99 éléments sont écrits et un élément est rejeté.

Codes d’erreur d’élément

Les codes d’erreur d’élément se produisent dans un corps de réponse JSON qui a le code http status 200.

InvalidInput : clé introuvable. : indique que l’élément interrogé est introuvable dans le jeu de données de référence.
```
{
  "code": "InvalidInput",
  "message": "Key not found.",
  "target": null,
  "details": null,
  "innerError": null
}
```
InvalidInput : la clé de charge utile ne doit pas contenir de propriété non clé. : indique que les éléments de requête du corps de la requête JSON ne doivent pas contenir de propriétés qui ne sont pas des propriétés de clé (c’est-à-dire des propriétés spécifiées dans le schéma du jeu de références). Les propriétés de clé se trouvent dans le Portail Azure.
```
{
  "code": "InvalidInput",
  "message": "Payload key should not contain any non-key property.",
  "target": null,
  "details": null,
  "innerError": null
}
```
InvalidInput : l’élément de charge utile doit contenir toutes les propriétés de clé. : indique que les éléments de requête du corps de la requête JSON doivent inclure toutes les propriétés de clé (c’est-à-dire les propriétés spécifiées dans le schéma du jeu de références). Les propriétés de clé se trouvent dans Portail Azure.
```
{
  "code": "InvalidInput",
  "message": "Payload item should contain all key properties.",
  "target": null,
  "details": null,
  "innerError": null
}
```

Exemple de jointure de données de référence

Prenons l’exemple d’un message event hub qui a la structure suivante :

[
  {
    "deviceId":"Fan1",
    "timestamp":"1/5/2015T00:10:30Z"
  },
  {
    "deviceId":"Fan2",
    "timestamp":"1/5/2015T00:10:30Z"
  }
]

Prenons l’exemple d’un élément de données de référence qui est défini avec le nom contoso et la clé deviceId de type String et qui a la structure suivante :

deviceId	couleur	Maxspeed	floor
Fan1	Rouge	5
Fan2	White		2

Lorsque les deux événements du message du hub d’événements sont traités par Azure Time Series Insights moteur d’entrée Gen1, ils sont joints à l’élément de données de référence approprié. La sortie des événements a la structure suivante :

[
  {
    "deviceId":"Fan1",
    "timestamp":"1/5/2015T00:10:30Z",
    "color":"Red",
    "maxSpeed":5
  },
  {
    "deviceId":"Fan2",
    "timestamp":"1/5/2015T00:10:30Z",
    "color":"White",
    "floor":2
  }
]

Règles de jointure et sémantique

Lorsque vous joignez des données de référence, respectez les contraintes suivantes :

La comparaison des noms de clé respecte la casse.
La comparaison des valeurs de clé respecte la casse pour les propriétés de chaîne.

Pour les environnements avec plusieurs jeux de données de référence, trois contraintes supplémentaires sont appliquées lors des jointures :

Chaque élément d’un jeu de données de référence peut spécifier sa propre liste de propriétés non clés.
Pour les deux jeux de données de référence A et B, les propriétés non clés ne doivent pas se croiser.
Les jeux de données de référence sont joints directement aux événements, jamais aux autres jeux de données référencés (puis aux événements). Pour joindre un élément de données de référence à un événement, toutes les propriétés de clé utilisées dans l’élément de données de référence doivent être présentes dans l’événement. En outre, les propriétés de clé ne doivent pas provenir des propriétés non clés qui sont jointes à un événement par le biais d’un autre élément de données de référence.

Compte tenu de ces contraintes, le moteur de jointure peut appliquer la jointure dans n’importe quel ordre pour un événement donné. La hiérarchie et le classement ne sont pas pris en compte.

Limites actuelles

Vous pouvez ajouter jusqu’à deux jeux de données de référence par Azure Time Series Insights environnement Gen1. Les limitations supplémentaires associées aux données de référence Azure Time Series Insights Gen1 sont répertoriées dans le tableau suivant :

Nom de la limite	Valeur de limite	Références SKU affectées	Notes
Nombre de propriétés de clé	3	S1, S2	Par jeu de données de référence ; Azure Resource Manager et le Portail Azure uniquement
Taille de la propriété de clé	1 Ko	S1, S2	Par jeu de données de référence
Nombre d’éléments de données de référence	2 000/20 000 (S1/S2)	S1, S2	Par unité; par exemple, 4 unités de référence S1 = 8 000 éléments (4 x 2 000)
Nombre maximal de transactions simultanées	2/10 (S1/S2)	S1, S2
Nombre maximal de transactions de données de référence	120/600 (S1/S2)	S1, S2	À l’heure
Nombre maximal d’éléments de données de référence	1 000	S1, S2	par transaction
Taille maximale des éléments de données de référence	8 192 Ko	S1, S2	par transaction

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 requête et d’authentification, consultez Authentification et autorisation.

Les outils qui 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.

Partager via

API de données de référence Azure Time Series Insights Gen1

Présentation de l’API

Placer des éléments de données de référence

Éléments de données de référence des correctifs

Supprimer des propriétés dans les éléments de données de référence

Supprimer des éléments de données de référence

Obtenir des éléments de données de référence

Validation et gestion des erreurs

Codes d’erreur d’élément

Exemple de jointure de données de référence

Règles de jointure et sémantique

Limites actuelles

Voir aussi

Ressources supplémentaires