Tạo tập dữ liệu

Quy trình tạo tập dữ liệu gồm 2 bước:

  1. Đưa ra yêu cầu tạo tập dữ liệu.

  2. Đưa ra yêu cầu tải dữ liệu lên tập dữ liệu.

Sau khi tải dữ liệu ban đầu lên, bạn có thể tải dữ liệu mới lên tập dữ liệu để tạo một phiên bản mới của tập dữ liệu.

Tạo tập dữ liệu

Tạo một tập dữ liệu bằng cách gửi yêu cầu POST đến điểm cuối datasets:

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets

Truyền một nội dung JSON vào yêu cầu xác định tập dữ liệu. Bạn phải:

  • Chỉ định displayName của tập dữ liệu. Giá trị của displayName phải là duy nhất cho tất cả các tập dữ liệu.

  • Đặt usage thành USAGE_DATA_DRIVEN_STYLING.

Ví dụ:

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"

Phản hồi chứa mã nhận dạng của tập dữ liệu, ở dạng projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID cùng với thông tin bổ sung. Sử dụng mã nhận dạng tập dữ liệu khi đưa ra yêu cầu cập nhật hoặc sửa đổi tập dữ liệu.

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

Tải dữ liệu lên tập dữ liệu

Sau khi tạo tập dữ liệu, hãy tải dữ liệu lên tập dữ liệu từ Google Cloud Storage hoặc từ một tệp cục bộ.

Thao tác tải lên là không đồng bộ. Sau khi bạn tải dữ liệu lên, dữ liệu sẽ được truyền và xử lý. Điều đó có nghĩa là bạn phải đưa ra yêu cầu HTTP GET để theo dõi trạng thái của tập dữ liệu nhằm xác định thời điểm tập dữ liệu sẵn sàng sử dụng hoặc nếu có lỗi. Để biết thêm thông tin, hãy xem phần Lấy trạng thái xử lý dữ liệu.

Tải dữ liệu lên từ Cloud Storage

Bạn tải lên từ Cloud Storage vào tập dữ liệu bằng cách gửi yêu cầu POST đến điểm cuối datasets (tập dữ liệu) cũng bao gồm mã nhận dạng của tập dữ liệu:

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import

Trong nội dung yêu cầu JSON:

  • Sử dụng inputUri để chỉ định đường dẫn tệp đến tài nguyên chứa dữ liệu trong Cloud Storage. Đường dẫn này có dạng gs://GCS_BUCKET/FILE.

    Người dùng đưa ra yêu cầu cần có vai trò Storage Object Viewer (Người xem đối tượng lưu trữ) hoặc bất kỳ vai trò nào khác có quyền storage.objects.get. Để biết thêm thông tin về cách quản lý quyền truy cập vào Cloud Storage, hãy xem phần Tổng quan về quyền kiểm soát truy cập.

  • Sử dụng fileFormat để chỉ định định dạng tệp của dữ liệu là: FILE_FORMAT_GEOJSON (tệp GeoJson), FILE_FORMAT_KML (tệp KML) hoặc FILE_FORMAT_CSV (tệp CSV).

Ví dụ:

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"

Phản hồi có dạng:

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

Tải dữ liệu lên từ tệp

Để tải dữ liệu lên từ một tệp, hãy gửi yêu cầu HTTP POST đến điểm cuối datasets (tập dữ liệu) cũng bao gồm cả mã nhận dạng của tập dữ liệu::

https://mapsplatformdatasets.googleapis.com/upload/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import

Yêu cầu này chứa:

  • Tiêu đề Goog-Upload-Protocol được đặt thành multipart.

  • Thuộc tính metadata chỉ định đường dẫn đến một tệp chỉ định loại dữ liệu cần tải lên, dưới dạng: FILE_FORMAT_GEOJSON (tệp GeoJSON), FILE_FORMAT_KML (tệp KML) hoặc FILE_FORMAT_CSV (tệp CSV).

    Nội dung của tệp này có định dạng sau:

    {"local_file_source": {"file_format": "FILE_FORMAT_GEOJSON"}}

  • Thuộc tính rawdata chỉ định đường dẫn đến tệp GeoJSON, KML hoặc CSV chứa dữ liệu cần tải lên.

Yêu cầu sau đây sử dụng tuỳ chọn curl -F để chỉ định đường dẫn đến 2 tệp:

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"

Phản hồi có dạng:

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

Lấy trạng thái xử lý dữ liệu

