So erstellen Sie ein Datenregistrierung

  • Artikel

Mit dem Dienst zur Datenregistrierung können Sie Dateninhalte in einem Azure Storage-Konto bei Ihrem Azure Maps-Konto registrieren. Ein Beispiel für Daten kann eine Sammlung von Geofences enthalten, die im Geofencing-Dienst von Azure Maps verwendet werden. Ein weiteres Beispiel sind ZIP-Dateien mit Zeichnungspaketen (DWG) oder GeoJSON-Dateien, die der Azure Maps-Creator zum Erstellen oder Aktualisieren von Gebäudeplänen verwendet.

Voraussetzungen

Wichtig

  • In diesem Artikel wird die geografische URL us.atlas.microsoft.com verwendet. Wenn Ihr Konto nicht in den USA erstellt wurde, müssen Sie eine andere geografische URL verwenden. Weitere Informationen finden Sie unter Zugreifen auf Creator-Dienste.
  • In den URL-Beispielen in diesem Artikel müssen Sie folgende Angaben ersetzen:

Vorbereiten der Registrierung von Daten in Azure Maps

Bevor Sie Daten in Azure Maps registrieren können, müssen Sie eine Umgebung mit allen erforderlichen Komponenten erstellen. Sie benötigen ein Speicherkonto mit einem oder mehreren Containern, welche die Dateien enthalten, die Sie registrieren möchten, und verwaltete Identitäten für die Authentifizierung. In diesem Abschnitt wird erläutert, wie Sie Ihre Azure-Umgebung für die Registrierung von Daten in Azure Maps vorbereiten.

Verwaltete Identitäten erstellen

Es gibt zwei Arten von verwalteten Identitäten: systemseitig zugewiesene und benutzerseitig zugewiesene Identitäten. Vom System zugewiesene verwaltete Identitäten haben ihren Lebenszyklus an die Ressource gebunden, die sie erstellt hat. Benutzerseitig zugewiesene verwaltete Identitäten können für mehrere Ressourcen verwendet werden. Weitere Informationen finden Sie unter verwaltete Identitäten für Azure-Ressourcen.

Führen Sie die folgenden Schritte aus, um eine verwaltete Identität zu erstellen und Ihrem Azure Maps-Konto hinzuzufügen.

Erstellen einer systemseitig zugewiesenen verwalteten Identität:

  1. Wechseln Sie im Azure-Portal zu Ihrem Azure Maps-Konto.
  2. Wählen Sie im linken Menü Identität aus.
  3. Schalten Sie den Status auf Ein um.

Weitere Informationen finden Sie unter verwaltete Identitäten für Azure-Ressourcen.

Erstellen eines Containers und Hochladen von Datendateien

Bevor Sie Dateien zu einer Datenregistrierung hinzufügen, müssen Sie diese in einen Container in Ihrem Azure-Speicherkonto hochladen. Container ähneln einem Verzeichnis in einem Dateisystem, und Ihre Dateien werden so in Ihrem Azure-Speicherkonto organisiert.

Führen Sie die folgenden Schritte aus, um einen Container über das Azure-Portal zu erstellen:

  1. Wählen Sie in Ihrem Azure-Speicherkonto im Navigationsbereich im Abschnitt Datenspeicher die Option Container aus.

  2. Wählen Sie im Bereich Container die Option + Container aus, um den Bereich Neuer Container zu öffnen.

  3. Klicken Sie auf Erstellen, um den Container zu erstellen.

    Ein Screenshot der Seite „Neuer Container“ in einem Azure-Speicherkonto.

    Sobald Ihr Container erstellt wurde, können Sie Dateien in ihn hochladen.

  4. Sobald Ihr Container erstellt ist, wählen Sie ihn aus.

    Ein Screenshot zeigt den neuen Container, der gerade in einem Azure-Speicherkonto erstellt wurde.

  5. Wählen Sie auf der Symbolleiste Hochladen aus, und wählen Sie eine oder mehrere Dateien aus

  6. Wählen Sie die Schaltfläche Hochladen.

    Ein Screenshot der Seite „Blob hochladen“ beim Erstellen eines Containers.

Hinzufügen eines Datenspeichers

Sobald Sie ein Azure-Speicherkonto mit Dateien erstellt haben, die in einen oder mehrere Container hochgeladen wurden, können Sie den Datenspeicher erstellen, der die Speicherkonten mit Ihrem Azure Maps-Konto verknüpft.

