Membuat set data

Membuat set data adalah proses dua langkah:

  1. Buat permintaan untuk membuat set data.

  2. Buat permintaan untuk mengupload data ke set data.

Setelah unggahan data awal, Anda dapat mengunggah data baru ke {i>dataset<i} untuk membuat {i>dataset <i}versi baru.

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

Meneruskan isi JSON ke permintaan yang menentukan set data. Anda harus:

  • Tentukan displayName set data. Nilai displayName harus unik untuk semua {i>dataset<i}.

  • Tetapkan usage ke USAGE_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 {i>dataset<i}.

{
  "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 {i>dataset<i}, unggah data dari Penyimpanan Google Cloud atau dari file lokal ke {i>dataset<i}.

Operasi upload bersifat asinkron. Setelah Anda mengunggah data, diserap dan diproses. Artinya Anda harus membuat permintaan GET HTTP untuk memantau status set data untuk menentukan kapan set data siap digunakan atau apakah dan terjadi error. Untuk mengetahui informasi selengkapnya, lihat Mendapatkan pemrosesan data status.

Mengupload data dari Cloud Storage

Anda mengupload dari Cloud Storage ke set data dengan mengirim permintaan POST ke set data yang juga berisi 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 berbentuk gs://GCS_BUCKET/FILE.

    Pengguna yang mengajukan permintaan memerlukan Objek Penyimpanan Pengakses lihat-saja peran, atau peran lain yang menyertakan izin storage.objects.get. Sebagai 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), atau FILE_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 bisa 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 set data yang juga berisi 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 ke multipart.

  • Properti metadata yang menentukan jalur ke file yang menentukan jenis data yang akan diupload, sebagai: FILE_FORMAT_GEOJSON (file GeoJSON), FILE_FORMAT_KML (file KML), atau FILE_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 keduanya 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 bisa berupa:

{
  "name": "projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@VERSION_NUMBER"
}

Mendapatkan status pemrosesan data

Operasi upload bersifat asinkron. Artinya setelah panggilan API untuk mengupload data ke hasil {i>dataset<i}, Anda kemudian harus mengumpulkan {i>dataset<i} itu untuk menentukan apakah penyerapan dan pemrosesan data berhasil atau gagal.

Untuk menentukan state elemen set data, gunakan Dapatkan set data. Misalnya, saat data diproses, state ditetapkan ke STATE_PROCESSING. Saat set data sudah siap untuk digunakan di aplikasi Anda, state disetel ke STATE_COMPLETED.

Misalnya, lakukan panggilan GET pada set data:

curl -X GET \
  -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \
  -H "Authorization: Bearer $TOKEN" \
  "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46"

Agar upload berhasil, state set data adalah STATE_COMPLETED:

{
  "name": "projects/119757857/datasets/f57074a0-a8b6-403e-9df1-e9fc46",
  "displayName": "My Test Dataset",
  "description": " ",
  "versionId": "837c5a9e-c885-4a5f-a462-7e35673e5218",
  "usage": [
    "USAGE_DATA_DRIVEN_STYLING"
  ],
  "localFileSource": {
    "filename": "Parks_Properties_20240529.csv",
    "fileFormat": "FILE_FORMAT_CSV"
  },
  "createTime": "2024-05-30T16:41:11.130816Z",
  "updateTime": "2024-05-30T16:41:14.416130Z",
  "versionCreateTime": "2024-05-30T16:41:14.416130Z",
  "status": {
    "state": "STATE_COMPLETED",
  },
  "sizeBytes": "6916924",
  "downloadable": true
}

Jika pemrosesan data gagal, state ditetapkan ke nilai selain STATE_COMPLETED, seperti STATE_PUBLISHING_FAILED atau status apa pun yang diakhiri dengan string _FAILED.

Misalnya, Anda mengunggah data ke sebuah {i>dataset<i} dan kemudian membuat pernyataan GET permintaan untuk mendapatkan detail {i>dataset<i}. Bersama dengan properti state, respons juga mencakup satu properti errorMessage yang berisi deskripsi error tersebut.

