Come creare il registro dati

Il servizio registro dati consente di registrare il contenuto dei dati in un account di Archiviazione di Azure con l'account Mappe di Azure. Un esempio di dati può includere una raccolta di recinti virtuali usati nel servizio di geofencing di Mappe di Azure. Un altro esempio è rappresentato da file ZIP contenenti pacchetti di disegno (DWG) o file GeoJSON usati da Creator di Mappe di Azure per creare o aggiornare piante di interni.

Prerequisiti

• Un account Mappe di Azure
• Chiave di sottoscrizione
• Un account di archiviazione di Azure

Preparare la registrazione dei dati in Mappe di Azure

Prima di poter registrare i dati in Mappe di Azure, è necessario creare un ambiente contenente tutti i componenti necessari. È necessario un account di archiviazione con uno o più contenitori che includano i file da registrare e le identità gestite per l'autenticazione. Questa sezione illustra come preparare l'ambiente di Azure per registrare i dati in Mappe di Azure.

Creare le identità gestite

Esistono due tipi di identità gestita: assegnata dal sistema e assegnata dall'utente. Le identità gestite assegnate dal sistema hanno il ciclo di vita associato alla risorsa che le ha creati. Le identità gestite assegnate dall'utente possono essere usate in più risorse. Per altre informazioni, vedere Identità gestite per le risorse di Azure.

Seguire questa procedura per creare un'identità gestita, aggiungerla all'account Mappe di Azure.

Per altre informazioni, vedere Identità gestite per le risorse di Azure.

Creare un contenitore e caricare file di dati

Prima di aggiungere file a un registro dati, è necessario caricarli in un contenitore nell'account di archiviazione di Azure. I contenitori sono simili a una directory in un file system, ovvero sono il modo in cui i file sono organizzati nell'account di archiviazione di Azure.

Per creare un contenitore nel portale di Azure, seguire questa procedura:

1. Nell'account di archiviazione di Azure selezionare Contenitori nella sezione Archiviazione dati del riquadro di spostamento.

2. Selezionare + Contenitore nel riquadro Contenitori per visualizzare il riquadro Nuovo contenitore.

3. Selezionare Crea per creare il contenitore.

   

   Dopo aver creato il contenitore, è possibile caricarvi file.

4. Dopo aver creato il contenitore, selezionarlo.

   

5. Selezionare Carica sulla barra degli strumenti, selezionare uno o più file

6. Seleziona il pulsante Carica.

   

Aggiungere un archivio dati

Dopo aver creato un account di archiviazione di Azure con i file caricati in uno o più contenitori, è possibile creare l'archivio dati che collega gli account di archiviazione all'account Mappe di Azure.

1. Selezionare Archivio dati dal menu a sinistra nell'account Mappe di Azure.

2. Seleziona il pulsante Aggiungi. Sul lato destro viene visualizzata una schermata Aggiungi archivio dati.

3. Immettere l'ID archivio dati desiderato, quindi selezionare il Nome della sottoscrizione e l'Account di archiviazione negli elenchi a discesa.

4. Selezionare Aggiungi.

   

Il nuovo archivio dati viene ora visualizzato nell'elenco degli archivi dati.

Assegnare ruoli alle identità gestite e aggiungerle all'archivio dati

Dopo aver creato le identità gestite e l'archivio dati, è possibile aggiungere le identità gestite all'archivio dati e allo stesso tempo assegnare loro i ruoli Collaboratore e Ruolo con autorizzazioni di lettura per i dati dei BLOB di archiviazione. Anche se è possibile aggiungere ruoli alle identità gestite direttamente nelle identità gestite o nell'account di archiviazione, è possibile farlo facilmente associandoli contemporaneamente all'archivio dati di Mappe di Azure direttamente nel riquadro dell'archivio dati.

1. Selezionare Archivio dati dal menu a sinistra nell'account Mappe di Azure.

2. Selezionare uno o più archivi dati dall'elenco, quindi Assegna ruoli.

3. Selezionare l'identità gestita da associare agli archivi dati selezionati dall'elenco a discesa.

4. Selezionare sia Collaboratore che Ruolo con autorizzazioni di lettura per i dati dei BLOB di archiviazione nell'elenco a discesa Ruoli da assegnare.

   

