Cara membuat registri data
Catatan
Penghentian layanan registri Data Azure Maps
Layanan registri Data Azure Maps sekarang tidak digunakan lagi dan akan dihentikan pada 30/9/25. Untuk informasi selengkapnya, lihat Pengumuman Akhir Masa Pakai Azure Maps Data Registry.
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. - Dalam 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:
- Buka akun Azure Maps Anda di portal Azure.
- Pilih Identitas dari bagian Pengaturan di menu sebelah kiri.
- 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:
Dari dalam akun penyimpanan Azure Anda, pilih Kontainer dari bagian Penyimpanan data di panel navigasi.
Pilih + Kontainer di panel Kontainer untuk memunculkan panel Kontainer baru.
Pilih Buat untuk membuat kontainer.
Setelah kontainer dibuat, Anda dapat mengunggah file ke dalamnya.
Setelah kontainer dibuat, pilih kontainer tersebut.
Pilih Unggah dari toolbar, pilih satu atau beberapa file
Pilih tombol Unggah.
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 Cakupan geografis layanan Azure Maps.
Catatan
Jika Anda tidak memiliki akun penyimpanan, lihat Membuat akun penyimpanan.
Pilih Datastore dari menu sebelah kiri di akun Azure Maps Anda.
Pilih tombol Tambahkan. Layar Tambahkan datastore muncul di sisi kanan.
Masukkan ID Datastore yang diinginkan lalu pilih Nama langganan dan akun Penyimpanan dari daftar drop-down.
Pilih Tambahkan.
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 datastore 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:
Pilih Datastore dari menu sebelah kiri di akun Azure Maps Anda.
Pilih satu atau beberapa penyimpanan data dari daftar, lalu Tetapkan peran.
Pilih Identitas terkelola untuk dikaitkan dengan datastore yang dipilih dari daftar drop-down.
Pilih Kontributor dan Pembaca Data Blob Penyimpanan di daftar drop-down Peran untuk ditetapkan.
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 |
Menentukan jenis objek apa yang didaftarkan. Saat ini AzureBlob adalah satu-satunya jenis yang didukung. |
dataFormat |
Format data file yang terletak di blobUrl. Formatnya dapat berupa GeoJSON untuk layanan spasial (Tidak digunakan lagi1) atau ZIP untuk layanan konversi (Tidak digunakan lagi1). |
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. |
1 Pembuat Azure Maps, dan registri data dan layanan Spasial sekarang tidak digunakan lagi dan akan dihentikan pada 30/9/25.
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 properti tersebut msiClientId
. Layanan registri data secara otomatis menggunakan identitas akun Azure Maps yang ditetapkan sistem saat msiClientId
null.
Properti blobUrl
Properti blobUrl
adalah jalur ke file yang didaftarkan. Anda bisa mendapatkan nilai ini dari kontainer tempat nilai ditambahkan. registri data
Pilih akun penyimpanan Anda di portal Azure.
Pilih Kontainer dari menu sebelah kiri.
Daftar kontainer muncul. Pilih kontainer yang berisi file yang ingin Anda daftarkan.
Kontainer terbuka, memperlihatkan daftar file yang sebelumnya diunggah.
Pilih file yang diinginkan, lalu salin URL.
ID data pengguna
ID data pengguna (udid
) 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 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:
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.
Setelah Anda menyiapkan isi permintaan HTTP Anda, 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.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 di 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 Lokasi Operasi 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.
Periksa 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 | description |
---|---|
contentMD5 | Hash MD5 yang dibuat dari konten file yang 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 sebagai AzureBlob
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.