Jak utworzyć rejestr danych

Usługa rejestru danych umożliwia rejestrowanie zawartości danych na koncie usługi Azure Storage przy użyciu konta Azure Maps. Przykładem danych może być kolekcja geofencingów używanych w usłudze Azure Maps Geofencing. Innym przykładem są pliki ZIP zawierające pakiety rysunkowe (DWG) lub pliki GeoJSON, które Azure Maps Twórca używa do tworzenia lub aktualizowania map wewnętrznych.

Wymagania wstępne

• Konto Azure Maps
• Klucz subskrypcji
• Konto usługi Azure Storage

Ważne

• W tym artykule jest używany us.atlas.microsoft.com adres URL geograficzny. Jeśli twoje konto nie zostało utworzone w Stany Zjednoczone, musisz użyć innego adresu URL geograficznego. Aby uzyskać więcej informacji, zobacz Dostęp do usług dla twórców.
• W przykładach adresów URL w tym artykule należy zastąpić następujące elementy:
  • {Azure-Maps-Subscription-key}z kluczem subskrypcji Azure Maps.
  • {udid} z identyfikatorem danych użytkownika rejestru danych. Aby uzyskać więcej informacji, zobacz Identyfikator danych użytkownika.

Przygotowywanie do rejestrowania danych w Azure Maps

Przed zarejestrowaniem danych w Azure Maps należy utworzyć środowisko zawierające wszystkie wymagane składniki. Potrzebujesz konta magazynu z co najmniej jednym kontenerem, który przechowuje pliki, które chcesz zarejestrować i tożsamości zarządzane na potrzeby uwierzytelniania. W tej sekcji wyjaśniono, jak przygotować środowisko platformy Azure do rejestrowania danych w Azure Maps.

Tworzenie tożsamości zarządzanych

Istnieją dwa typy tożsamości zarządzanych: przypisane przez system i przypisane przez użytkownika. Tożsamości zarządzane przypisane przez system mają swój cykl życia związany z zasobem, który je utworzył. Tożsamości zarządzane przypisane przez użytkownika mogą być używane w wielu zasobach. Aby uzyskać więcej informacji, zobacz tożsamości zarządzane dla zasobów platformy Azure.

Aby utworzyć tożsamość zarządzaną, dodaj ją do konta Azure Maps.

przypisane przez system

Utwórz tożsamość zarządzaną przypisaną przez system:

1. Przejdź do konta Azure Maps w Azure Portal.
2. Wybierz pozycję Tożsamość z menu po lewej stronie.
3. Przełącz pozycję Stan na Włączone.

przypisane przez użytkownika

Utwórz tożsamość zarządzaną przypisaną przez użytkownika:

1. Przejdź do Azure Portal i wybierz pozycję Utwórz zasób.

2. W kontrolce Usługi wyszukiwania i marketplace wprowadź tożsamość zarządzaną przypisaną przez użytkownika.

3. Na stronie Tworzenie tożsamości zarządzanej przypisanej przez użytkownika wybierz subskrypcję, grupę zasobów, region i nazwę zarządzanej identyfikacji.

4. Wybierz pozycję Przeglądanie i tworzenie, a następnie gdy wszystko będzie gotowe, Utwórz.

   

5. Na koncie Azure Maps wybierz pozycję Tożsamość w sekcji Ustawienia menu po lewej stronie.

6. Wybierz kartę Przypisane przez użytkownika .

7. Wybierz pozycję + Dodaj.

8. Na ekranie Dodawanie tożsamości zarządzanej przypisanej przez użytkownika wybierz żądaną subskrypcję i tożsamość zarządzaną.

9. Wybierz pozycję Dodaj.

   

Tożsamość zarządzana zdefiniowana przez użytkownika powinna zostać teraz dodana do konta Azure Maps.

Aby uzyskać więcej informacji, zobacz tożsamości zarządzane dla zasobów platformy Azure.

Tworzenie kontenera i przekazywanie plików danych

Przed dodaniem plików do rejestru danych należy przekazać je do kontenera na koncie usługi Azure Storage. Kontenery są podobne do katalogu w systemie plików. Są one sposobem organizowania plików na koncie usługi Azure Storage.

Aby utworzyć kontener w Azure Portal, wykonaj następujące kroki:

1. Z poziomu konta usługi Azure Storage wybierz pozycję Kontenery w sekcji Magazyn danych w okienku nawigacji.

