Membuat set data adalah proses dua langkah:
Buat permintaan untuk membuat set data.
Buat permintaan untuk mengupload data ke set data.
Setelah upload data awal, Anda dapat mengupload data baru ke set data untuk membuat versi baru set data.
Prasyarat
Saat membuat set data:
- Nama tampilan dalam project Google Cloud Anda harus berbeda-beda.
- Nama tampilan harus kurang dari 64 byte (Karena karakter ini direpresentasikan dalam UTF-8, dalam beberapa bahasa, setiap karakter dapat direpresentasikan oleh beberapa byte).
- Deskripsi harus kurang dari 1000 byte.
Saat mengupload data:
- Jenis file yang didukung adalah CSV, GeoJSON, dan KML.
- Ukuran file maksimum yang didukung adalah 350 MB.
- Nama kolom atribut tidak boleh diawali dengan string "?_".
- Geometri tiga dimensi tidak didukung. Ini mencakup akhiran "Z" dalam format WKT, dan koordinat ketinggian dalam format GeoJSON.
Praktik terbaik persiapan data
Jika data sumber kompleks atau besar, seperti titik padat, linestring panjang, atau poligon (sering kali ukuran file sumber lebih besar dari 50 MB termasuk dalam kategori ini), pertimbangkan untuk menyederhanakan data sebelum mengupload untuk mencapai performa terbaik dalam peta visual.
Berikut adalah beberapa praktik terbaik untuk menyiapkan data Anda:
- Meminimalkan properti fitur. Hanya simpan properti fitur yang diperlukan untuk menata gaya peta Anda, misalnya "id" dan "category". Anda dapat menggabungkan properti tambahan ke fitur dalam aplikasi klien menggunakan gaya berbasis data pada kunci ID unik. Misalnya, lihat Melihat data secara real time dengan Gaya visual berbasis data.
- Gunakan jenis data sederhana untuk objek properti jika memungkinkan, seperti bilangan bulat, untuk meminimalkan ukuran ubin dan meningkatkan performa peta.
- Sederhanakan geometri kompleks sebelum mengupload file. Anda dapat melakukannya di alat geospasial pilihan Anda, seperti utilitas Mapshaper.org open source, atau di BigQuery menggunakan ST_Simplify pada geometri poligon yang kompleks.
- Buat cluster titik yang sangat padat sebelum mengupload file. Anda dapat melakukannya di alat geospasial pilihan Anda, seperti fungsi cluster turf.js open source, atau di BigQuery menggunakan ST_CLUSTERDBSCAN pada geometri titik padat.
Lihat panduan tambahan tentang praktik terbaik set data di artikel Memvisualisasikan data dengan Set Data dan BigQuery.
Persyaratan GeoJSON
Maps Datasets API mendukung spesifikasi GeoJSON saat ini. Maps Datasets API juga mendukung file GeoJSON yang berisi salah satu jenis objek berikut:
- Objek geometri. Objek geometri adalah bentuk spasial, yang digambarkan sebagai gabungan titik, garis, dan poligon dengan lubang opsional.
- Objek fitur. Objek fitur berisi geometri beserta pasangan nama/nilai tambahan, yang memiliki arti khusus untuk aplikasi.
- Koleksi fitur. Koleksi fitur adalah sekumpulan objek fitur.
Maps Datasets API tidak mendukung file GeoJSON yang memiliki data dalam sistem referensi koordinat (CRS) selain WGS84.
Untuk mengetahui informasi selengkapnya tentang GeoJSON, lihat Dokumen RFC 7946.
Persyaratan KML
Maps Datasets API memiliki persyaratan berikut:
- Semua URL harus bersifat lokal (atau relatif) terhadap file tersebut.
- Geometri titik, garis, dan poligon didukung.
- Semua atribut data dianggap sebagai string.
- Ikon atau
<styleUrl>
yang ditentukan di luar file. - Network link, seperti
<NetworkLink>
- Overlay bumi, seperti
<GroundOverlay>
- Geometri 3D atau tag terkait ketinggian seperti
<altitudeMode>
- Spesifikasi kamera seperti
<LookAt>
- Gaya yang ditentukan di dalam file KML.
Persyaratan CSV
Untuk file CSV, nama kolom yang didukung tercantum di bawah ini sesuai urutan prioritas:
latitude
,longitude
lat
,long
x
,y
wkt
(Well-Known Text)address
,city
,state
,zip
address
- Satu kolom yang berisi semua informasi alamat, seperti
1600 Amphitheatre Parkway Mountain View, CA 94043
Misalnya, file Anda berisi kolom bernama x
, y
, dan wkt
.
Karena x
dan y
memiliki prioritas yang lebih tinggi, sebagaimana ditentukan oleh
urutan nama kolom yang didukung dalam daftar di atas, nilai dalam kolom x
dan y
akan digunakan dan kolom wkt
akan diabaikan.
Selain itu:
- Setiap nama kolom hanya boleh untuk satu kolom. Artinya, Anda tidak dapat memiliki kolom bernama
xy
yang berisi data koordinat x dan y. Koordinat x dan y harus berada dalam kolom terpisah. - Nama kolom tidak peka huruf besar/kecil.
- Urutan nama kolom tidak akan memengaruhi apa pun. Misalnya, jika file CSV Anda berisi kolom
lat
danlong
, keduanya dapat muncul dalam urutan apa pun.
Menangani error upload data
Saat mengupload data ke set data, Anda mungkin mengalami salah satu error umum yang dijelaskan di bagian ini.
Error GeoJSON
Error GeoJSON umum mencakup:
- Kolom
type
tidak ada, atautype
bukan string. File data GeoJSON yang diupload harus berisi kolom string dengan namatype
sebagai bagian dari definisi Objek fitur dan Objek geometri masing-masing.
Error KML
Error KML umum mencakup:
- File data tidak boleh berisi salah satu fitur KML yang tidak didukung yang tercantum di atas. Jika tidak, impor data mungkin akan gagal.
Error CSV
Error CSV umum mencakup:
- Beberapa baris tidak memiliki nilai untuk kolom geometri. Semua baris dalam file CSV harus berisi
nilai yang tidak kosong untuk kolom geometri. Kolom geometri mencakup:
latitude
,longitude
lat
,long
x
,y
wkt
address
,city
,state
,zip
address
- Satu kolom yang berisi semua informasi alamat, seperti
1600 Amphitheatre Parkway Mountain View, CA 94043
- Jika
x
dany
adalah kolom geometri Anda, pastikan bahwa unitnya adalah bujur dan lintang. Beberapa set data publik menggunakan sistem koordinat yang berbeda di bagian headerx
dany
. Jika unit yang salah digunakan, set data mungkin berhasil diimpor, tetapi data yang dirender dapat menampilkan titik set data di lokasi yang tidak terduga.
Membuat set data
Buat set data dengan mengirim permintaan POST
ke endpoint set data:
https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets
Teruskan isi JSON ke permintaan yang menentukan set data. Anda harus:
Tentukan
displayName
set data. NilaidisplayName
harus unik untuk semua set data.Tetapkan
usage
keUSAGE_DATA_DRIVEN_STYLING
.
Contoh:
curl -X POST -d '{ "displayName": "My Test Dataset", "usage": "USAGE_DATA_DRIVEN_STYLING" }' \ -H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $TOKEN" \ https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets
Respons berisi ID set data, dalam bentuk
projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID
beserta informasi tambahan. Gunakan ID set data saat membuat permintaan untuk
memperbarui atau mengubah set data.
{ "name": "projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46", "displayName": "My Test Dataset", "usage": [ "USAGE_DATA_DRIVEN_STYLING" ], "createTime": "2022-08-15T17:50:00.189682Z", "updateTime": "2022-08-15T17:50:00.189682Z" }
Mengunggah data ke {i>dataset<i}
Setelah Anda membuat set data, upload data dari Google Cloud Storage atau dari file lokal ke set data.
Mengupload data dari Cloud Storage
Anda mengupload dari Cloud Storage ke set data dengan mengirimkan permintaan POST
ke endpoint set data yang juga menyertakan ID set data:
https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import
Dalam isi permintaan JSON:
Gunakan
inputUri
untuk menentukan jalur file ke resource yang berisi data di Cloud Storage. Jalur ini akan terlihat sepertigs://GCS_BUCKET/FILE
.Pengguna yang mengajukan permintaan memerlukan peran Storage Object Viewer, atau peran lain yang mencakup izin
storage.objects.get
. Untuk mengetahui informasi selengkapnya tentang cara mengelola akses ke Cloud Storage, lihat Ringkasan kontrol akses.Gunakan
fileFormat
untuk menentukan format file data sebagai:FILE_FORMAT_GEOJSON
(file GeoJson),FILE_FORMAT_KML
(file KML), atauFILE_FORMAT_CSV
(file CSV).
Contoh:
curl -X POST -d '{ "gcs_source":{ "inputUri": "gs://my_bucket/my_csv_file", "fileFormat": "FILE_FORMAT_CSV" } }' \ -H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \ -H "content-type: application/json" \ -H "Authorization: Bearer $TOKEN" \ https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:import
Responsnya berupa:
{ "name": "projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@VERSION_NUMBER" }
Mengupload data dari file
Untuk mengupload data dari file, kirim permintaan POST
HTTP ke endpoint set data yang juga menyertakan ID set data:
https://mapsplatformdatasets.googleapis.com/upload/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import
Permintaan berisi:
Header
Goog-Upload-Protocol
disetel kemultipart
.Properti
metadata
yang menentukan jalur ke file yang menentukan jenis data yang akan diupload, baik sebagai:FILE_FORMAT_GEOJSON
(file GeoJSON),FILE_FORMAT_KML
(file KML), atauFILE_FORMAT_CSV
(file CSV).Isi file ini memiliki format berikut:
{"local_file_source": {"file_format": "FILE_FORMAT_GEOJSON"}}
Properti
rawdata
yang menentukan jalur ke file GeoJSON, KML, atau CSV yang berisi data yang akan diupload.
Permintaan berikut menggunakan opsi curl -F
untuk menentukan jalur ke kedua
file:
curl -X POST \ -H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \ -H "Authorization: Bearer $TOKEN" \ -H "X-Goog-Upload-Protocol: multipart" \ -F "metadata=@csv_metadata_file" \ -F "rawdata=@csv_data_file" \ https://mapsplatformdatasets.googleapis.com/upload/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:import
Responsnya berupa:
{ "name": "projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@VERSION_NUMBER" }
Mengunggah data baru ke {i>dataset<i}
Setelah Anda membuat set data dan berhasil mengupload data awal, status set data akan ditetapkan ke STATE_COMPLETED
. Artinya, set data siap
digunakan di aplikasi Anda. Untuk menentukan state
set data, lihat Mendapatkan
set data.
Anda juga dapat mengupload data baru ke set data untuk membuat set data versi baru. Untuk mengupload data baru, gunakan proses yang sama seperti yang Anda lakukan pada Mengupload data dari Cloud Storage atau Mengupload data dari file, dan menentukan data baru yang akan diupload.
Jika data baru berhasil diupload:
Status set data versi baru ditetapkan ke
STATE_COMPLETED
.Versi baru akan menjadi versi "aktif" dan merupakan versi yang digunakan oleh aplikasi Anda.
Jika terjadi error saat mengupload:
Status versi set data baru disetel ke salah satu status berikut:
STATE_IMPORT_FAILED
STATE_PROCESSING_FAILED
STATE_PUBLISHING_FAILED
STATE_DELETION_FAILED
Versi set data sebelumnya yang berhasil akan tetap sebagai versi "aktif" dan merupakan versi yang digunakan oleh aplikasi Anda.