Trang này được dịch bởi Cloud Translation API.

Tạo tập dữ liệu

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

Tạo yêu cầu tạo tập dữ liệu.
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 datasets (tập dữ liệu):

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

Truyền phần 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.

Lưu ý: USAGE_DATA_DRIVEN_STYLING là giá trị duy nhất được hỗ trợ cho usage.

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 bạn tạo tập dữ liệu, hãy tải dữ liệu lên từ Google Cloud Storage hoặc từ một tệp cục bộ lên tập dữ liệu.

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 nhập và xử lý. Điều đó có nghĩa là bạn phải tạo một yêu cầu GET HTTP để 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 liệu có lỗi nào không. Để biết thêm thông tin, hãy xem phần Nhận trạng thái xử lý dữ liệu.

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

Bạn tải dữ liệu 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 phần 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ò Người xem đối tượng bộ nhớ 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ề tính năng 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 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 POST HTTP đế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/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 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 như 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 hai 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"
}

Nhận 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ò ý kiến tập dữ liệu để xác định xem quá trình nhập và xử lý dữ liệu có thành công hay không.

Để xác định state của tập dữ liệu, hãy sử dụng tính năng Tải 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, 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 xử lý dữ liệu không thành công, state đượ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, sau đó tạo một 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 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
}

Lỗi xử lý dữ liệu

Khi quá trình nhập và xử lý dữ liệu không thành công, thuộc tính 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 không nhất thiết cung cấp đủ thông tin để xác định và khắc phục sự cố.

Để 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ảng này chứa tối đa 50 lỗi thuộc loại Status cho mỗi lệnh gọi 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 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 lệnh gọi tiếp theo để nhận trang lỗi tiếp theo. Khi nextPageToken trống, sẽ 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 Tải 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 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, rồi 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 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 quá trình tải lên gặp lỗi:

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.