2. Wybierz pozycję + Kontener w okienku Kontenery , aby wyświetlić okienko Nowy kontener .

3. Wybierz pozycję Utwórz, aby utworzyć kontener.

   

   Po utworzeniu kontenera możesz przekazać do niego pliki.

4. Po utworzeniu kontenera wybierz go.

   

5. Wybierz pozycję Przekaż na pasku narzędzi, wybierz co najmniej jeden plik

6. Wybierz przycisk Przekaż.

   

Dodawanie magazynu danych

Po utworzeniu konta usługi Azure Storage z plikami przekazanymi do co najmniej jednego kontenera możesz utworzyć magazyn danych, który łączy konta magazynu z kontem Azure Maps.

Ważne

Wszystkie konta magazynu połączone z kontem Azure Maps muszą znajdować się w tej samej lokalizacji geograficznej. Aby uzyskać więcej informacji, zobacz Azure Maps zakres geograficzny usługi.

Uwaga

Jeśli nie masz konta magazynu, zobacz Tworzenie konta magazynu.

1. Wybierz pozycję Magazyn danych z menu po lewej stronie na koncie Azure Maps.

2. Wybierz przycisk Dodaj . Ekran Dodawanie magazynu danych jest wyświetlany po prawej stronie.

3. Wprowadź żądany identyfikator magazynu danych , a następnie wybierz pozycję Nazwa subskrypcji i Konto magazynu z listy rozwijanej.

4. Wybierz pozycję Dodaj.

   

Nowy magazyn danych jest teraz wyświetlany na liście magazynów danych.

Przypisywanie ról do tożsamości zarządzanych i dodawanie ich do magazynu danych

Po utworzeniu tożsamości zarządzanych i magazynu danych można dodać tożsamości zarządzane do magazynu danych i jednocześnie przypisać im role Współautor i Czytelnik danych obiektów blob usługi Storage . Chociaż można dodawać role do tożsamości zarządzanych bezpośrednio w tożsamościach zarządzanych lub na koncie magazynu, co można łatwo zrobić, jednocześnie kojarząc je z magazynem danych Azure Maps bezpośrednio w okienku magazynu danych.

Uwaga

Każda tożsamość zarządzana skojarzona z magazynem danych będzie potrzebować ról współautora i czytelnika danych obiektu blob usługi Storage przyznanych im. Jeśli nie masz wymaganych uprawnień do udzielania ról tożsamościom zarządzanym, skontaktuj się z administratorem platformy Azure. Aby przypisać role do tożsamości zarządzanych i skojarzyć je z magazynem danych:

1. Wybierz pozycję Magazyn danych z menu po lewej stronie na koncie Azure Maps.

2. Wybierz jeden lub więcej magazynów danych z listy, a następnie pozycję Przypisz role.

3. Wybierz tożsamość zarządzaną , która ma być skojarzona z wybranymi magazynami danych z listy rozwijanej.

4. Wybierz pozycję Współautor i Czytelnik danych obiektów blob usługi Storage w rolach, aby przypisać listę rozwijaną.

   

5. Wybierz przycisk Przypisz .

Właściwości rejestru danych

W przypadku magazynu danych utworzonego na koncie Azure Maps możesz zebrać właściwości wymagane do utworzenia rejestru danych.

Istnieją właściwości usługi AzureBlob przekazywane w treści żądania HTTP, a identyfikator danych użytkownika przekazany w adresie URL.

The AzureBlob

Jest AzureBlob to obiekt JSON, który definiuje właściwości wymagane do utworzenia rejestru danych.

Właściwość	Opis
kind	Definiuje typ zarejestrowanego obiektu. Obecnie usługa AzureBlob jest jedynym rodzajem obsługiwanym.
dataFormat	Format danych pliku znajdującego się w obiekcie blobUrl. Jego format może być geoJSON dla usługi przestrzennej lub ZIP dla usługi konwersji.
msiClientId	Identyfikator tożsamości zarządzanej używanej do tworzenia rejestru danych.
linkedResource	Identyfikator magazynu danych zarejestrowanego na koncie Azure Maps. Magazyn danych zawiera link do zarejestrowanego pliku.
blobUrl	Adres URL wskazujący lokalizację obiektu AzurebBlob, plik zaimportowany do kontenera.