{
  "name": "projects/119757857/datasets/f57074a0-a8b6-403e-9df1-e9fc46",
  "displayName": "My Test Dataset",
  "description": " ",
  "versionId": "837c5a9e-c885-4a5f-a462-7e35673e5218",
  "usage": [
    "USAGE_DATA_DRIVEN_STYLING"
  ],
  "localFileSource": {
    "filename": "Parks_Properties_20240529.csv",
    "fileFormat": "FILE_FORMAT_CSV"
  },
  "createTime": "2024-05-30T16:41:11.130816Z",
  "updateTime": "2024-05-30T16:41:14.416130Z",
  "versionCreateTime": "2024-05-30T16:41:14.416130Z",
  "status": {
    "state": "STATE_PUBLISHING_FAILED",
    "errorMessage": "INVALID_ARGUMENT: Skipping row because address could not be geocoded: 5521 18 AVENUE (from line 79)"
  },
  "sizeBytes": "6916924",
  "downloadable": true
}

Mendapatkan error pemrosesan data

Saat penyerapan dan pemrosesan data gagal, properti errorMessage berisi satu pesan yang menjelaskan error tersebut. Namun, satu pesan {i>error<i} tidak harus memberikan informasi yang cukup untuk mengidentifikasi dan memperbaiki masalah.

Untuk mendapatkan informasi error yang lengkap, panggil metode fetchDatasetErrors Compute Engine API. API ini menampilkan semua error pemrosesan data yang terkait dengan set data:

curl -X GET \
  -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \
  -H "Authorization: Bearer $TOKEN" \
  "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:fetchDatasetErrors"

Respons berisi array errors. {i>Array<i} ini berisi hingga 50 {i>error<i} dari ketik Status per panggilan, dan mendukung hingga total 500 error:

{
  "nextPageToken": "cigKJkIkMTU3MzM0NjQtYzlmMy00YzYxLWIxM2YtYmVkYjFjYjRkYzRj",
  "errors": [
    {
      "code": 3,
      "message": "INVALID_ARGUMENT: No address was derived from fields 2. (from line 631)"
    },
    {
      "code": 3,
      "message": "INVALID_ARGUMENT: No address was derived from fields 2. (from line 457)"
    },
    {
      "code": 3,
      "message": "INVALID_ARGUMENT: No address was derived from fields 2. (from line 31)"
    },
    ...
  ]
}

Jika ada lebih dari 50 error, artinya lebih dari satu halaman error, respons akan berisi token halaman di kolom nextPageToken. Teruskan nilai tersebut dalam parameter kueri pageToken pada panggilan berikutnya untuk mendapatkan halaman error berikutnya. Bila nextPageToken kosong, tidak ada lagi halaman.

Misalnya, untuk mendapatkan halaman error berikutnya menggunakan token dari respons:

curl -X GET \
  -H "content-type: application/json" \
  -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \
  -H "Authorization: Bearer $TOKEN" \
  "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:fetchDatasetErrors?pageToken=cigKJkIkMTU3MzM0NjQtYzlmMy00YzYxLWIxM2YtYmVkYjFjYjRkYzRj"

Secara default, respons berisi maksimum 50 error per halaman. Gunakan parameter kueri pageSize untuk mengontrol ukuran halaman.

Mengunggah data baru ke {i>dataset<i}

Setelah Anda membuat {i>dataset<i} dan berhasil mengunggah data awal, status set data ditetapkan ke STATE_COMPLETED. Itu berarti {i>dataset<i} siap untuk gunakan dalam aplikasi Anda. Untuk menentukan state set data, lihat Mendapatkan set data.

Anda juga dapat mengunggah data baru ke {i>dataset<i} untuk membuat versi baru dari {i>dataset<i} aslinya. Untuk mengupload data baru, gunakan proses yang sama seperti yang Anda lakukan pada Mengupload data dari Cloud Storage atau Upload 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 menjadi "aktif" dan merupakan versi yang digunakan oleh .

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 memiliki status "aktif" dan merupakan versi yang digunakan oleh aplikasi Anda.