Cara membuat registri data

  • Artikel

Layanan registri data memungkinkan Anda mendaftarkan konten data di Akun Azure Storage dengan akun Azure Maps Anda. Contoh data mungkin mencakup kumpulan Geofence yang digunakan dalam layanan Azure Maps Geofencing. Contoh lain adalah file ZIP yang berisi paket gambar (DWG) atau file GeoJSON yang digunakan Azure Maps Creator untuk membuat atau memperbarui peta dalam ruangan.

Prasyarat

Penting

  • Artikel ini menggunakan URL geografis us.atlas.microsoft.com. Jika akun Anda tidak dibuat di Amerika Serikat, Anda harus menggunakan URL geografis yang berbeda. Untuk informasi selengkapnya, lihat Akses ke layanan Pembuat.
  • Pada contoh URL dalam artikel ini, Anda harus mengganti:
    • {Azure-Maps-Subscription-key}dengan kunci langganan Azure Maps Anda.
    • {udid} dengan ID data pengguna registri data Anda. Untuk informasi selengkapnya, lihat ID data pengguna.

Bersiap untuk mendaftarkan data di Azure Maps

Sebelum dapat mendaftarkan data di Azure Maps, Anda perlu membuat lingkungan yang berisi semua komponen yang diperlukan. Anda memerlukan akun penyimpanan dengan satu atau beberapa kontainer yang menyimpan file yang ingin Anda daftarkan dan identitas terkelola untuk autentikasi. Bagian ini menjelaskan cara menyiapkan lingkungan Azure Anda untuk mendaftarkan data di Azure Maps.

Membuat identitas terkelola

Ada dua jenis identitas terkelola: identitas yang ditetapkan sistem dan identitas yang ditetapkan pengguna. Siklus hidup identitas terkelola yang ditetapkan terkait dengan sumber daya yang menciptakannya. Identitas terkelola yang ditetapkan pengguna dapat digunakan pada banyak sumber daya. Untuk informasi selengkapnya, lihat identitas terkelola untuk sumber daya Azure.

Gunakan langkah-langkah berikut untuk membuat identitas terkelola, tambahkan ke akun Azure Maps Anda.

Buat identitas terkelola yang ditetapkan sistem:

  1. Buka akun Azure Maps Anda di portal Azure.
  2. Pilih Identitas dari menu sebelah kiri.
  3. Alihkan Status ke Aktif.

Untuk informasi selengkapnya, lihat identitas terkelola untuk sumber daya Azure.

Membuat kontainer dan mengunggah file data

Sebelum menambahkan file ke registri data, Anda harus mengunggahnya ke dalam kontainer di akun penyimpanan Azure Anda. Kontainer mirip dengan direktori dalam sistem file, mereka adalah cara file Anda diatur di akun penyimpanan Azure Anda.

Untuk membuat kontainer di portal Azure, ikuti langkah-langkah berikut:

  1. Dari dalam akun penyimpanan Azure Anda, pilih Kontainer dari bagian Penyimpanan data di panel navigasi.

  2. Pilih + Kontainer di panel Kontainer untuk memunculkan panel Kontainer baru .

  3. Pilih Buat untuk membuat kontainer.

    Cuplikan layar halaman kontainer baru di akun penyimpanan Azure.

    Setelah kontainer dibuat, Anda dapat mengunggah file ke dalamnya.

  4. Setelah kontainer dibuat, pilih kontainer tersebut.

    Cuplikan layar memperlihatkan kontainer baru yang baru saja dibuat di akun penyimpanan Azure.

  5. Pilih Unggah dari toolbar, pilih satu atau beberapa file

  6. Pilih tombol Unggah.

    Cuplikan layar halaman unggahan blob saat membuat kontainer.

Menambahkan datastore

Setelah membuat akun penyimpanan Azure dengan file yang diunggah ke dalam satu atau beberapa kontainer, Anda siap untuk membuat datastore yang menautkan akun penyimpanan ke akun Azure Maps Anda.

Penting

Semua akun penyimpanan yang ditautkan ke akun Azure Maps harus berada di lokasi geografis yang sama. Untuk informasi selengkapnya, lihat Azure Maps cakupan geografis layanan.

Catatan

Jika Anda tidak memiliki akun penyimpanan, lihat Membuat akun penyimpanan.

  1. Pilih Datastore dari menu sebelah kiri di akun Azure Maps Anda.

  2. Pilih tombol Tambahkan. Layar Tambahkan datastore muncul di sisi kanan.

  3. Masukkan ID Datastore yang diinginkan lalu pilih Nama langganan dan akun Penyimpanan dari daftar drop-down.

  4. Pilih Tambahkan.

    Cuplikan layar yang menunjukkan layar tambahkan datastore.

