Ajouter des objets blob à des objets dans Azure Digital Twins

Article
01/10/2020

Important

Une nouvelle version du service Azure Digital Twins a été publiée. Compte tenu des fonctionnalités étendues du nouveau service, le service Azure Digital Twins d’origine (décrit dans cet ensemble de documentation) a été mis hors service.

Pour afficher la documentation du nouveau service, consultez la documentation active d’Azure Digital Twins.

Les objets blob sont des représentations non structurées de types de fichier courants, comme les images et les journaux d’activité. Les blobs assurent le suivi du type de données qu’ils représentent à l’aide d’un type MIME (par exemple : « image/jpeg ») et de métadonnées (nom, description, type, etc.).

Azure Digital Twins prend en charge l’attachement d’objets blob à des appareils, des espaces et des utilisateurs. Les blobs peuvent représenter une image de profil pour un utilisateur, une photo de l’appareil, une vidéo, une carte, un zip de microprogramme, des données JSON, un journal, etc.

Cet article suppose une certaine familiarité avec l'authentification auprès de vos API de gestion Azure Digital Twins.

Pour en savoir plus sur l'authentification auprès de vos API de gestion, consultez S'authentifier auprès des API Azure Digital Twins.
Pour vous authentifier auprès de vos API de gestion à l'aide du client Postman REST, consultez Comment configurer Postman.

Vue d’ensemble du chargement d’objets blob

Vous pouvez utiliser des demandes en plusieurs parties pour charger des objets blob vers des points de terminaison spécifiques et leurs fonctionnalités respectives.

Remarque

Les demandes en plusieurs parties nécessitent généralement trois éléments :

En-tête Content-Type :
- application/json; charset=utf-8
- multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
Une disposition de contenu :
- form-data; name="metadata"
Le contenu du fichier à charger

L’en-tête Content-Type et l’élément Content-Disposition varient en fonction du scénario d’utilisation.

Des demandes en plusieurs parties peuvent être effectuées par programme (via C#), à l’aide d’un client REST ou d’un outil tel que Postman. Les outils clients REST peuvent avoir différents niveaux de support pour les demandes en plusieurs parties complexes. Les paramètres de configuration peuvent aussi légèrement varier d'un outil à un autre. Vérifiez quel outil est le mieux adapté à vos besoins.

Important

Les demandes en plusieurs parties faites aux API de gestion Azure Digital Twins comprennent généralement deux parties :

Des métadonnées blob (par exemple, un type MIME associé) déclarées par l’en-tête Content-Type et/ou l’élément Content-Disposition
Du contenu d’objet blob incluant le contenu non structuré d’un fichier à charger

Aucune des deux parties n’est obligatoire pour les demandes PATCH. Les deux sont requises pour POST ou pour créer des opérations.

Le code source de démarrage rapide d’Occupation contient des exemples en C# complets, montrant comment adresser des demandes en plusieurs parties aux API de gestion Azure Digital Twins.

Métadonnées d'objet blob

En plus de Content-Type et Content-Disposition, les demandes en plusieurs parties Azure Digital Twins doivent également spécifier le corps JSON approprié. Le corps JSON à envoyer varie selon le type d’opération de requête HTTP effectuée.

Les quatre principaux schémas JSON sont :

Les métadonnées d’objets blob JSON sont conformes au modèle suivant :

{
    "parentId": "00000000-0000-0000-0000-000000000000",
    "name": "My First Blob",
    "type": "Map",
    "subtype": "GenericMap",
    "description": "A well chosen description",
    "sharing": "None"
  }

Attribut	Type	Description
parentId	Chaîne	Entité parente avec laquelle associer l’objet blob (espaces, appareils ou utilisateurs)
nom	Chaîne	Nom convivial pour l’objet blob
type	Chaîne	Type d’objet blob. Vous ne pouvez pas utiliser type et typeId
typeId	Integer	ID de type d’objet blob. Vous ne pouvez pas utiliser type et typeId
subtype	Chaîne	Sous-type d’objet blob. Vous ne pouvez pas utiliser subtype et subtypeId
subtypeId	Integer	ID de sous-type d’objet blob. Vous ne pouvez pas utiliser subtype et subtypeId
description	Chaîne	Description personnalisée de l’objet blob
sharing	Chaîne	Indique si l’objet blob peut être partagé - enum [`None`, `Tree`, `Global`]

Les métadonnées de blobs sont toujours fournies en tant que premier bloc avec Content-Type application/json ou en tant que fichier .json. Les données de fichiers sont fournies dans le deuxième segment et peuvent être de n’importe quel type MIME pris en charge.

La documentation Swagger décrit en détail ces schémas de modèle.

Conseil

Vous pouvez obtenir un premier aperçu de Swagger qui illustre le jeu de fonctionnalités de l’API. Pour ce faire, rendez-vous à l’adresse docs.westcentralus.azuresmartspaces.net/management/swagger.

Vous pouvez accéder à votre propre documentation Swagger générée pour l’API Gestion à l’adresse suivante :

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger

Nom	Replace with
YOUR_INSTANCE_NAME	Nom de votre instance Azure Digital Twins
YOUR_LOCATION	Région de serveur dans laquelle votre instance est hébergée

Découvrez plus d’informations sur l’utilisation de la documentation de référence en lisant Comment utiliser Swagger.

Données de réponse d’objets blob

Les objets blob retournés individuellement sont conformes au schéma JSON suivant :

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "string",
  "parentId": "00000000-0000-0000-0000-000000000000",
  "type": "string",
  "subtype": "string",
  "typeId": 0,
  "subtypeId": 0,
  "sharing": "None",
  "description": "string",
  "contentInfos": [
    {
      "type": "string",
      "sizeBytes": 0,
      "mD5": "string",
      "version": "string",
      "lastModifiedUtc": "2019-01-12T00:58:08.689Z",
      "metadata": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      }
    }
  ],
  "fullName": "string",
  "spacePaths": [
    "string"
  ]
}

