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 Geofences utilizzata nel servizio geofencing Mappe di Azure. Un altro esempio è file ZIP contenenti pacchetti di disegno (DWG) o file GeoJSON che Mappe di Azure Creator usa per creare o aggiornare mappe interne.
Prerequisiti
Importante
- Questo articolo usa l'URL
us.atlas.microsoft.comgeografico. Se l'account non è stato creato nella Stati Uniti, è necessario usare un URL geografico diverso. Per altre informazioni, vedere Accesso ai servizi Creator. - Negli esempi di URL di questo articolo sarà necessario sostituire:
{Azure-Maps-Subscription-key}con la chiave di sottoscrizione Mappe di Azure.{udid}con l'ID dati utente del registro dati. Per altre informazioni, vedere ID dati utente.
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 contengono i file che si desidera registrare e gestire le identità per l'autenticazione. Questa sezione illustra come preparare l'ambiente di Azure per registrare i dati in Mappe di Azure.
Creare identità gestite
Esistono due tipi di identità gestite: assegnata dal sistema e assegnata dall'utente. Le identità gestite assegnate dal sistema hanno il ciclo di vita associato alla risorsa che li 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.
Creare un'identità gestita assegnata dal sistema:
- Passare all'account Mappe di Azure nell'portale di Azure.
- Selezionare Identità dal menu a sinistra.
- Attivare l'opzione Stato su Attiva.
Per altre informazioni, vedere Identità gestite per le risorse di Azure.
Creare un contenitore e caricare i 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, sono il modo in cui i file sono organizzati nell'account di archiviazione di Azure.
Per creare un contenitore nella portale di Azure, seguire questa procedura:
Nell'account di archiviazione di Azure selezionare Contenitori nella sezione Archiviazione dati nel riquadro di spostamento.
Selezionare + Contenitore nel riquadro Contenitori per visualizzare il riquadro Nuovo contenitore .
Selezionare Crea per creare il contenitore.
Dopo aver creato il contenitore, è possibile caricare i file in esso.
Dopo aver creato il contenitore, selezionarlo.
Selezionare Carica dalla barra degli strumenti, selezionare uno o più file
Selezionare il pulsante Carica.
Aggiungere un archivio dati
Dopo aver creato un account di archiviazione di Azure con file caricati in uno o più contenitori, è possibile creare l'archivio dati che collega gli account di archiviazione all'account di Mappe di Azure.
Importante
Tutti gli account di archiviazione collegati a un account Mappe di Azure devono trovarsi nella stessa posizione geografica. Per altre informazioni, vedere Mappe di Azure ambito geografico del servizio.
Nota
Se non si dispone di un account di archiviazione, vedere Creare un account di archiviazione.
Selezionare Archivio dati dal menu a sinistra nell'account Mappe di Azure.
Fare clic sul pulsante Aggiungi. Viene visualizzata una schermata Aggiungi archivio dati sul lato destro.
Immettere l'ID archivio dati desiderato e quindi selezionare il nome della sottoscrizione e l'account di archiviazione negli elenchi a discesa.
Selezionare Aggiungi.
Il nuovo archivio dati ora viene visualizzato nell'elenco di 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 assegnare contemporaneamente i ruoli Collaboratore e Lettore dati BLOB di archiviazione . Anche se è possibile aggiungere ruoli alle identità gestite direttamente nell'account di archiviazione o identità gestite, che è possibile eseguire facilmente associandoli contemporaneamente all'archivio dati Mappe di Azure direttamente nel riquadro dell'archivio dati.
Nota
Ogni identità gestita associata all'archivio dati richiederà i ruoli Collaboratore e Lettore dati BLOB di archiviazione concessi. Se non si dispone delle autorizzazioni necessarie per concedere ruoli alle identità gestite, consultare l'amministratore di Azure. Per assegnare ruoli alle identità gestite e associarle a un archivio dati:
Selezionare Archivio dati dal menu a sinistra nell'account Mappe di Azure.
Selezionare uno o più archivi dati dall'elenco, quindi Assegnare ruoli.
Selezionare l'identità gestita da associare agli archivi dati selezionati dall'elenco a discesa.
Selezionare sia Collaboratore che Lettore dati BLOB di archiviazione nell'elenco a discesa Ruoli per assegnare .
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.
Esistono le proprietà di AzureBlob passate nel corpo della richiesta HTTP e l'ID dati utente passato nell'URL.
The AzureBlob
È AzureBlob un oggetto JSON che definisce le proprietà necessarie per creare il Registro dati.
| Proprietà | Descrizione |
|---|---|
kind |
Definisce il tipo di oggetto registrato. Attualmente AzureBlob è l'unico tipo supportato. |
dataFormat |
Formato dati del file che si trova in BLOBUrl. Il formato può essere GeoJSON per il servizio spaziale o ZIP per il servizio di conversione. |
msiClientId |
ID dell'identità gestita utilizzata per creare il registro dati. |
linkedResource |
ID dell'archivio dati registrato nell'account Mappe di Azure. L'archivio dati contiene un collegamento al file da registrare. |
blobUrl |
URL che punta alla posizione di AzurebBlob, il file importato nel contenitore. |
Le due sezioni seguenti forniscono informazioni dettagliate su come ottenere i valori da usare per le proprietà msiClientId, blobUrl .
Proprietà msiClientId
La msiClientId proprietà è l'ID dell'identità gestita usata per creare il Registro di sistema dei dati. Esistono due tipi di identità gestite: assegnata dal sistema e assegnata dall'utente. Le identità gestite assegnate dal sistema hanno il ciclo di vita associato alla risorsa che le ha create. Le identità gestite assegnate dall'utente possono essere usate in più risorse. Per altre informazioni, vedere Identità gestite per le risorse di Azure.
Quando si usano identità gestite assegnate dal sistema, non è necessario specificare un valore per la msiClientId proprietà . Il servizio registro dati usa automaticamente l'identità assegnata dal sistema dell'account Mappe di Azure quando msiClientId è Null.
Proprietà blobUrl
La blobUrl proprietà è il percorso del file da registrare. È possibile ottenere questo valore dal contenitore a cui è stato aggiunto. Registro dati
Selezionare l'account di archiviazione nel portale di Azure.
Selezionare Contenitori dal menu a sinistra.
Viene visualizzato un elenco di contenitori. Selezionare il contenitore contenente il file da registrare.
Viene aperto il contenitore, che mostra un elenco dei file caricati in precedenza.
Selezionare il file desiderato e quindi copiare l'URL.
ID dati utente
L'ID dati utente (udid) del Registro di sistema 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}$
Suggerimento
udid è un GUID definito dall'utente che deve essere fornito durante la creazione di un registro dati. Se si vuole essere certi di avere un identificatore univoco globale (GUID), è consigliabile crearlo eseguendo uno strumento di generazione GUID, ad esempio il programma della riga di comando Guidgen.exe (disponibile con Visual Studio).
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 di sistema dei dati per registrare tali file. Se sono presenti più file nell'account di archiviazione di Azure da registrare, è necessario eseguire la richiesta di registrazione per ogni file (udid).
Nota
La dimensione massima di un file che può essere registrata con un archivio dati Mappe di Azure è un gigabyte.
Per creare un registro dati:
Specificare le informazioni necessarie per fare riferimento all'account di archiviazione che viene aggiunto al Registro di sistema dei dati nel corpo della richiesta HTTP. Le informazioni devono essere in formato JSON e contenere i campi seguenti:
{ "kind": "AzureBlob", "azureBlob": { "dataFormat": "geojson", "linkedResource": "{datastore ID}", "blobUrl": "https://teststorageaccount.blob.core.windows.net/testcontainer/test.geojson" } }Nota
Quando si usano identità gestite assegnate dal sistema, viene visualizzato un errore se si specifica un valore per la proprietà msiClientId nella richiesta HTTP.
Per altre informazioni sulle proprietà necessarie nel corpo della richiesta HTTP, vedere Proprietà del Registro di sistema dei dati.
Dopo aver ottenuto il corpo della richiesta HTTP pronta, eseguire la richiesta HTTP PUT seguente:
https://us.atlas.microsoft.com/dataRegistries/{udid}?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key}Per altre informazioni sulla
udidproprietà, vedere ID dati utente.Copiare il valore della chiave Operation-Location dall'intestazione della risposta.
Suggerimento
Se il contenuto di un file registrato in precedenza viene modificato, la convalida dei dati avrà esito negativo e non sarà utilizzabile in Mappe di Azure fino a quando non viene nuovamente registrata. Per registrare nuovamente un file, eseguire di nuovo la richiesta di registrazione, passando lo stesso AzureBlob usato per creare la registrazione originale. Il valore della chiave Operation-Location è l'URL di stato che verrà usato per controllare lo stato della creazione del Registro di sistema dati nella sezione successiva, contiene l'ID operazione usato dall'API Get operation .
Nota
Il valore della chiave Operation-Location non conterrà subscription-key, sarà necessario aggiungerlo all'URL della richiesta quando viene usato per controllare lo stato di creazione del Registro di sistema dei dati.
Controllare lo stato di creazione del Registro di sistema dei dati
Per (facoltativamente) controllare lo stato del processo di creazione del Registro di sistema dati, immettere l'URL di stato copiato nella sezione Creare un registro dati e aggiungere la chiave di sottoscrizione come parametro della 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 di sistema dei dati
Usare la richiesta Elenco 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, completati, in esecuzione e non riusciti:
{
"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:
| proprietà | description |
|---|---|
| contentMD5 | Hash MD5 creato dal contenuto del file registrato. Per altre informazioni, vedere Convalida dei dati |
| sizeInBytes | Dimensioni del contenuto in byte. |
Sostituire un registro dati
Se è necessario sostituire un file registrato in precedenza con un altro file, eseguire di nuovo la richiesta di registrazione, passando lo stesso AzureBlob usato per creare la registrazione originale, ad eccezione di blobUrl. Deve BlobUrl essere 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 di sistema dati, viene creato un hash MD5 dal contenuto del file, codificandolo in un'impronta digitale a 128 bit e salvandolo in AzureBlob come contentMD5 proprietà . L'hash MD5 archiviato nella contentMD5 proprietà 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 contentMD5 proprietà del file quando è stato registrato con un hash del file nell'account di archiviazione di Azure per verificare che sia intatto e non modificato. Se l'hash non è lo stesso, la convalida ha esito negativo. Se il file nell'account di archiviazione sottostante viene modificato, la convalida ha esito negativo. Se è necessario modificare il contenuto di un file registrato in Mappe di Azure, è necessario registrarlo di nuovo.