Datastore baru sekarang muncul dalam daftar penyimpanan data.

Menetapkan peran ke identitas terkelola dan menambahkannya ke datastore

Setelah identitas dan datastore terkelola Anda dibuat, Anda dapat menambahkan identitas terkelola ke datastore, dan secara bersamaan menetapkan peran Kontributor dan Pembaca Data Blob Penyimpanan . Meskipun Dimungkinkan untuk menambahkan peran ke identitas terkelola Anda langsung di identitas terkelola atau akun penyimpanan Anda, yang dapat Anda lakukan dengan mudah sambil mengaitkannya secara bersamaan dengan penyimpanan data Azure Maps Anda langsung di panel datastore.

Catatan

Setiap identitas terkelola yang terkait dengan datastore akan memerlukan peran Kontributor dan Pembaca Data Blob Penyimpanan yang diberikan kepada mereka. Jika Anda tidak memiliki izin yang diperlukan untuk memberikan peran ke identitas terkelola, konsultasikan dengan administrator Azure Anda. Untuk menetapkan peran ke identitas terkelola Anda dan mengaitkannya dengan datastore:

  1. Pilih Datastore dari menu sebelah kiri di akun Azure Maps Anda.

  2. Pilih satu atau beberapa penyimpanan data dari daftar, lalu Tetapkan peran.

  3. Pilih Identitas terkelola untuk dikaitkan dengan datastore yang dipilih dari daftar drop-down.

  4. Pilih Kontributor dan Pembaca Data Blob Penyimpanan di daftar drop-down Peran untuk menetapkan .

    Cuplikan layar memperlihatkan layar tetapkan peran ke datastore.

  5. Pilih tombol Tetapkan.

Properti registri data

Dengan datastore yang dibuat di akun Azure Maps, Anda siap untuk mengumpulkan properti yang diperlukan untuk membuat registri data.

Ada properti AzureBlob yang Anda berikan di isi permintaan HTTP, dan ID data pengguna yang diteruskan di URL.

The AzureBlob

AzureBlob adalah objek JSON yang menentukan properti yang diperlukan untuk membuat registri data.

Properti Deskripsi
kind Mendefinisikan jenis objek apa yang didaftarkan. Saat ini AzureBlob adalah satu-satunya jenis yang didukung.
dataFormat Format data file yang terletak di blobUrl. Formatnya bisa GeoJSON untuk layanan spasial atau ZIP untuk layanan konversi.
msiClientId ID identitas terkelola yang digunakan untuk membuat registri data.
linkedResource ID datastore yang terdaftar di akun Azure Maps.
Datastore berisi tautan ke file yang sedang didaftarkan.
blobUrl URL yang menunjuk ke Lokasi AzurebBlob, file yang diimpor ke kontainer Anda.

Dua bagian berikut memberi Anda detail cara mendapatkan nilai yang akan digunakan untuk properti msiClientId, blobUrl .

Properti msiClientId

Properti msiClientId adalah ID identitas terkelola yang digunakan untuk membuat registri data. Ada dua jenis identitas terkelola: identitas yang ditetapkan sistem dan identitas yang ditetapkan pengguna. Siklus hidup identitas terkelola yang ditetapkan terkait dengan sumber daya yang menciptakannya. Identitas terkelola yang ditetapkan pengguna dapat digunakan pada banyak sumber daya. Untuk informasi selengkapnya, lihat identitas terkelola untuk sumber daya Azure.

Saat menggunakan Identitas terkelola yang ditetapkan sistem, Anda tidak perlu memberikan nilai untuk msiClientId properti . Layanan registri data secara otomatis menggunakan identitas yang ditetapkan sistem dari akun Azure Maps saat msiClientId null.

Properti blobUrl

Properti blobUrl adalah jalur ke file yang sedang didaftarkan. Anda bisa mendapatkan nilai ini dari kontainer tempat nilai ditambahkan. registri data

  1. Pilih akun penyimpanan Anda di portal Azure.

  2. Pilih Kontainer dari menu sebelah kiri.

  3. Daftar kontainer muncul. Pilih kontainer yang berisi file yang ingin Anda daftarkan.

  4. Kontainer terbuka, memperlihatkan daftar file yang sebelumnya diunggah.

  5. Pilih file yang diinginkan, lalu salin URL.

    Cuplikan layar yang menunjukkan cara memilih URL yang digunakan sebagai properti blobUrl.

ID data pengguna

ID data pengguna (udid) dari registri data adalah GUID yang ditentukan pengguna yang harus sesuai dengan pola Regex berikut:

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

