Comment créer un registre de données

Article
06/14/2023

Le service de registre de données vous permet d’inscrire du contenu de données dans un compte de stockage Azure avec votre compte Azure Maps. Les données peuvent se présenter sous forme de collection de limites géographiques utilisée dans le service Azure Maps Geofencing. Ce peut être aussi des fichiers ZIP contenant des packages de dessin (DWG), ou des fichiers GeoJSON utilisés par Azure Maps Creator pour créer ou mettre à jour des cartes d’intérieur.

Prérequis

Important

Cet article utilise l’URL géographique us.atlas.microsoft.com. Si votre compte n’a pas été créé aux États-Unis, vous devez utiliser une autre URL géographique. Pour plus d’informations, consultez Accès aux services Creator.
Dans les exemples d’URL de cet article, vous devez remplacer :
- {Azure-Maps-Subscription-key} avec votre clé d’abonnement Azure Maps.
- {udid} avec l’ID de données utilisateur de votre registre de données. Pour plus d’informations, consultez ID de données utilisateur.

Préparer l’inscription des données dans Azure Maps

Avant de pouvoir inscrire des données dans Azure Maps, vous devez créer un environnement contenant tous les composants nécessaires. Vous avez besoin d’un compte de stockage avec un ou plusieurs conteneurs pour les fichiers que vous souhaitez inscrire, et des identités managées pour l’authentification. Cette section explique comment préparer votre environnement Azure pour inscrire des données dans Azure Maps.

Créer des identités managées

Il existe deux types d’identités managées : celles qui sont affectées par le système et celles qui sont affectées par l’utilisateur. Le cycle de vie des identités managées affectées par le système est lié à la ressource qui les a créées. Les identités managées affectées par l’utilisateur peuvent être utilisées sur plusieurs ressources. Pour plus d’informations, consultez Identités managées pour les ressources Azure.

Utilisez les étapes suivantes pour créer une identité managée et l’ajouter à votre compte Azure Maps.

affectée par le système
affectée par l’utilisateur

Créer une identité managée affectée par le système :

Accédez à votre compte Azure Maps dans le portail Azure.
Dans le volet gauche, sélectionnez Identité.
Basculez l’Étatsur Activé.

Pour plus d’informations, consultez Identités managées pour les ressources Azure.

Créer un conteneur et charger des fichiers de données

Avant d’ajouter des fichiers à un registre de données, vous devez les charger dans un conteneur de votre compte de stockage Azure. Les conteneurs sont comme les répertoires d’un système de fichiers : ils organisent les fichiers dans votre compte de stockage Azure.

Pour créer un conteneur dans le portail Azure, procédez comme suit :

Dans votre compte de stockage Azure, sélectionnez Conteneurs dans la section Stockage des données du volet de navigation.
Sélectionnez + Conteneur dans le volet Conteneurs pour afficher le volet Nouveau conteneur.
Sélectionnez Créer pour créer le conteneur.

Une fois votre conteneur créé, vous pouvez y charger des fichiers.
Dès que le conteneur est créé, sélectionnez-le.
Sélectionnez Charger dans la barre d’outils, sélectionnez un ou plusieurs fichiers
Cliquez sur le bouton Charger.

Ajouter un magasin de données

Une fois que vous avez créé un compte de stockage Azure avec des fichiers chargés dans un ou plusieurs conteneurs, vous êtes prêt à créer le magasin de données qui relie les comptes de stockage à votre compte Azure Maps.

Important

Tous les comptes de stockage liés à un compte Azure Maps doivent se trouver dans la même localisation géographique. Pour plus d’informations, consultez Étendue géographique du service Azure Maps.

Notes

Si vous n’avez pas encore de compte de stockage, consultez Créer un compte de stockage.

Sélectionnez Magasin de données dans le menu de gauche de votre compte Azure Maps.
Sélectionnez le bouton Ajouter. Un écran Ajouter un magasin de données s’affiche à droite.
Entrez l’ID de magasin de données souhaité, puis sélectionnez le Nom de l’abonnement et le Compte de stockage dans les listes déroulantes.
Sélectionnez Ajouter.

Le nouveau magasin de données s’affiche désormais dans la liste des magasins de données.

Attribuer des rôles à des identités managées et les ajouter au magasin de données