Wichtig

Alle Speicherkonten, die mit einem Azure Maps-Konto verknüpft sind, müssen sich am gleichen geografischen Standort befinden. Weitere Informationen finden Sie unter Geografischer Bereich des Azure Maps-Dienstes.

Hinweis

Falls Sie kein Speicherkonto haben, lesen Sie Erstellen eines Speicherkontos.

  1. Wählen Sie im linken Menü In Ihrem Azure Maps-Konto die Option Datenspeicher aus.

  2. Wählen Sie die Schaltfläche Hinzufügen aus. Auf der rechten Seite wird ein Bildschirm Datenspeicher hinzufügen angezeigt.

  3. Geben Sie die gewünschte Datenspeicher-ID ein, und wählen Sie dann den Abonnementnamen und das Speicherkonto aus den Dropdownlisten aus.

  4. Wählen Sie Hinzufügen.

    Ein Screenshot zeigt den Bildschirm „Datenspeicher hinzufügen“.

Der neue Datenspeicher wird jetzt in der Liste der Datenspeicher angezeigt.

Zuweisen von Rollen zu verwalteten Identitäten und Hinzufügen zum Datenspeicher

Sobald Ihre verwalteten Identitäten und der Datenspeicher erstellt wurden, können Sie die verwalteten Identitäten dem Datenspeicher hinzufügen und ihnen gleichzeitig die Rollen Mitwirkender und Storage-Blobdatenleser zuweisen. Es ist zwar möglich, Rollen direkt in Ihrem verwalteten Identitäten- oder Speicherkonto zu Ihren verwalteten Identitäten hinzuzufügen, aber es ist einfacher, wenn Sie sie gleichzeitig mit Ihrem Azure Maps-Datenspeicher direkt im Datenspeicherbereich verknüpfen.

Hinweis

Jede verwaltete Identität, die dem Datenspeicher zugeordnet ist, benötigt die zugewiesenen Rollen Mitwirkender und Storage Blob-Datenleser. Wenn Sie nicht über die erforderlichen Berechtigungen zum Zuweisen von Rollen für verwaltete Identitäten verfügen, wenden Sie sich an Ihren Azure-Administrator. So weisen Sie Ihren verwalteten Identitäten Rollen zu und ordnen sie einem Datenspeicher zu:

  1. Wählen Sie im linken Menü In Ihrem Azure Maps-Konto die Option Datenspeicher aus.

  2. Wählen Sie einen oder mehrere Datenspeicher aus der Liste und dann Rollen zuweisen aus.

  3. Wählen Sie in der Dropdownliste die Verwaltete Identität aus, die dem/den ausgewählten Datenspeicher(n) zugeordnet werden soll.

  4. Wählen Sie in der Dropdownliste Zuzuweisende Rollen sowohl Mitwirkender als auch Storage Blob-Datenleser aus.

    Ein Screenshot zeigt den Bildschirm zum Zuweisen von Rollen zum Datenspeicher.

  5. Wählen Sie die Schaltfläche Zuweisen aus.

Eigenschaften der Datenregistrierung

Mit einem Datenspeicher, der in Ihrem Azure Maps-Konto erstellt wurde, können Sie die Eigenschaften erfassen, die zum Erstellen der Datenregistrierung erforderlich sind.

Es gibt AzureBlob-Eigenschaften, die Sie im Text der HTTP-Anforderung übergeben, und die Benutzerdaten-ID, die in der URL übergeben wird.

Der AzureBlob

Der AzureBlob ist ein JSON-Objekt, das Eigenschaften definiert, die zum Erstellen der Datenregistrierung erforderlich sind.

Eigenschaft BESCHREIBUNG
kind Definiert, welcher Typ von Objekt registriert wird. Derzeit ist AzureBlob der einzige Typ, der unterstützt wird.
dataFormat Das Datenformat der Datei, die sich im blobUrl befindet. Ihr Format kann entweder GeoJSON für den räumlichen Dienst oder ZIP für den Konvertierungsdienst sein.
msiClientId Die ID der verwalteten Identität, die zum Erstellen der Datenregistrierung verwendet wird.
linkedResource Die ID des Datenspeichers, der im Azure Maps-Konto registriert ist.
Der Datenspeicher enthält einen Link zur Datei, die registriert wird.
blobUrl Eine URL, die auf den Speicherort des AzurebBlob verweist, die in Ihren Container importierten Datei.