udid adalah GUID yang ditentukan pengguna yang harus disediakan saat membuat registri data. Jika Anda ingin yakin bahwa Anda memiliki pengidentifikasi unik global (GUID), pertimbangkan untuk membuatnya dengan menjalankan alat pembuatan GUID seperti program baris perintah Guidgen.exe (Tersedia dengan Visual Studio).

Membuat registri data

Sekarang setelah Anda memiliki akun penyimpanan dengan file yang diinginkan yang ditautkan ke akun Azure Maps Anda melalui datastore dan telah mengumpulkan semua properti yang diperlukan, Anda siap menggunakan API registri data untuk mendaftarkan file-file tersebut. Jika Anda memiliki beberapa file di akun penyimpanan Azure yang ingin Anda daftarkan, Anda perlu menjalankan permintaan register untuk setiap file (udid).

Catatan

Ukuran maksimum file yang dapat didaftarkan dengan datastore Azure Maps adalah satu gigabyte.

Untuk membuat registri data:

  1. Berikan informasi yang diperlukan untuk mereferensikan akun penyimpanan yang sedang ditambahkan ke registri data dalam isi permintaan HTTP Anda. Informasi harus dalam format JSON dan berisi bidang berikut:

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

    Catatan

    Saat menggunakan identitas terkelola yang ditetapkan sistem, Anda akan mendapatkan kesalahan jika Anda memberikan nilai untuk properti msiClientId dalam permintaan HTTP Anda.

    Untuk informasi selengkapnya tentang properti yang diperlukan dalam isi permintaan HTTP, lihat Properti registri data.

  2. Setelah isi permintaan HTTP Anda siap, jalankan permintaan HTTP PUT berikut:

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

    Untuk informasi selengkapnya tentang udid properti , lihat ID data pengguna.

  3. Salin nilai kunci Operation-Location dari header respons.

Tip

Jika konten file yang didaftarkan sebelumnya dimodifikasi, itu akan gagal validasi datanya dan tidak akan dapat digunakan dalam Azure Maps sampai didaftarkan kembali. Untuk mendaftarkan ulang file, jalankan ulang permintaan register, melewati AzureBlob yang sama yang digunakan untuk membuat pendaftaran asli. Nilai kunci Operation-Location adalah URL status yang akan Anda gunakan untuk memeriksa status pembuatan registri data di bagian berikutnya, berisi ID operasi yang digunakan oleh Get operation API.

Catatan

Nilai kunci Operation-Location tidak akan berisi subscription-key, Anda harus menambahkannya ke URL permintaan saat menggunakannya untuk memeriksa status pembuatan registri data.

Memeriksa status pembuatan registri data

Untuk (opsional) periksa status proses pembuatan registri data, masukkan URL status yang Anda salin di bagian Buat registri data , dan tambahkan kunci langganan Anda sebagai parameter string kueri. Permintaan akan terlihat mirip dengan URL berikut:

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

Mendapatkan daftar semua file di registri data

Gunakan permintaan Daftar untuk mendapatkan daftar semua file yang terdaftar di akun Azure Maps:

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

Sampel berikut menunjukkan tiga kemungkinan status, selesai, berjalan, dan gagal:

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

Data yang dikembalikan saat menjalankan permintaan daftar mirip dengan data yang disediakan saat membuat registri dengan beberapa penambahan:

properti deskripsi
contentMD5 Hash MD5 yang dibuat dari konten file yang sedang didaftarkan. Untuk informasi selengkapnya, lihat Validasi data
sizeInBytes Ukuran konten dalam byte.

Mengganti registri data

Jika Anda perlu mengganti file yang terdaftar sebelumnya dengan file lain, jalankan ulang permintaan register, meneruskan AzureBlob yang sama yang digunakan untuk membuat pendaftaran asli, kecuali untuk blobUrl. BlobUrl Perlu dimodifikasi untuk menunjuk ke file baru.

Validasi data

Saat Anda mendaftarkan file di Azure Maps menggunakan API registri data, hash MD5 dibuat dari konten file, mengodekannya ke dalam sidik jari 128-bit dan menyimpannya di AzureBlob sebagai contentMD5 properti . Hash MD5 yang disimpan di contentMD5 properti digunakan untuk memastikan integritas data file. Karena algoritma hash MD5 selalu menghasilkan output yang sama dengan input yang sama, proses validasi data dapat membandingkan contentMD5 properti file ketika didaftarkan terhadap hash file di akun penyimpanan Azure untuk memeriksa apakah file tersebut utuh dan tidak dimodifikasi. Jika hash tidak sama, validasi gagal. Jika file di akun penyimpanan yang mendasar berubah, validasi gagal. Jika Anda perlu mengubah konten file yang telah terdaftar di Azure Maps, Anda perlu mendaftarkannya lagi.