Une fois vos identités managées et votre magasin de données créés, vous pouvez ajouter les identités managées au magasin de données et leur attribuer simultanément les rôles Contributeur et Lecteur de données blob de stockage. Même si vous pouvez ajouter des rôles à vos identités managées directement dans vos identités managées ou votre compte de stockage, vous pouvez facilement le faire quand vous les associez à votre magasin de données Azure Maps directement dans le volet du magasin de données.

Notes

Chaque identité managée associée au magasin de données a besoin des rôles Contributeur et Lecteur de données blob de stockage. Si vous n’avez pas les autorisations nécessaires pour accorder des rôles aux identités managées, consultez votre administrateur Azure. Pour attribuer des rôles à vos identités managées et les associer à un magasin de données :

Sélectionnez Magasin de données dans le menu de gauche de votre compte Azure Maps.
Sélectionnez un ou plusieurs magasins de données dans la liste, puis Attribuer des rôles.
Sélectionnez l’Identité managée à associer aux magasins de données sélectionnés dans la liste déroulante.
Sélectionnez Contributeur et Lecteur de données blob de stockage dans la liste déroulante Rôles à attribuer.
Sélectionnez le bouton Attribuer.

Propriétés du registre de données

Dès que vous avez un magasin de données créé dans votre compte Azure Maps, vous êtes prêt à collecter les propriétés nécessaires pour créer le registre de données.

Vous avez les propriétés AzureBlob que vous passez dans le corps de la requête HTTP et l’ID de données utilisateur que vous passez dans l’URL.

AzureBlob

AzureBlob est un objet JSON qui définit les propriétés nécessaires pour créer le registre de données.

Propriété	Description
`kind`	Définit le type d’objet inscrit. Actuellement AzureBlob est le seul type pris en charge.
`dataFormat`	Format de données du fichier situé dans blobUrl. Son format peut être GeoJSON pour le service spatial ou ZIP pour le service de conversion.
`msiClientId`	ID de l’identité managée utilisée pour créer le registre de données.
`linkedResource`	ID du magasin de données inscrit dans le compte Azure Maps. Le magasin de données contient un lien vers le fichier que vous inscrivez.
`blobUrl`	URL pointant vers l’emplacement d’AzurebBlob, le fichier importé dans votre conteneur.

Les deux sections suivantes vous expliquent comment obtenir les valeurs à utiliser pour les propriétés msiClientId, blobUrl.

Propriété msiClientId

La propriété msiClientId est l’ID de l’identité managée utilisée pour créer le registre de données. Il existe deux types d’identités managées : celles qui sont affectées par le système et celles qui sont affectées par l’utilisateur. Le cycle de vie des identités managées affectées par le système est lié à la ressource qui les a créées. Les identités managées affectées par l’utilisateur peuvent être utilisées sur plusieurs ressources. Pour plus d’informations, consultez Identités managées pour les ressources Azure.

affectée par le système
affectée par l’utilisateur

Quand vous utilisez des identités managées affectées par le système, vous n’avez pas besoin de fournir une valeur pour la propriété msiClientId. Le service de registre de données utilise automatiquement l’identité affectée par le système du compte Azure Maps quand msiClientId a la valeur null.

Propriété blobUrl

La propriété blobUrl est le chemin du fichier que vous inscrivez. Vous pouvez obtenir cette valeur à partir du conteneur auquel il a été ajouté. Registre de données

Sélectionnez votre compte de stockage dans le portail Azure.
Sélectionnez Conteneurs dans le menu de gauche.
Une liste de conteneurs s’affiche. Sélectionnez le conteneur qui contient le fichier que vous souhaitez inscrire.
Le conteneur s’ouvre, affichant la liste des fichiers précédemment chargés.
Sélectionnez le fichier souhaité, puis copiez l’URL.

ID de données utilisateur

L’ID de données utilisateur (udid) du registre de données est un GUID défini par l’utilisateur qui doit être conforme au modèle Regex suivant :

^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$

Conseil

udid est un GUID défini par l’utilisateur qui doit être fourni pendant la création d’un registre de données. Si vous voulez être certain que vous disposez d’un identificateur global unique (GUID), créez-le en exécutant un outil de génération de GUID tel que le programme en ligne de commande Guidgen.exe (disponible avec Visual Studio).

Créer un registre de données