In den folgenden beiden Abschnitten erfahren Sie, wie Sie die Werte abrufen, die für die Eigenschaften msiClientId und blobUrl verwendet werden sollen.

Die msiClientId-Eigenschaft

Die msiClientId-Eigenschaft ist die ID der verwalteten Identität, die zum Erstellen der Datenregistrierung verwendet wird. Es gibt zwei Arten von verwalteten Identitäten: systemseitig zugewiesene und benutzerseitig zugewiesene Identitäten. Vom System zugewiesene verwaltete Identitäten haben ihren Lebenszyklus an die Ressource gebunden, die sie erstellt hat. Benutzerseitig zugewiesene verwaltete Identitäten können für mehrere Ressourcen verwendet werden. Weitere Informationen finden Sie unter verwaltete Identitäten für Azure-Ressourcen.

Wenn Sie systemseitig zugewiesene verwaltete Identitäten verwenden, müssen Sie keinen Wert für die msiClientId-Eigenschaft angeben. Der Datenregistrierungsdienst verwendet automatisch die systemseitig zugewiesene Identität des Azure Maps-Kontos, wenn msiClientId NULL ist.

Die blobUrl-Eigenschaft

Die blobUrl-Eigenschaft ist der Pfad zur Datei, die registriert wird. Sie können diesen Wert aus dem Container abrufen, dem er hinzugefügt wurde. Datenregistrierung

  1. Wählen Sie Ihr Speicherkonto im Azure-Portal aus.

  2. Klicken Sie im Menü links auf Container.

  3. Eine Liste der Container wird angezeigt. Wählen Sie den Container aus, der die Datei enthält, die Sie registrieren möchten.

  4. Der Container wird geöffnet und zeigt eine Liste der zuvor hochgeladenen Dateien an.

  5. Wählen Sie die gewünschte Datei aus, und kopieren Sie dann die URL.

    Ein Screenshot zeigt das Auswählen der URL, die als die blobUrl-Eigenschaft verwendet wird.

Die Benutzerdaten-ID

Die Benutzerdaten-ID (udid) der Datenregistrierung ist eine benutzerdefinierte GUID, die dem folgenden Regex-Muster entsprechen muss:

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

Tipp

Die udid ist eine benutzerdefinierte GUID, die beim Erstellen einer Datenregistrierung angegeben werden muss. Wenn Sie sicher sein möchten, dass Sie über einen global eindeutigen Bezeichner (GUID) verfügen, sollten Sie ihn erstellen, indem Sie ein GUID-Generierungstool ausführen, z. B. das Befehlszeilenprogramm Guidgen.exe (in Visual Studio verfügbar).

Erstellen einer Datenregistrierung

Nachdem Sie nun über Ihr Speicherkonto mit den gewünschten Dateien verfügen, die über den Datenspeicher mit Ihrem Azure Maps-Konto verknüpft sind und alle erforderlichen Eigenschaften erfasst haben, können Sie die API für die Datenregistrierung verwenden, um diese Dateien zu registrieren. Wenn in Ihrem Azure-Speicherkonto mehrere Dateien vorhanden sind, die Sie registrieren möchten, müssen Sie die Registrierungsanforderung für jede Datei (udid) ausführen.

Hinweis

Die maximale Größe einer Datei, die bei einem Azure Maps-Datenspeicher registriert werden kann, beträgt ein Gigabyte.

So erstellen Sie eine Datenregistrierung:

  1. Geben Sie die erforderlichen Informationen an, um auf das Speicherkonto zu verweisen, das der Datenregistrierung im Text Ihrer HTTP-Anforderung hinzugefügt wird. Die Informationen müssen im JSON-Format vorliegen und die folgenden Felder enthalten:

    {
"kind": "AzureBlob",
    "azureBlob": {
        "dataFormat": "geojson",
        "linkedResource": "{datastore ID}",
        "blobUrl": "https://teststorageaccount.blob.core.windows.net/testcontainer/test.geojson"
    }
}

    Hinweis

    Wenn Sie systemseitig zugewiesene verwaltete Identitäten verwenden, erhalten Sie eine Fehlermeldung, wenn Sie einen Wert für die msiClientId-Eigenschaft in Ihrer HTTP-Anforderung angeben.

    Weitere Informationen zu den Eigenschaften, die im HTTP-Anforderungstext erforderlich sind, finden Sie unter Eigenschaften der Datenregistrierung.

  2. Sobald Sie den Text ihrer HTTP-Anforderung bereit haben, führen Sie die folgende HTTP PUT-Anforderung aus:

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

    Weitere Informationen zur udid-Eigenschaft finden Sie unter Die Benutzerdaten-ID.

  3. Kopieren Sie den Wert des Schlüssels Operation-Location aus dem Antwortheader.

