Tạo tập dữ liệu là quy trình gồm hai bước:
Đưa ra 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.
Đ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 Google Cloud của bạn.
- Tên hiển thị phải nhỏ hơn 64 byte (Vì các ký tự này được biểu thị bằng UTF-8, ở 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 nhỏ hơn 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 3 chiều không được hỗ trợ. bao gồm cả "Z" hậu tố ở định dạng WKT, và toạ độ cao độ ở định dạng GeoJSON.
Các phương pháp hay nhất để chuẩn bị dữ liệu
Nếu dữ liệu nguồn của bạn phức tạp hoặc lớn, chẳng hạn như các điểm dày đặc, chuỗi đường dài hoặc đa giác (thường có kích thước tệp nguồn lớn hơn 50 MB thuộc danh mục này), hãy cân nhắc đơn giản hoá dữ liệu trước khi tải lên để đạt được hiệu suất tốt nhất trong bản đồ trực quan.
Dưới đây là một số phương pháp hay nhất để chuẩn bị dữ liệu:
- Giảm thiểu các thuộc tính của tính năng. Chỉ giữ lại các thuộc tính của đối tượng cần thiết để tạo kiểu bản đồ của bạn, ví dụ: "id" và "category". Bạn có thể kết hợp các thuộc tính khác với một đối tượng trong ứng dụng bằng cách sử dụng các kiểu theo hướng dữ liệu trên một khoá nhận dạng duy nhất. Ví dụ: hãy xem Xem dữ liệu của bạn theo thời gian thực bằng tính năng Tạo kiểu dựa trên dữ liệu.
- Sử dụng các kiểu dữ liệu đơn giản cho đối tượng thuộc tính nếu có thể, chẳng hạn như số nguyên, để giảm thiểu kích thước ô và cải thiện hiệu suất của bản đồ.
- Đơn giản hoá các hình học phức tạp trước khi tải tệp lên. Bạn có thể thực hiện việc này trong công cụ không gian địa lý mà bạn chọn, chẳng hạn như mã nguồn mở Tiện ích Mapshaper.org hoặc trong BigQuery sử dụng ST_Simplify trên hình học đa giác phức tạp.
- Nhóm các điểm rất dày đặc trước khi tải tệp lên. Bạn có thể thực hiện việc này trong công cụ không gian địa lý mà bạn chọn, chẳng hạn như mã nguồn mở hàm cụm turf.js hoặc trong BigQuery sử dụng ST_CLUSTERDBSCAN trên hình học điểm dày đặc.
Xem thêm hướng dẫn về các phương pháp hay nhất về tập dữ liệu trong Trực quan hoá dữ liệu bằng Tập dữ liệu và BigQuery.
Yêu cầu về GeoJSON
Maps Datasets API hỗ trợ dữ liệu hiện tại Quy cách GeoJSON. Maps Datasets API 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 điểm hợp nhất gồm các điểm, đường và đa giác có lỗ tuỳ chọn.
- Đối tượng đối tượng. Đối tượng đối tượng chứa một hình học cộng thêm các cặp tên/giá trị, có ý nghĩa dành riêng cho ứng dụng.
- Bộ sưu tập tính năng. Tập hợp tính năng là một tập hợp các đối tượng tính năng.
Maps Datasets API 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 đối với KML
API Tập dữ liệu Maps có các yêu cầu sau:
- Tất cả URL phải cục bộ (hoặc tương đối) với chính tệp đó.
- Các hình học điểm, đường và đa giác được hỗ trợ.
- Tất cả thuộc tính dữ liệu đều được coi là chuỗi.
- Các 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 như
<altitudeMode>
- Thông số kỹ thuật của camera, chẳng hạn như
<LookAt>
- Kiểu được xác định trong tệp KML.
Yêu cầu về tệp CSV
Đối với tệp CSV, tên cột được hỗ trợ được liệt kê theo mức độ ưu tiên bên dưới:
latitude
,longitude
lat
,long
x
,y
wkt
(Văn bản dễ biết)address
,city
,state
,zip
address
- Một cột chứa tất cả thông tin về đị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
tên cột được hỗ trợ trong danh sách ở trên, giá trị trong cột x
và y
được sử dụng và cột wkt
bị bỏ qua.
Ngoài ra:
- Mỗi tên cột phải thuộc về một cột duy nhất. Tức là bạn không thể có cột có tên
xy
chứa cả dữ liệu toạ độ x và y. 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ự tên cột không quan trọng. Ví dụ: nếu tệp CSV của bạn chứa
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 phải một trong những lỗi phổ biến như mô tả trong bài viết này .
Lỗi GeoJSON
Các lỗi GeoJSON phổ biến bao gồm:
- Thiếu trường
type
hoặctype
không phải là một chuỗi. URL được tải lên Tệp dữ liệu GeoJSON phải chứa một trường chuỗi có têntype
trong mỗi chuỗi Định nghĩa đối tượng đối tượng và đối tượng Hình học.
Lỗi KML
Các lỗi KML phổ biến bao gồm:
- Tệp dữ liệu không được chứa bất kỳ đối tượng KML nào không được hỗ trợ nêu trên, nếu không có thể không nhập được dữ liệu.
Lỗi CSV
Các lỗi CSV thường gặp bao gồm:
- Một số hàng bị 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 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 chứa tất cả thông tin về địa chỉ, chẳng hạn như
1600 Amphitheatre Parkway Mountain View, CA 94043
- Nếu
x
vày
là cột hình học, hãy đảm bảo các đơn vị kinh độ và vĩ độ. Một số tập dữ liệu công khai sử dụng các hệ thống toạ độ khác nhau dưới các tiêu đềx
vày
. Nếu sử dụng sai đơn vị, tập dữ liệu có thể nhập nhưng dữ liệu hiển thị có thể cho thấy các điểm tập dữ liệu ở những vị trí không mong muốn.
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ủadisplayName
phải là duy nhất cho mọi 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
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.
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ẫugs://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
. Cho 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ặ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
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ànhmultipart
.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ặ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
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" }
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 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.