Việc tạo tập dữ liệu là một quá trình gồm hai bước:
Gửi 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.
Điều kiện tiên quyết
Khi tạo tập dữ liệu:
- Tên hiển thị phải là duy nhất trong dự án trên Google Cloud.
- Tên hiển thị phải dưới 64 byte (Vì các ký tự này được biểu thị bằng UTF-8, nên trong một số ngôn ngữ, mỗi ký tự có thể được biểu thị bằng nhiều byte).
- Nội dung mô tả phải dưới 1000 byte.
Khi tải dữ liệu lên:
- Các loại tệp được hỗ trợ là CSV, GeoJSON và KML.
- Kích thước tệp tối đa được hỗ trợ là 350 MB.
- Tên cột thuộc tính không được bắt đầu bằng chuỗi "?_".
- Hình học ba chiều không được hỗ trợ. Trong đó bao gồm hậu tố "Z" ở định dạng WKT và toạ độ cao độ ở định dạng GeoJSON.
Yêu cầu đối với GeoJSON
API Tập dữ liệu Maps hỗ trợ thông số kỹ thuật GeoJSON hiện tại. API Tập dữ liệu Maps cũng hỗ trợ các tệp GeoJSON chứa bất kỳ loại đối tượng nào sau đây:
- Đối tượng hình học. Đối tượng hình học là một hình dạng không gian, được mô tả là một sự kết hợp giữa các điểm, đường kẻ và đa giác có các lỗ tuỳ chọn.
- Đối tượng làm nổi bật. Đối tượng tính năng chứa một hình học cùng với các cặp tên/giá trị bổ sung, có ý nghĩa dành riêng cho ứng dụng.
- Bộ sưu tập tính năng. Bộ sưu tập đối tượng là một tập hợp các đối tượng đối tượng.
API Tập dữ liệu Maps không hỗ trợ các tệp GeoJSON có dữ liệu trong hệ thống tham chiếu toạ độ (CRS) khác với WGS84.
Để biết thêm thông tin về GeoJSON, hãy xem Tuân thủ RFC 7946.
Yêu cầu về KML
API Tập dữ liệu Maps có các yêu cầu sau:
- Tất cả URL phải là URL cục bộ (hoặc có liên quan) đến chính tệp đó.
- Hình học điểm, đường và đa giác được hỗ trợ.
- Tất cả các thuộc tính dữ liệu đều được coi là chuỗi.
- Biểu tượng hoặc
<styleUrl>
được xác định bên ngoài tệp. - Đường liên kết mạng, chẳng hạn như
<NetworkLink>
- Lớp phủ mặt đất, chẳng hạn như
<GroundOverlay>
- Hình học 3D hoặc bất kỳ thẻ nào liên quan đến độ cao, chẳng hạn như
<altitudeMode>
- Các thông số kỹ thuật của camera, chẳng hạn như
<LookAt>
- Kiểu được xác định bên trong tệp KML.
Yêu cầu về tệp CSV
Đối với tệp CSV, các tên cột được hỗ trợ được liệt kê theo thứ tự ưu tiên dưới đây:
latitude
,longitude
lat
,long
x
,y
wkt
(Văn bản quen thuộc)address
,city
,state
,zip
address
- Một cột duy nhất chứa tất cả thông tin địa chỉ, chẳng hạn như
1600 Amphitheatre Parkway Mountain View, CA 94043
Ví dụ: tệp của bạn chứa các cột có tên x
, y
và wkt
.
Vì x
và y
có mức độ ưu tiên cao hơn, như được xác định theo thứ tự của các tên cột được hỗ trợ trong danh sách ở trên, nên các giá trị trong cột x
và y
sẽ được sử dụng và cột wkt
sẽ bị bỏ qua.
Ngoài ra:
- Tên mỗi cột phải thuộc về một cột duy nhất. Điều đó nghĩa là bạn không thể có một cột tên là
xy
chứa cả dữ liệu toạ độ x và y. Các toạ độ x và y phải nằm trong các cột riêng biệt. - Tên cột không phân biệt chữ hoa chữ thường.
- Thứ tự của các tên cột không quan trọng. Ví dụ: nếu tệp CSV của bạn chứa
các cột
lat
vàlong
, các cột này có thể xuất hiện theo thứ tự bất kỳ.
Xử lý lỗi tải dữ liệu lên
Khi tải dữ liệu lên một tập dữ liệu, bạn có thể gặp một trong các lỗi phổ biến được mô tả trong phần này.
Lỗi GeoJSON
Các lỗi GeoJSON thường gặp bao gồm:
- Thiếu trường
type
hoặctype
không phải là một chuỗi. Tệp dữ liệu GeoJSON đã tải lên phải chứa một trường chuỗi có têntype
trong mỗi đối tượng Feature và định nghĩa đối tượng Hình học.
Lỗi KML
Các lỗi KML thường gặp bao gồm:
- Tệp dữ liệu không được chứa bất kỳ tính năng KML nào không được hỗ trợ nêu trên, nếu không, quá trình nhập dữ liệu có thể không thành công.
Lỗi CSV
Các lỗi thường gặp về tệp CSV bao gồm:
- Một số hàng thiếu giá trị cho một cột hình học. Tất cả các hàng trong tệp CSV phải chứa giá trị không được để trống cho các cột hình học. Các cột hình học bao gồm:
latitude
,longitude
lat
,long
x
,y
wkt
address
,city
,state
,zip
address
- Một cột duy nhất chứa tất cả thông tin địa chỉ, chẳng hạn như
1600 Amphitheatre Parkway Mountain View, CA 94043
- Nếu
x
vày
là các cột hình học, hãy đảm bảo rằng các đơn vị là kinh độ và vĩ độ. Một số tập dữ liệu công khai sử dụng các hệ toạ độ khác nhau trong các tiêu đềx
vày
. Nếu bạn sử dụng sai đơn vị, thì tập dữ liệu có thể được nhập thành công nhưng dữ liệu được hiển thị có thể cho thấy các điểm trong tập dữ liệu ở vị trí không mong muốn.
Gửi yêu cầ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 của tập dữ liệu:
https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets
Truyền nội dung JSON đến 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ủadisplayName
phải là duy nhất đối với tất cả các tập dữ liệu.Đặt
usage
thànhUSAGE_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ã 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ạo yêu cầu 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.
Tải dữ liệu lên từ Cloud Storage
Bạn tải tập dữ liệu lên từ Cloud Storage bằng cách gửi yêu cầu POST
đến điểm cuối của tập dữ liệu. Điểm cuối này 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ạnggs://GCS_BUCKET/FILE
.Người dùng đưa ra yêu cầu cần có vai trò Storage Object xem (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 bài viết Tổng quan về chế độ 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 dưới dạng:FILE_FORMAT_GEOJSON
(tệp GeoJson),FILE_FORMAT_KML
(tệp KML) hoặcFILE_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 của 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 bao gồm:
Tiêu đề
Goog-Upload-Protocol
được đặt thànhmultipart
.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ạngFILE_FORMAT_GEOJSON
(tệp GeoJSON),FILE_FORMAT_KML
(tệp KML) hoặcFILE_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" }