Maintenant que vous avez votre compte de stockage avec les fichiers souhaités liés à votre compte Azure Maps via le magasin de données et que vous avez collecté toutes les propriétés nécessaires, vous êtes prêt à utiliser l’API Registre de données pour inscrire ces fichiers. Si vous souhaitez inscrire plusieurs fichiers dans votre compte de stockage Azure, vous devez exécuter la demande d’inscription pour chaque fichier (udid).

Notes

La taille maximale d’un fichier pouvant être inscrit dans un magasin de données Azure Maps est d’un gigaoctet.

Pour créer un registre de données :

affectée par le système
affectée par l’utilisateur

Fournissez les informations nécessaires pour référencer le compte de stockage ajouté au registre de données dans le corps de votre requête HTTP. Les informations doivent être au format JSON et contenir les champs suivants :
```
{
"kind": "AzureBlob",
    "azureBlob": {
        "dataFormat": "geojson",
        "linkedResource": "{datastore ID}",
        "blobUrl": "https://teststorageaccount.blob.core.windows.net/testcontainer/test.geojson"
    }
}
```
Notes

Lors de l'utilisation d'identités managées attribuées par le système, vous obtiendrez une erreur si vous fournissez une valeur pour la propriété msiClientId dans votre requête HTTP.

Pour plus d’informations sur les propriétés nécessaires dans le corps de la requête HTTP, consultez Propriétés du registre de données.
Une fois le corps de votre requête HTTP prêt, exécutez la requête HTTP PUT suivante :
```
https://us.atlas.microsoft.com/dataRegistries/{udid}?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key} 
```
Pour plus d’informations sur la propriété udid, consultez ID de données utilisateur.
Copiez la valeur de la clé Emplacement à partir de l’en-tête de réponse.

Fournissez les informations nécessaires pour référencer le compte de stockage ajouté au registre de données dans le corps de votre requête HTTP. Les informations doivent être au format JSON et contenir les champs suivants :
```
{
"kind": "AzureBlob",
    "azureBlob": {
        "dataFormat": "geojson",
        "msiClientId": "{The client ID of the managed identity}",
        "linkedResource": "{datastore ID}",
        "blobUrl": "https://teststorageaccount.blob.core.windows.net/testcontainer/test.geojson"
    }
}
```
Notes

Lorsque vous utilisez des identités managées attribuées par l'utilisateur, vous obtenez une erreur si vous ne fournissez pas de valeur pour la propriété msiClientId dans votre requête HTTP.

Pour plus d’informations sur les propriétés nécessaires dans le corps de la requête HTTP, consultez Propriétés du registre de données.
Une fois le corps de votre requête HTTP prêt, exécutez la requête HTTP PUT suivante :
```
https://us.atlas.microsoft.com/dataRegistries/{udid}?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key} 
```
Pour plus d’informations sur la propriété udid, consultez ID de données utilisateur.
Copiez la valeur de la clé Emplacement à partir de l’en-tête de réponse.

Conseil

Si le contenu d’un fichier précédemment inscrit est modifié, sa validation de données échoue et il n’est pas utilisable dans Azure Maps tant qu’il n’est pas réinscrit. Pour réinscrire un fichier, réexécutez la demande d’inscription en passant le même AzureBlob que celui utilisé pour créer l’inscription d’origine. La valeur de la clé Operation-Location est l’URL d’état que vous utilisez pour vérifier l’état de la création du registre de données dans la section suivante. Elle contient l’ID d’opération utilisé par l’API Opération Get.

Notes

La valeur de la clé Operation-Location ne contient pas la subscription-key, vous devez l’ajouter à l’URL de la demande quand vous l’utilisez pour vérifier l’état de création du registre de données.

Vérifier l’état de création du registre de données

Pour (éventuellement) vérifier l’état du processus de création du registre de données, entrez l’URL d’état que vous avez copiée dans la section Créer un registre de données, puis ajoutez votre clé d’abonnement comme paramètre de chaîne de requête. La demande doit ressembler à l’URL suivante :

https://us.atlas.microsoft.com/dataRegistries/operations/{udid}?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Primary-Subscription-key}

Obtenir la liste de tous les fichiers du registre de données

Pour obtenir la liste de tous les fichiers inscrits dans un compte Azure Maps en utilisant la demande de liste :

https://us.atlas.microsoft.com/dataRegistries?api-version=2023-06-01&subscription-key={Azure-Maps-Subscription-key}