Poniższe dwie sekcje zawierają szczegółowe informacje na temat sposobu uzyskiwania wartości do użycia dla właściwości msiClientId, blobUrl .

Właściwość msiClientId

Właściwość msiClientId jest identyfikatorem tożsamości zarządzanej użytej do utworzenia rejestru danych. Istnieją dwa typy tożsamości zarządzanych: przypisane przez system i przypisane przez użytkownika. Tożsamości zarządzane przypisane przez system mają swój cykl życia związany z zasobem, który je utworzył. Tożsamości zarządzane przypisane przez użytkownika mogą być używane w wielu zasobach. Aby uzyskać więcej informacji, zobacz tożsamości zarządzane dla zasobów platformy Azure.

przypisane przez system

W przypadku korzystania z tożsamości zarządzanych przypisanych przez system nie trzeba podawać wartości dla msiClientId właściwości. Usługa rejestru danych automatycznie używa przypisanej przez system tożsamości konta Azure Maps, gdy msiClientId ma wartość null.

przypisana przez użytkownika

Wartość używana dla msiClientId właściwości to identyfikator klienta tożsamości zarządzanej przypisanej przez użytkownika.

1. Na koncie Azure Maps wybierz pozycję Tożsamość z menu po lewej stronie.

2. Zatrzymaj wskaźnik myszy na nazwie zarządzanej identyfikacji, dopóki nie zostanie wyświetlony jako link, a następnie wybierz go.

   

3. Skopiuj identyfikator klienta.

   

Właściwość blobUrl

Właściwość blobUrl jest ścieżką do zarejestrowanego pliku. Tę wartość można pobrać z kontenera, do którego został dodany. rejestr danych

1. Wybierz konto magazynu w Azure Portal.

2. Wybierz pozycję Kontenery z menu po lewej stronie.

3. Zostanie wyświetlona lista kontenerów. Wybierz kontener zawierający plik, który chcesz zarejestrować.

4. Zostanie otwarty kontener z listą wcześniej przekazanych plików.

5. Wybierz żądany plik, a następnie skopiuj adres URL.

   

Identyfikator danych użytkownika

Identyfikator danych użytkownika (udid) rejestru danych to zdefiniowany przez użytkownika identyfikator GUID, który musi być zgodny z następującym wzorcem wyrażenia regularnego:

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

Porada

Jest udid to zdefiniowany przez użytkownika identyfikator GUID, który należy podać podczas tworzenia rejestru danych. Jeśli chcesz mieć pewność, że masz unikatowy identyfikator globalny (GUID), rozważ utworzenie go, uruchamiając narzędzie do generowania identyfikatora GUID, takie jak program wiersza polecenia Guidgen.exe (dostępny w programie Visual Studio).

Tworzenie rejestru danych

Teraz, gdy masz konto magazynu z żądanymi plikami połączonymi z kontem Azure Maps za pośrednictwem magazynu danych i zebrano wszystkie wymagane właściwości, możesz przystąpić do rejestrowania tych plików przy użyciu interfejsu API rejestru danych. Jeśli masz wiele plików na koncie usługi Azure Storage, które chcesz zarejestrować, musisz uruchomić żądanie rejestracji dla każdego pliku (udid).

Uwaga

Maksymalny rozmiar pliku, który można zarejestrować w magazynie danych Azure Maps to jeden gigabajt.

Aby utworzyć rejestr danych:

przypisane przez system

1. Podaj informacje potrzebne do odwoływanie się do konta magazynu dodawanego do rejestru danych w treści żądania HTTP. Informacje muszą być w formacie JSON i zawierać następujące pola:

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

   Uwaga

   W przypadku korzystania z tożsamości zarządzanych przypisanych przez system wystąpi błąd, jeśli w żądaniu HTTP zostanie wyświetlona wartość właściwości msiClientId.

   Aby uzyskać więcej informacji na temat właściwości wymaganych w treści żądania HTTP, zobacz Właściwości rejestru danych.

2. Po uzyskaniu treści żądania HTTP gotowego wykonaj następujące żądanie HTTP PUT:

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

   Aby uzyskać więcej informacji na udid temat właściwości, zobacz Identyfikator danych użytkownika.

3. Skopiuj wartość klucza Operation-Location z nagłówka odpowiedzi.

przypisana przez użytkownika