Thao tác tải lên là không đồng bộ. Điều đó có nghĩa là sau khi lệnh gọi API để tải dữ liệu lên tập dữ liệu trả về, bạn phải thăm dò tập dữ liệu để xác định xem quá trình xử lý và nhập dữ liệu có thành công hay không.

Để xác định state của tập dữ liệu, hãy dùng Lấy một tập dữ liệu. Ví dụ: trong khi dữ liệu đang được xử lý, state được đặt thành STATE_PROCESSING. Khi tập dữ liệu đã sẵn sàng để sử dụng trong ứng dụng của bạn, state sẽ được đặt thành STATE_COMPLETED.

Ví dụ: thực hiện lệnh gọi GET trên tập dữ liệu:

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"

Để tải lên thành công, state của tập dữ liệu phải là 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
}

Khi quá trình xử lý dữ liệu không thành công, state sẽ được đặt thành một giá trị khác với STATE_COMPLETED, chẳng hạn như STATE_PUBLISHING_FAILED hoặc bất kỳ trạng thái nào kết thúc bằng chuỗi _FAILED.

Ví dụ: bạn tải dữ liệu lên một tập dữ liệu rồi thực hiện yêu cầu GET để lấy thông tin chi tiết về tập dữ liệu đó. Cùng với thuộc tính state, phản hồi cũng bao gồm một thuộc tính errorMessage duy nhất chứa nội dung mô tả về lỗi.

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

Nhận lỗi xử lý dữ liệu

Khi quá trình xử lý và truyền dữ liệu không thành công, thuộc tính errorMessage sẽ chứa một thông báo duy nhất mô tả lỗi. Tuy nhiên, một thông báo lỗi duy nhất không nhất thiết cung cấp đủ thông tin để xác định và khắc phục vấn đề.

Để nhận thông tin đầy đủ về lỗi, hãy gọi API fetchDatasetErrors. API này trả về tất cả lỗi xử lý dữ liệu liên quan đến một tập dữ liệu:

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"

Phản hồi chứa mảng errors. Mỗi lệnh gọi, mảng này chứa tối đa 50 lỗi thuộc loại Status và hỗ trợ tổng cộng tối đa 500 lỗi:

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

Nếu có hơn 50 lỗi (tức là có nhiều hơn 1 trang lỗi), thì phản hồi sẽ chứa mã thông báo trang trong trường nextPageToken. Truyền giá trị đó trong tham số truy vấn pageToken của một lệnh gọi tiếp theo để nhận trang lỗi tiếp theo. Khi nextPageToken trống, tức là không còn trang nào nữa.

Ví dụ: để nhận trang lỗi tiếp theo bằng mã thông báo từ phản hồi trước:

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"

Theo mặc định, phản hồi chứa tối đa 50 lỗi trên mỗi trang. Sử dụng tham số truy vấn pageSize để kiểm soát kích thước trang.

Tải dữ liệu mới lên tập dữ liệu

Sau khi bạn tạo tập dữ liệu và tải dữ liệu ban đầu lên thành công, trạng thái của tập dữ liệu sẽ được đặt thành STATE_COMPLETED. Điều đó có nghĩa là tập dữ liệu đã sẵn sàng để sử dụng trong ứng dụng của bạn. Để xác định state của tập dữ liệu, hãy xem phần Nhận tập dữ liệu.

Bạn cũng có thể tải dữ liệu mới lên tập dữ liệu để tạo một phiên bản mới của tập dữ liệu. Để tải dữ liệu mới lên, hãy sử dụng quy trình tương tự như khi bạn Tải dữ liệu lên từ Cloud Storage hoặc Tải dữ liệu lên từ một tệp, đồng thời chỉ định dữ liệu mới cần tải lên.

Nếu dữ liệu mới tải lên thành công:

  • Trạng thái của phiên bản mới của tập dữ liệu được đặt thành STATE_COMPLETED.

  • Phiên bản mới sẽ trở thành phiên bản "đang hoạt động" và là phiên bản mà ứng dụng của bạn sử dụng.

Nếu xảy ra lỗi khi tải lên:

  • Trạng thái của phiên bản tập dữ liệu mới được đặt thành một trong các trạng thái sau:

    • STATE_IMPORT_FAILED
    • STATE_PROCESSING_FAILED
    • STATE_PUBLISHING_FAILED
    • STATE_DELETION_FAILED

  • Phiên bản thành công của tập dữ liệu trước đó vẫn là phiên bản "đang hoạt động" và là phiên bản mà ứng dụng của bạn sử dụng.