Tạo tập dữ liệu

Tạo tập dữ liệu là quy trình gồm hai bước:

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

  2. Tạo yêu cầu tải dữ liệu lên tập dữ liệu.

Sau lần 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 phiên bản mới của tập dữ liệu.

Tạo tập dữ liệu

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

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

Truyền nội dung JSON cho 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 mọi 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"

Câu trả lời có chứa mã nhận dạng 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 bạn tạo tập dữ liệu, hãy tải dữ liệu lên từ Bộ nhớ Google Cloud hoặc từ một tệp cục bộ vào tập dữ liệu.

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

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

Bạn tải từ Cloud Storage lên tập dữ liệu bằng cách gửi yêu cầu POST đến tập dữ liệu điểm cuối 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ó trong biểu mẫu gs://GCS_BUCKET/FILE.

    Người dùng đưa ra yêu cầu sẽ yêu cầu Đối tượng bộ nhớ Người xem 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 Tổng quan về kiểm soát quyền truy cập.

  • Sử dụng fileFormat để chỉ định định dạng tệp của dữ liệu: 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"

Câu trả lời có dạng:

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

Tải dữ liệu lên từ mộ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 tập dữ liệu điểm cuối cũng bao gồm 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 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 giá trị loại dữ liệu cần tải lên, như: 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 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"

Câu trả lời có dạng:

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

Xem trạng thái xử lý dữ liệu

Hoạt động tải lên không đồng bộ. Tức là sau lệnh gọi API để tải lên dữ liệu mà tập dữ liệu trả về, sau đó bạn phải thăm dò tập dữ liệu để xác định liệu việc nhập và xử lý dữ liệu thành công hay thất bại.

Để xác định state của tập dữ liệu, hãy sử dụng Lấy tập dữ liệu. Ví dụ: trong khi dữ liệu đang được đã xử lý, state sẽ được đặt thành STATE_PROCESSING. Khi tập dữ liệu đã sẵn sàng để dùng trong ứng dụng, state đượ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 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 xử lý dữ liệu không thành công, state được đặt thành một giá trị không phải là 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, sau đó thực hiện hàm GET yêu cầu lấy thông tin chi tiết về tập dữ liệu. Cùng với thuộc tính state, Nội dung phản hồi cũng bao gồm một thuộc tính errorMessage duy nhất có chứa nội dung mô tả 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 nhập và xử lý dữ liệu không thành công, tài sản errorMessage sẽ chứa một thông báo mô tả lỗi. Tuy nhiên, một thông báo lỗi thì không nhất thiết phải cung cấp đủ thông tin để xác định và khắc phục vấn đề.

Để biết thông tin đầy đủ về lỗi, hãy gọi fetchDatasetErrors API. API này trả về tất cả cá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ảng này chứa tối đa 50 lỗi của loại Status mỗi lệnh gọi và hỗ trợ tối đa 500 lỗi tổng cộng:

{
  "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 trang thì phản hồi sẽ chứa mã thông báo trang trong trường nextPageToken. Truyền giá trị đó vào tham số truy vấn pageToken của lệnh gọi tiếp theo để lấy trang lỗi tiếp theo. Khi nextPageToken trống sẽ không có trang nào khác.

Ví dụ: để lấy mã lỗi từ trang tiếp theo trả lời:

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 lên dữ liệu ban đầu thành công, trạng thái của tập dữ liệu đượ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 .

Bạn cũng có thể tải dữ liệu mới lên tập dữ liệu để tạo 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ư bạn đã làm để Tải dữ liệu lên từ Cloud Storage hoặc Tải dữ liệu lên từ tệp, và chỉ định dữ liệu mới cần tải lên.

Nếu dữ liệu mới được 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 "đang hoạt động" và là phiên bản được sử dụng bởi .

Nếu có lỗi trong quá trình 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.