1. Podaj informacje potrzebne do odwoływanie się do konta magazynu dodawanego do rejestru danych w treści żądania HTTP. Informacje muszą być w formacie JSON i zawierać następujące pola:

   {
   "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"
       }
   }
   

   Uwaga

   W przypadku korzystania z tożsamości zarządzanych przypisanych przez użytkownika wystąpi błąd, jeśli nie podasz wartości właściwości msiClientId w żądaniu HTTP.

   Aby uzyskać więcej informacji na temat właściwości wymaganych w treści żądania HTTP, zobacz Właściwości rejestru danych.

2. Po uzyskaniu treści żądania HTTP gotowego wykonaj następujące żądanie HTTP PUT:

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

   Aby uzyskać więcej informacji na udid temat właściwości, zobacz Identyfikator danych użytkownika.

3. Skopiuj wartość klucza Operation-Location z nagłówka odpowiedzi.

Porada

Jeśli zawartość wcześniej zarejestrowanego pliku zostanie zmodyfikowana, weryfikacja danych zakończy się niepowodzeniem i nie będzie można jej używać w Azure Maps, dopóki nie zostanie ponownie zarejestrowana. Aby ponownie zarejestrować plik, uruchom ponownie żądanie rejestracji, przekazując ten sam obiekt AzureBlob użyty do utworzenia oryginalnej rejestracji. Wartość klucza Operation-Location to adres URL stanu, którego użyjesz do sprawdzenia stanu tworzenia rejestru danych w następnej sekcji, zawiera identyfikator operacji używany przez interfejs API operacji Pobierania .

Uwaga

Wartość klucza Operation-Location nie będzie zawierać subscription-keyelementu , należy dodać ją do adresu URL żądania podczas korzystania z niego w celu sprawdzenia stanu tworzenia rejestru danych.

Sprawdzanie stanu tworzenia rejestru danych

Aby (opcjonalnie) sprawdzić stan procesu tworzenia rejestru danych, wprowadź adres URL stanu skopiowany w sekcji Tworzenie rejestru danych i dodaj klucz subskrypcji jako parametr ciągu zapytania. Żądanie powinno wyglądać podobnie do następującego adresu URL:

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

Pobieranie listy wszystkich plików w rejestrze danych

Użyj żądania listy, aby uzyskać listę wszystkich plików zarejestrowanych na koncie Azure Maps:

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

Poniższy przykład przedstawia trzy możliwe stany, ukończone, uruchomione i zakończone niepowodzeniem:

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

Dane zwracane podczas uruchamiania żądania listy są podobne do danych podanych podczas tworzenia rejestru z kilkoma dodatkami:

property	description (opis)
contentMD5	Skrót MD5 utworzony na podstawie zawartości zarejestrowanego pliku. Aby uzyskać więcej informacji, zobacz Walidacja danych
sizeInBytes	Rozmiar zawartości w bajtach.

Zastępowanie rejestru danych

Jeśli musisz zastąpić wcześniej zarejestrowany plik innym plikiem, uruchom ponownie żądanie rejestracji, przekazując ten sam obiekt AzureBlob użyty do utworzenia oryginalnej rejestracji, z wyjątkiem obiektu blobUrl. Należy zmodyfikować element BlobUrl w celu wskazania nowego pliku.

Walidacja danych

Po zarejestrowaniu pliku w Azure Maps przy użyciu interfejsu API rejestru danych skrót MD5 jest tworzony na podstawie zawartości pliku, kodując go w 128-bitowym odcisku palca i zapisując go w AzureBlob postaci contentMD5 właściwości . Skrót MD5 przechowywany we contentMD5 właściwości służy do zapewnienia integralności danych pliku. Ponieważ algorytm skrótu MD5 zawsze generuje te same dane wyjściowe, biorąc pod uwagę te same dane wejściowe, proces weryfikacji danych może porównać contentMD5 właściwość pliku, gdy został on zarejestrowany względem skrótu pliku na koncie usługi Azure Storage, aby sprawdzić, czy jest on nienaruszony i niezmodyfikowany. Jeśli skrót nie jest taki sam, walidacja zakończy się niepowodzeniem. Jeśli plik na bazowym koncie magazynu ulegnie zmianie, walidacja zakończy się niepowodzeniem. Jeśli musisz zmodyfikować zawartość pliku zarejestrowanego w Azure Maps, musisz zarejestrować go ponownie.