Gegevensregister maken
Met de gegevensregisterservice kunt u gegevensinhoud registreren in een Azure Storage-account met uw Azure Maps-account. Een voorbeeld van gegevens kan een verzameling geofences zijn die worden gebruikt in de Azure Maps Geofencing-service. Een ander voorbeeld zijn ZIP-bestanden met TEKENpakketten (DWG) of GeoJSON-bestanden die Azure Maps Creator gebruikt om indoorkaarten te maken of bij te werken.
Vereisten
- Een Azure Maps-account
- Een abonnementssleutel
- Een Azure-opslagaccount
Belangrijk
- In dit artikel wordt de
us.atlas.microsoft.comgeografische URL gebruikt. Als uw account niet is gemaakt in de Verenigde Staten, moet u een andere geografische URL gebruiken. Zie Toegang tot Creator-services voor meer informatie. - In de URL-voorbeelden in dit artikel moet u het volgende vervangen:
{Azure-Maps-Subscription-key}met uw Azure Maps abonnementssleutel.{udid}door de gebruikersgegevens-id van uw gegevensregister. Zie De gebruikersgegevens-id voor meer informatie.
Registratie van gegevens in Azure Maps voorbereiden
Voordat u gegevens in Azure Maps kunt registreren, moet u een omgeving maken die alle vereiste onderdelen bevat. U hebt een opslagaccount nodig met een of meer containers die de bestanden bevatten die u wilt registreren en beheerde identiteiten voor verificatie. In deze sectie wordt uitgelegd hoe u uw Azure-omgeving voorbereidt om gegevens in Azure Maps te registreren.
Beheerde identiteiten maken
Er zijn twee typen beheerde identiteiten: door het systeem toegewezen en door de gebruiker toegewezen. Voor door het systeem toegewezen beheerde identiteiten is de levenscyclus gekoppeld aan de resource die ze heeft gemaakt. Door de gebruiker toegewezen beheerde identiteiten kunnen voor meerdere resources worden gebruikt. Zie Beheerde identiteiten voor Azure-resources voor meer informatie.
Gebruik de volgende stappen om een beheerde identiteit te maken en voeg deze toe aan uw Azure Maps-account.
Een door het systeem toegewezen beheerde identiteit maken:
- Ga naar uw Azure Maps-account in de Azure Portal.
- Selecteer Identiteit in het linkermenu.
- Zet de status op Aan.
Zie Beheerde identiteiten voor Azure-resources voor meer informatie.
Een container maken en gegevensbestanden uploaden
Voordat u bestanden toevoegt aan een gegevensregister, moet u ze uploaden naar een container in uw Azure-opslagaccount. Containers zijn vergelijkbaar met een map in een bestandssysteem. Ze zijn de manier waarop uw bestanden zijn georganiseerd in uw Azure-opslagaccount.
Voer de volgende stappen uit om een container te maken in de Azure Portal:
Vanuit uw Azure-opslagaccount selecteert u Containers in de sectie Gegevensopslag in het navigatiedeelvenster.
Selecteer + Container in het deelvenster Containers om het deelvenster Nieuwe container weer te geven.
Selecteer Maken om de container te maken.
Zodra de container is gemaakt, kunt u er bestanden naar uploaden.
Nadat de container is gemaakt, selecteert u deze.
Selecteer Uploaden op de werkbalk en selecteer een of meer bestanden
Selecteer de knop Uploaden.
Een gegevensarchief toevoegen
Nadat u een Azure-opslagaccount hebt gemaakt met bestanden die zijn geüpload naar een of meer containers, kunt u het gegevensarchief maken waarmee de opslagaccounts worden gekoppeld aan uw Azure Maps-account.
Belangrijk
Alle opslagaccounts die zijn gekoppeld aan een Azure Maps-account moeten zich op dezelfde geografische locatie bevinden. Zie geografisch bereik van Azure Maps service voor meer informatie.
Notitie
Als u geen opslagaccount hebt, raadpleegt u Een opslagaccount maken.
Selecteer Gegevensarchief in het linkermenu in uw Azure Maps-account.
Selecteer de knop Add. Het scherm Gegevensarchief toevoegen wordt aan de rechterkant weergegeven.
Voer de gewenste gegevensarchief-id in en selecteer vervolgens de abonnementsnaam en het opslagaccount in de vervolgkeuzelijsten.
Selecteer Toevoegen.
Het nieuwe gegevensarchief wordt nu weergegeven in de lijst met gegevensarchieven.
Rollen toewijzen aan beheerde identiteiten en deze toevoegen aan het gegevensarchief
Zodra uw beheerde identiteiten en gegevensarchief zijn gemaakt, kunt u de beheerde identiteiten toevoegen aan het gegevensarchief en ze tegelijkertijd de rollen Inzender en Lezer voor opslagblobgegevens toewijzen. Hoewel het mogelijk is om rechtstreeks in uw beheerde identiteiten of opslagaccount rollen toe te voegen aan uw beheerde identiteiten of opslagaccount, wat u eenvoudig kunt doen terwijl u ze tegelijkertijd aan uw Azure Maps gegevensarchief rechtstreeks in het deelvenster Gegevensarchief kunt koppelen.
Notitie
Voor elke beheerde identiteit die aan het gegevensarchief is gekoppeld, moeten de rollen Inzender en Lezer van opslagblobgegevens worden verleend. Als u niet over de vereiste machtigingen beschikt om rollen toe te kennen aan beheerde identiteiten, raadpleegt u uw Azure-beheerder. Rollen toewijzen aan uw beheerde identiteiten en deze koppelen aan een gegevensarchief:
Selecteer Gegevensarchief in het linkermenu in uw Azure Maps-account.
Selecteer een of meer gegevensarchieven in de lijst en selecteer vervolgens Rollen toewijzen.
Selecteer de beheerde identiteit die u wilt koppelen aan de geselecteerde gegevensopslag(en) in de vervolgkeuzelijst.
Selecteer zowel Inzender als Lezer voor opslagblobgegevens in de vervolgkeuzelijst Rollen om toe te wijzen .
Selecteer de knop Toewijzen .
Eigenschappen van gegevensregister
Met een gegevensarchief dat is gemaakt in uw Azure Maps-account, kunt u de eigenschappen verzamelen die nodig zijn om het gegevensregister te maken.
Er zijn de AzureBlob-eigenschappen die u doorgeeft in de hoofdtekst van de HTTP-aanvraag en De gebruikersgegevens-id die in de URL is doorgegeven.
De AzureBlob
De AzureBlob is een JSON-object dat de eigenschappen definieert die nodig zijn om het gegevensregister te maken.
| Eigenschap | Beschrijving |
|---|---|
kind |
Definieert welk type object wordt geregistreerd. Momenteel is AzureBlob het enige type dat wordt ondersteund. |
dataFormat |
De gegevensindeling van het bestand in blobUrl. De indeling kan GeoJSON zijn voor de ruimtelijke service of ZIP voor de conversieservice. |
msiClientId |
De id van de beheerde identiteit die wordt gebruikt om het gegevensregister te maken. |
linkedResource |
De id van het gegevensarchief dat is geregistreerd in het Azure Maps-account. Het gegevensarchief bevat een koppeling naar het bestand dat wordt geregistreerd. |
blobUrl |
Een URL die verwijst naar de locatie van de AzurebBlob, het bestand dat in uw container is geïmporteerd. |
In de volgende twee secties vindt u meer informatie over het ophalen van de waarden die moeten worden gebruikt voor de eigenschappen msiClientId, blobUrl .
De eigenschap msiClientId
De msiClientId eigenschap is de id van de beheerde identiteit die wordt gebruikt om het gegevensregister te maken. Er zijn twee typen beheerde identiteiten: door het systeem toegewezen en door de gebruiker toegewezen. Voor door het systeem toegewezen beheerde identiteiten is de levenscyclus gekoppeld aan de resource die ze heeft gemaakt. Door de gebruiker toegewezen beheerde identiteiten kunnen voor meerdere resources worden gebruikt. Zie Beheerde identiteiten voor Azure-resources voor meer informatie.
Wanneer u door het systeem toegewezen beheerde identiteiten gebruikt, hoeft u geen waarde op te geven voor de msiClientId eigenschap. De gegevensregisterservice gebruikt automatisch de door het systeem toegewezen identiteit van het Azure Maps-account wanneer msiClientId null is.
De eigenschap blobUrl
De blobUrl eigenschap is het pad naar het bestand dat wordt geregistreerd. U kunt deze waarde ophalen uit de container waaraan deze is toegevoegd. gegevensregister
Selecteer uw opslagaccount in de Azure Portal.
Selecteer Containers in het linkermenu.
Er wordt een lijst met containers weergegeven. Selecteer de container met het bestand dat u wilt registreren.
De container wordt geopend, met een lijst met de bestanden die eerder zijn geüpload.
Selecteer het gewenste bestand en kopieer de URL.
De id van de gebruikersgegevens
De gebruikersgegevens-id (udid) van het gegevensregister is een door de gebruiker gedefinieerde GUID die moet voldoen aan het volgende Regex-patroon:
^[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}$
Tip
De udid is een door de gebruiker gedefinieerde GUID die moet worden opgegeven bij het maken van een gegevensregister. Als u er zeker van wilt zijn dat u een GLOBALLY Unique Identifier (GUID) hebt, kunt u deze maken door een hulpprogramma voor het genereren van een GUID uit te voeren, zoals het opdrachtregelprogramma Guidgen.exe (beschikbaar met Visual Studio).
Een gegevensregister maken
Nu u uw opslagaccount met de gewenste bestanden hebt gekoppeld aan uw Azure Maps-account via het gegevensarchief en alle vereiste eigenschappen hebt verzameld, kunt u de gegevensregister-API gebruiken om deze bestanden te registreren. Als uw Azure Storage-account meerdere bestanden bevat die u wilt registreren, moet u de registratieaanvraag voor elk bestand (udid) uitvoeren.
Notitie
De maximale grootte van een bestand dat kan worden geregistreerd bij een Azure Maps gegevensarchief is één gigabyte.
Een gegevensregister maken:
Geef de informatie op die nodig is om te verwijzen naar het opslagaccount dat wordt toegevoegd aan het gegevensregister in de hoofdtekst van uw HTTP-aanvraag. De informatie moet de JSON-indeling hebben en de volgende velden bevatten:
{ "kind": "AzureBlob", "azureBlob": { "dataFormat": "geojson", "linkedResource": "{datastore ID}", "blobUrl": "https://teststorageaccount.blob.core.windows.net/testcontainer/test.geojson" } }Notitie
Wanneer u door het systeem toegewezen beheerde identiteiten gebruikt, krijgt u een fout als u een waarde opgeeft voor de eigenschap msiClientId in uw HTTP-aanvraag.
Zie Gegevensregistereigenschappen voor meer informatie over de vereiste eigenschappen in de http-aanvraagbody.
Zodra de hoofdtekst van uw HTTP-aanvraag gereed is, voert u de volgende HTTP PUT-aanvraag uit:
https://us.atlas.microsoft.com/dataRegistries/{udid}?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key}Zie De gebruikersgegevens-id voor meer informatie over de
udideigenschap.Kopieer de waarde van de sleutel Operation-Location uit de antwoordheader.
Tip
Als de inhoud van een eerder geregistreerd bestand wordt gewijzigd, mislukt de gegevensvalidatie en kan het niet worden gebruikt in Azure Maps totdat het opnieuw is geregistreerd. Als u een bestand opnieuw wilt registreren, voert u de registratieaanvraag opnieuw uit en geeft u dezelfde AzureBlob door die is gebruikt om de oorspronkelijke registratie te maken. De waarde van de sleutel Operation-Location is de status-URL die u gebruikt om de status van het maken van het gegevensregister te controleren in de volgende sectie. Deze bevat de bewerkings-id die wordt gebruikt door de Api voor bewerking ophalen .
Notitie
De waarde van de sleutel Operation-Location bevat niet de subscription-key. U moet deze toevoegen aan de aanvraag-URL wanneer u deze gebruikt om de status van het maken van het gegevensregister te controleren.
De status van het maken van het gegevensregister controleren
Als u (optioneel) de status van het proces voor het maken van het gegevensregister wilt controleren, voert u de status-URL in die u hebt gekopieerd in de sectie Een gegevensregister maken en voegt u uw abonnementssleutel toe als een queryreeksparameter. De aanvraag moet er ongeveer uitzien als de volgende URL:
https://us.atlas.microsoft.com/dataRegistries/operations/{udid}?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Primary-Subscription-key}
Een lijst met alle bestanden in het gegevensregister ophalen
Gebruik de aanvraag Lijst om een lijst op te halen met alle bestanden die zijn geregistreerd in een Azure Maps-account:
https://us.atlas.microsoft.com/dataRegistries?api-version=2023-06-01&subscription-key={Azure-Maps-Subscription-key}
In het volgende voorbeeld ziet u drie mogelijke statussen: voltooid, actief en mislukt:
{
"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==."
}
}
]
}
De gegevens die worden geretourneerd bij het uitvoeren van de lijstaanvraag, zijn vergelijkbaar met de gegevens die zijn opgegeven bij het maken van een register, met enkele toevoegingen:
| property | beschrijving |
|---|---|
| contentMD5 | MD5-hash gemaakt op basis van de inhoud van het bestand dat wordt geregistreerd. Zie Gegevensvalidatie voor meer informatie |
| sizeInBytes | De grootte van de inhoud in bytes. |
Een gegevensregister vervangen
Als u een eerder geregistreerd bestand wilt vervangen door een ander bestand, voert u de registratieaanvraag opnieuw uit en geeft u dezelfde AzureBlob door die is gebruikt om de oorspronkelijke registratie te maken, met uitzondering van de blobUrl. De BlobUrl moet worden gewijzigd om naar het nieuwe bestand te verwijzen.
Gegevensvalidatie
Wanneer u een bestand registreert in Azure Maps met behulp van de gegevensregister-API, wordt er een MD5-hash gemaakt op basis van de inhoud van het bestand, waarbij het wordt gecodeerd in een 128-bits vingerafdruk en deze opslaat in de AzureBlob als de contentMD5 eigenschap. De MD5-hash die is opgeslagen in de contentMD5 eigenschap, wordt gebruikt om de gegevensintegriteit van het bestand te garanderen. Omdat het MD5-hash-algoritme altijd dezelfde uitvoer produceert op basis van dezelfde invoer, kan het gegevensvalidatieproces de contentMD5 eigenschap van het bestand vergelijken met een hash van het bestand in het Azure-opslagaccount om te controleren of het intact en ongewijzigd is. Als de hash niet hetzelfde is, mislukt de validatie. Als het bestand in het onderliggende opslagaccount wordt gewijzigd, mislukt de validatie. Als u de inhoud wilt wijzigen van een bestand dat is geregistreerd in Azure Maps, moet u het opnieuw registreren.