Attribut	Type	Description
id	Chaîne	Identificateur unique de l’objet blob
nom	Chaîne	Nom convivial pour l’objet blob
parentId	Chaîne	Entité parente avec laquelle associer l’objet blob (espaces, appareils ou utilisateurs)
type	Chaîne	Type d’objet blob. Vous ne pouvez pas utiliser type et typeId
typeId	Integer	ID de type d’objet blob. Vous ne pouvez pas utiliser type et typeId
subtype	Chaîne	Sous-type d’objet blob. Vous ne pouvez pas utiliser subtype et subtypeId
subtypeId	Integer	ID de sous-type d’objet blob. Vous ne pouvez pas utiliser subtype et subtypeId
sharing	Chaîne	Indique si l’objet blob peut être partagé - enum [`None`, `Tree`, `Global`]
description	Chaîne	Description personnalisée de l’objet blob
contentInfos	Tableau	Spécifie les informations de métadonnées non structurées, notamment la version
fullName	Chaîne	Nom complet de l’objet blob
spacePaths	Chaîne	Chemin de l’espace

Exemples de requête multipart d’objet blob

Dans les exemples ci-dessous, YOUR_MANAGEMENT_API_URL fait référence à l’URI des API Digital Twins :

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0

Nom	Replace with
YOUR_INSTANCE_NAME	Nom de votre instance Azure Digital Twins
YOUR_LOCATION	Région dans laquelle votre instance est hébergée

Pour charger un fichier texte sous forme de blob et l’associer à un espace, envoyez une requête HTTP POST authentifiée à :

YOUR_MANAGEMENT_API_URL/spaces/blobs

Avec le corps suivant :

--USER_DEFINED_BOUNDARY
Content-Type: application/json; charset=utf-8
Content-Disposition: form-data; name="metadata"

{
  "ParentId": "54213cf5-285f-e611-80c3-000d3a320e1e",
  "Name": "My First Blob",
  "Type": "Map",
  "SubType": "GenericMap",
  "Description": "A well chosen description",
  "Sharing": "None"
}
--USER_DEFINED_BOUNDARY
Content-Disposition: form-data; name="contents"; filename="myblob.txt"
Content-Type: text/plain

This is my blob content. In this case, some text, but I could also be uploading a picture, an JSON file, a firmware zip, etc.

--USER_DEFINED_BOUNDARY--

Valeur	Replace with
USER_DEFINED_BOUNDARY	Nom de la limite de contenu en plusieurs parties

Le code suivant est une implémentation .NET du même chargement d’objet blob mais en utilisant la classe MultipartFormDataContent :

//Supply your metadata in a suitable format
var multipartContent = new MultipartFormDataContent("USER_DEFINED_BOUNDARY");

var metadataContent = new StringContent(JsonConvert.SerializeObject(metaData), Encoding.UTF8, "application/json");
metadataContent.Headers.ContentType = MediaTypeHeaderValue.Parse("application/json; charset=utf-8");
multipartContent.Add(metadataContent, "metadata");

//MY_BLOB.txt is the String representation of your text file
var fileContents = new StringContent("MY_BLOB.txt");
fileContents.Headers.ContentType = MediaTypeHeaderValue.Parse("text/plain");
multipartContent.Add(fileContents, "contents");

var response = await httpClient.PostAsync("spaces/blobs", multipartContent);

Pour finir, les utilisateurs cURL peuvent effectuer des requêtes de formulaire multipart de la même manière :