Tipp

Wenn der Inhalt einer zuvor registrierten Datei geändert wird, schlägt ihre Datenüberprüfung fehl, und sie kann erst dann in Azure Maps verwendet werden, wenn sie erneut registriert wird. Um eine Datei erneut zu registrieren, führen Sie die Registrierungsanforderung erneut aus und übergeben dabei denselben AzureBlob, der zum Erstellen der ursprünglichen Registrierung verwendet wurde. Der Wert des Schlüssels Operation-Location (Vorgang-Speicherort) ist die Status-URL, die Sie verwenden, um den Status der Erstellung der Datenregistrierung im nächsten Abschnitt zu überprüfen. Er enthält die Vorgangs-ID, die von der API für den GET-Vorgang verwendet wird.

Hinweis

Der Wert des Schlüssels Operation-Location (Vorgang-Speicherort) enthält nicht densubscription-key, Sie werden ihn der Anforderungs-URL hinzufügen müssen, wenn Sie ihn verwenden, um den Erstellungsstatus der Datenregistrierung zu überprüfen.

Überprüfen des Erstellungsstatus der Datenregistrierung

Um (optional) den Status des Erstellungsprozesses der Datenregistrierung zu überprüfen, geben Sie im Abschnitt Erstellen einer Datenregistrierung die von Ihnen kopierte Status-URL ein, und fügen Sie Ihren Abonnementschlüssel als Abfragezeichenfolgenparameter hinzu. Die Anforderung sollte in etwa so aussehen wie die folgende URL:

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

Abrufen einer Liste aller Dateien in der Datenregistrierung

Rufen Sie mithilfe der Anforderung List eine Liste aller in einem Azure Maps-Konto registrierten Dateien ab:

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

Das folgende Beispiel zeigt drei mögliche Status: „Completed“ (Abgeschlossen), „Running“ (Wird ausgeführt) und „Failed“ (Fehler):

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

Die beim Ausführen der Listenanforderung zurückgegebenen Daten ähneln den Daten, die beim Erstellen einer Registrierung bereitgestellt werden, mit einigen Ergänzungen:

property description
contentMD5 MD5-Hash, der aus dem Inhalt der zu registrierenden Datei erstellt wird. Weitere Informationen finden Sie unter Datenüberprüfung
sizeInBytes Die Größe des Inhalts in Bytes.

Ersetzen einer Datenregistrierung

Wenn Sie eine zuvor registrierte Datei durch eine andere Datei ersetzen müssen, führen Sie die Registrierungsanforderung erneut aus, und übergeben Sie denselben AzureBlob, der zum Erstellen der ursprünglichen Registrierung verwendet wurde, mit Ausnahme der blobUrl. Der BlobUrl muss geändert werden, um auf die neue Datei zu verweisen.

Datenvalidierung

Wenn Sie eine Datei in Azure Maps mithilfe der API zur Datenregistrierung registrieren, wird aus dem Inhalt der Datei ein MD5-Hash erstellt, der ihn in einen 128-Bit-Fingerabdruck codiert und in der AzureBlob als contentMD5-Eigenschaft speichert. Der in der contentMD5-Eigenschaft gespeicherte MD5-Hash wird verwendet, um die Datenintegrität der Datei sicherzustellen. Da der MD5-Hashalgorithmus bei gleicher Eingabe immer dieselbe Ausgabe erzeugt, kann der Datenüberprüfungsprozess die contentMD5-Eigenschaft der Datei zum Zeitpunkt der Registrierung mit einem Hash der Datei im Azure-Speicherkonto vergleichen, um zu überprüfen, ob sie intakt und unverändert ist. Wenn der Hash nicht identisch ist, schlägt die Validierung fehl. Wenn sich die Datei im zugrunde liegenden Speicherkonto ändert, tritt bei der Validierung ein Fehler auf. Wenn Sie den Inhalt einer Datei ändern müssen, die in Azure Maps registriert wurde, müssen Sie die Datei erneut registrieren.