5. Selezionare il pulsante Assegna.

Proprietà del registro dati

Con un archivio dati creato nell'account Mappe di Azure, è possibile raccogliere le proprietà necessarie per creare il registro dati.

Si tratta delle proprietà di AzureBlob passate al corpo della richiesta HTTP e dell'ID dati utente passato nell'URL.

AzureBlob

AzureBlob è un oggetto JSON che definisce le proprietà necessarie per creare il registro dati.

¹ Creator di Mappe di Azure, il Registro dati e i servizi spaziali sono ora deprecati e verranno ritirati il 30/9/25.

Le due sezioni seguenti forniscono informazioni dettagliate su come ottenere i valori da usare per le proprietà msiClientId e blobUrl.

Proprietà msiClientId

La proprietà msiClientId è l'ID dell'identità gestita usata per creare il registro dati. Esistono due tipi di identità gestita: assegnata dal sistema e assegnata dall'utente. Le identità gestite assegnate dal sistema hanno il ciclo di vita associato alla risorsa che le ha creati. Le identità gestite assegnate dall'utente possono essere usate in più risorse. Per altre informazioni, vedere Identità gestite per le risorse di Azure.

Proprietà blobUrl

La proprietà blobUrl è il percorso del file registrato. È possibile ottenere questo valore dal contenitore a cui è stato aggiunto. Registro dati

1. Selezionare l'account di archiviazione nel portale di Azure.

2. Selezionare Contenitori dal menu a sinistra.

3. Viene visualizzato un elenco di contenitori. Selezionare il contenitore con il file da registrare.

4. Viene aperto il contenitore, che mostra un elenco dei file caricati in precedenza.

5. Selezionare il file desiderato e quindi copiare l'URL.

   

ID dati utente

L'ID dati utente (udid) del registro dati è un GUID definito dall'utente che deve essere conforme al modello Regex seguente:

^[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}$

Creare un registro dati

Dopo aver creato l'account di archiviazione con i file desiderati collegati all'account Mappe di Azure tramite l'archivio dati e aver raccolto tutte le proprietà necessarie, è possibile usare l'API del registro dati per registrare tali file. Se nell'account di archiviazione di Azure sono presenti più file da registrare, è necessario eseguire la richiesta di registrazione per ogni file (udid).

Per creare un registro dati:

Controllare lo stato di creazione del registro dati

Se si vuole controllare lo stato del processo di creazione del registro dati, immettere l'URL di stato copiato nella sezione Creare un registro dati e aggiungere la chiave di sottoscrizione come parametro di stringa di query. La richiesta dovrebbe essere simile all'URL seguente:

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

Ottenere un elenco di tutti i file nel registro dati

Usare la richiesta List per ottenere un elenco di tutti i file registrati in un account Mappe di Azure:

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

L'esempio seguente illustra tre possibili stati, completato, in esecuzione e non riuscito:

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

I dati restituiti durante l'esecuzione della richiesta di elenco sono simili ai dati forniti durante la creazione di un registro, con alcune aggiunte:

Sostituire un registro dati

Se è necessario sostituire un file registrato in precedenza con un altro file, eseguire nuovamente la richiesta di registrazione passando lo stesso AzureBlob usato per creare la registrazione originale, ad eccezione di blobUrl. BlobUrl va modificato in modo che punti al nuovo file.

Convalida dei dati

Quando si registra un file in Mappe di Azure usando l'API del registro dati, viene creato un hash MD5 dal contenuto del file, codificandolo in un'impronta digitale a 128 bit e salvandolo in AzureBlob come proprietà contentMD5. L'hash MD5 archiviato nella proprietà contentMD5 viene usato per garantire l'integrità dei dati del file. Poiché l'algoritmo hash MD5 produce sempre lo stesso output dato lo stesso input, il processo di convalida dei dati può confrontare la proprietà contentMD5 del file quando è stato registrato con un hash del file nell'account di archiviazione di Azure per verificare che sia intatto e non sia stato modificato. Se l'hash non è uguale, la convalida ha esito negativo. Se il file nell'account di archiviazione sottostante cambia, la convalida non riesce. Se è necessario modificare il contenuto di un file registrato in Mappe di Azure, è necessario registrarlo di nuovo.