curl -X POST "YOUR_MANAGEMENT_API_URL/spaces/blobs" \
 -H "Authorization: Bearer YOUR_TOKEN" \
 -H "Accept: application/json" \
 -H "Content-Type: multipart/form-data" \
 -F "meta={\"ParentId\":\"YOUR_SPACE_ID\",\"Name\":\"My CURL Blob\",\"Type\":\"Map\",\"SubType\":\"GenericMap\",\"Description\":\"A well chosen description\",\"Sharing\":\"None\"};type=application/json" \
 -F "text=PATH_TO_FILE;type=text/plain"

Valeur	Replace with
YOUR_TOKEN	Votre jeton OAuth 2.0 valide
YOUR_SPACE_ID	ID de l’espace avec lequel associer l’objet blob
PATH_TO_FILE	Chemin de votre fichier texte

Une requête POST ayant réussi retourne l’ID du nouvel objet blob.

Points de terminaison d’API

Les sections suivantes décrivent les points de terminaison d’API principaux liés à l’objet blob et leurs fonctionnalités.

Appareils

Vous pouvez attacher des objets blob à des appareils. L’illustration suivante montre la documentation de référence Swagger pour vos API de gestion. Elle spécifie les points de terminaison d’API associés à l’appareil pour la consommation d’objets blob et tous les paramètres de chemin obligatoires à leur passer.

Par exemple, pour mettre à jour ou créer un blob, et l’attacher à un appareil, envoyez une requête HTTP PATCH authentifiée à :

YOUR_MANAGEMENT_API_URL/devices/blobs/YOUR_BLOB_ID

Paramètre	Replace with
YOUR_BLOB_ID	ID d’objet blob souhaité

Les requêtes ayant réussi retournent un objet JSON comme décrit précédemment.

Espaces

Vous pouvez également attacher des objets blob à des espaces. L’image suivante liste tous les points de terminaison d’API d’espace responsables du traitement des objets blob. Elle liste également tous les paramètres de chemin à passer à ces points de terminaison.

Par exemple, pour retourner un blob attaché à un espace, envoyez une requête HTTP GET authentifiée à :

YOUR_MANAGEMENT_API_URL/spaces/blobs/YOUR_BLOB_ID

Paramètre	Replace with
YOUR_BLOB_ID	ID d’objet blob souhaité

Les requêtes ayant réussi retournent un objet JSON comme décrit précédemment.

Une requête PATCH au même point de terminaison met à jour la description des métadonnées et crée des versions de l’objet blob. La requête HTTP est envoyée à l’aide de la méthode PATCH ainsi que des métadonnées et des données de formulaire en plusieurs parties nécessaires.

Utilisateurs

Vous pouvez attacher des objets blob aux modèles utilisateur (par exemple, pour associer une image de profil). L’image suivante montre les points de terminaison pertinents de l’API utilisateur et les paramètres de chemin nécessaires, comme id :

Par exemple, pour extraire un blob attaché à un utilisateur, envoyez une requête HTTP GET authentifiée avec les données de formulaire nécessaires à :

YOUR_MANAGEMENT_API_URL/users/blobs/YOUR_BLOB_ID

Paramètre	Replace with
YOUR_BLOB_ID	ID d’objet blob souhaité

Les requêtes ayant réussi retournent un objet JSON comme décrit précédemment.

Erreurs courantes

Une erreur courante consiste à ne pas fournir les informations d’en-tête correctes :
```
{
    "error": {
        "code": "400.600.000.000",
        "message": "Invalid media type in first section."
    }
}
```
Pour résoudre cette erreur, vérifiez que la requête entière a un en-tête Content-Type approprié :
- multipart/mixed
- multipart/form-data
Vérifiez également que chaque bloc en plusieurs parties a un Content-Type correspondant approprié.
Une deuxième erreur courante survient lorsque plusieurs blobs sont assignés à la même ressource dans votre graphique d’intelligence spatiale :
```
{
    "error": {
        "code": "400.600.000.000",
        "message": "SpaceBlobMetadata already exists."
    }
}
```
Remarque

L’attribut message varie en fonction de la ressource.

Un seul blob (de chaque type) peut être attaché à chaque ressource dans votre graphique spatial.

Pour résoudre cette erreur, mettez à jour le blob existant à l’aide de l’opération API HTTP PATCH appropriée. Cela remplacera les données blob existantes par les données souhaitées.

Étapes suivantes

Pour en savoir plus sur la documentation de référence Swagger pour Azure Digital Twins, lisez Utiliser Azure Digital Twins Swagger.
Pour découvrir comment charger des objets blob par le biais de Postman, consultez Guide pratique pour configurer Postman.

Partager via

Ajouter des objets blob à des objets dans Azure Digital Twins

Vue d’ensemble du chargement d’objets blob

Métadonnées d'objet blob

Données de réponse d’objets blob

Exemples de requête multipart d’objet blob

Points de terminaison d’API

Appareils

Espaces

Utilisateurs

Erreurs courantes

Étapes suivantes

Ressources supplémentaires