Voici un exemple de réponse montrant trois états possibles : terminé, en cours d’exécution et échec :

{
  "value": [
    {
      "udid": "f6495f62-94f8-0ec2-c252-45626f82fcb2",
      "description": "Contoso Indoor Design",
      "kind": "AzureBlob",
      "azureBlob": {
        "dataFormat": "zip",
        "msiClientId": "3263cad5-ed8b-4829-b72b-3d1ba556e373",
        "linkedResource": "my-storage-account",
        "blobUrl": "https://mystorageaccount.blob.core.windows.net/my-container/my/blob/path1.zip",
        "sizeInBytes": 29920,
        "contentMD5": "CsFxZ2YSfxw3cRPlqokV0w=="
      },
      "status": "Completed"
    },
    {
      "udid": "8b1288fa-1958-4a2b-b68e-13a7i5af7d7c",
      "kind": "AzureBlob",
      "azureBlob": {
        "dataFormat": "geojson",
        "msiClientId": "3263cad5-ed8b-4829-b72b-3d1ba556e373",
        "linkedResource": "my-storage-account",
        "blobUrl": "https://mystorageaccount.blob.core.windows.net/my-container/my/blob/path2.geojson",
        "sizeInBytes": 1339
      },
      "status": "Running"
    },
    {
      "udid": "7c1288fa-2058-4a1b-b68f-13a6h5af7d7c",
      "description": "Contoso Geofence GeoJSON",
      "kind": "AzureBlob",
      "azureBlob": {
        "dataFormat": "geojson",
        "linkedResource": "my-storage-account",
        "blobUrl": "https://mystorageaccount.blob.core.windows.net/my-container/my/blob/path3.geojson",
        "sizeInBytes": 1650,
        "contentMD5": "rYpEfIeLbWZPyaICGEGy3A=="
      },
      "status": "Failed",
      "error": {
        "code": "ContentMD5Mismatch",
        "message": "Actual content MD5: sOJMJvFParkSxBsvvrPOMQ== doesn't match expected content MD5: CsFxZ2YSfxw3cRPlqokV0w==."
      }
    }
  ]
}

Les données retournées pendant l’exécution de la demande de liste sont similaires aux données fournies pendant la création d’un registre, mais avec quelques ajouts :

propriété	description
contentMD5	Hachage MD5 créé à partir du contenu du fichier en cours d’inscription. Pour plus d’informations, consultez Validation des données
sizeInBytes	Taille du contenu en octets.

Remplacer un registre de données

Si vous devez remplacer un fichier précédemment inscrit par un autre fichier, réexécutez la demande d’inscription, en passant le même AzureBlob que celui utilisé pour créer l’inscription d’origine, à l’exception de blobUrl. BlobUrl doit être modifié pour pointer vers le nouveau fichier.

Validation des données

Quand vous inscrivez un fichier dans Azure Maps en utilisant l’API de registre de données, un hachage MD5 est créé à partir du contenu du fichier pour l’encoder dans une empreinte digitale 128 bits et l’enregistrer dans AzureBlob comme propriété contentMD5. Le hachage MD5 stocké dans la propriété contentMD5 est utilisé pour garantir l’intégrité des données du fichier. Comme l’algorithme de hachage MD5 produit toujours la même sortie avec la même entrée, le processus de validation des données peut comparer la propriété contentMD5 du fichier quand il a été inscrit avec le hachage du fichier dans le compte de stockage Azure pour vérifier qu’il est intact et non modifié. Si le hachage n’est pas le même, la validation échoue. Si le fichier dans le compte de stockage sous-jacent change, la validation échoue. Si vous devez modifier le contenu d’un fichier qui a été inscrit dans Azure Maps, vous devez le réinscrire.

Comment créer un registre de données

Prérequis

Préparer l’inscription des données dans Azure Maps

Créer des identités managées

Créer un conteneur et charger des fichiers de données

Ajouter un magasin de données

Attribuer des rôles à des identités managées et les ajouter au magasin de données

Propriétés du registre de données

AzureBlob

Propriété msiClientId

Propriété blobUrl

ID de données utilisateur

Créer un registre de données

Vérifier l’état de création du registre de données

Obtenir la liste de tous les fichiers du registre de données

Remplacer un registre de données

Validation des données

Ressources supplémentaires