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 upload data awal, Anda dapat mengupload data baru ke set data untuk membuat set data versi baru.

Membuat set data

Buat set data dengan mengirim permintaan POST ke endpoint datasets:

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. Nilai displayName harus unik untuk semua set data.

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

Mengupload data ke set data

Setelah Anda membuat set data, upload data dari Google Cloud Storage atau dari file lokal ke set data.

Operasi upload bersifat asinkron. Setelah Anda mengupload data, data tersebut akan ditransfer dan diproses. Artinya, Anda harus membuat permintaan GET HTTP untuk memantau status set data guna menentukan kapan set data siap digunakan atau apakah ada error. Untuk mengetahui informasi selengkapnya, lihat Mendapatkan status pemrosesan data.

Mengupload data dari Cloud Storage

Anda mengupload dari Cloud Storage ke set data dengan mengirimkan permintaan POST ke endpoint datasets 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 seperti gs://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 pengelolaan 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 dalam bentuk:

{
  "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 ditetapkan 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 dua 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 dalam bentuk:

{
  "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 set data ditampilkan, Anda harus melakukan polling pada set data untuk menentukan apakah penyerapan dan pemrosesan data berhasil atau gagal.

Untuk menentukan state set data, gunakan Mendapatkan set data. Misalnya, saat data sedang diproses, state ditetapkan ke STATE_PROCESSING. Saat set data siap digunakan di aplikasi Anda, state ditetapkan 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"

Untuk upload yang 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 mengupload data ke set data, lalu membuat permintaan GET untuk mendapatkan detail set data. Bersama dengan properti state, respons juga menyertakan satu properti errorMessage yang berisi deskripsi error.

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

Jika penyerapan dan pemrosesan data gagal, properti errorMessage akan berisi satu pesan yang menjelaskan error. Namun, satu pesan error tidak selalu memberikan informasi yang memadai untuk mengidentifikasi dan memperbaiki masalah.

Untuk mendapatkan informasi error lengkap, panggil API fetchDatasetErrors. 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"

Responsnya berisi array errors. Array ini berisi hingga 50 error jenis Status per panggilan, dan mendukung total hingga 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, yang berarti lebih dari satu halaman error, respons akan berisi token halaman di kolom nextPageToken. Teruskan nilai tersebut dalam parameter kueri pageToken dari panggilan berikutnya untuk mendapatkan halaman error berikutnya. Jika nextPageToken kosong, tidak ada lagi halaman.

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

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.

Mengupload data baru ke set data

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 versi set data baru. Untuk mengupload data baru, gunakan proses yang sama seperti yang Anda lakukan untuk Mengupload data dari Cloud Storage atau Mengupload data dari file, dan tentukan data baru yang akan diupload.

Jika data baru berhasil diupload:

  • Status versi baru set data 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 ditetapkan ke salah satu status berikut:

    • STATE_IMPORT_FAILED
    • STATE_PROCESSING_FAILED
    • STATE_PUBLISHING_FAILED
    • STATE_DELETION_FAILED

  • Versi set data sebelumnya yang berhasil tetap menjadi versi "aktif" dan merupakan versi yang digunakan oleh aplikasi Anda.