การสร้างชุดข้อมูลเป็นกระบวนการที่มี 2 ขั้นตอน ดังนี้
ส่งคำขอเพื่อสร้างชุดข้อมูล
ส่งคำขอเพื่ออัปโหลดข้อมูลไปยังชุดข้อมูล
หลังจากการอัปโหลดข้อมูลครั้งแรก คุณสามารถอัปโหลดข้อมูลใหม่ไปยังชุดข้อมูลเพื่อสร้าง ชุดข้อมูลเวอร์ชันใหม่
ข้อกำหนดเบื้องต้น
เมื่อสร้างชุดข้อมูลให้ทำดังนี้
- ชื่อที่แสดงต้องไม่ซ้ำกันภายในโปรเจ็กต์ Google Cloud
- ชื่อที่แสดงต้องมีขนาดไม่เกิน 64 ไบต์ (เนื่องจากอักขระเหล่านี้แสดงในรูปแบบ UTF-8 ในบางภาษา อักขระแต่ละตัวอาจแสดงด้วยไบต์หลายไบต์)
- คำอธิบายต้องมีขนาดไม่เกิน 1,000 ไบต์
เมื่ออัปโหลดข้อมูล ให้ทำดังนี้
- ประเภทไฟล์ที่รองรับ ได้แก่ CSV, GeoJSON และ KML
- ขนาดไฟล์สูงสุดที่รองรับคือ 350 MB
- ชื่อคอลัมน์แอตทริบิวต์ต้องไม่ขึ้นต้นด้วยสตริง "?_"
- ไม่สนับสนุนรูปทรงเรขาคณิตสามมิติ ซึ่งรวมถึง "Z" ซึ่งอยู่ในรูปแบบ WKT และพิกัดระดับความสูงในรูปแบบ GeoJSON
แนวทางปฏิบัติแนะนำในการเตรียมข้อมูล
หากข้อมูลต้นฉบับของคุณมีความซับซ้อนหรือมีขนาดใหญ่ เช่น จุดหนาแน่น สตริงเส้นยาว หรือรูปหลายเหลี่ยม (ไฟล์ต้นฉบับที่มีขนาดใหญ่กว่า 50 MB จะจัดอยู่ในหมวดหมู่นี้) ให้ลองลดความซับซ้อนของข้อมูล ก่อนอัปโหลดเพื่อให้ได้ประสิทธิภาพดีที่สุดในแผนที่ภาพ
แนวทางปฏิบัติแนะนำในการเตรียมข้อมูลมีดังนี้
- ลดคุณสมบัติของฟีเจอร์ เก็บเฉพาะคุณสมบัติของฟีเจอร์เพื่อจัดรูปแบบ แผนที่ของคุณ ตัวอย่างเช่น "id" และ "category" คุณรวมพร็อพเพอร์ตี้เพิ่มเติมสำหรับฟีเจอร์ในไคลเอ็นต์ได้ โดยใช้รูปแบบที่อิงตามข้อมูลในคีย์ตัวระบุที่ไม่ซ้ำกัน ตัวอย่างเช่น โปรดดู ดูข้อมูลแบบเรียลไทม์ด้วยการจัดรูปแบบตามข้อมูล
- ใช้ประเภทข้อมูลแบบง่ายสำหรับออบเจ็กต์พร็อพเพอร์ตี้เมื่อเป็นไปได้ เช่น จำนวนเต็ม เพื่อลดขนาดชิ้นส่วนและปรับปรุงประสิทธิภาพของแผนที่
- ลดความซับซ้อนของเรขาคณิตที่ซับซ้อนก่อนที่จะอัปโหลดไฟล์ โดยทำได้ใน เครื่องมือทางภูมิศาสตร์ที่คุณเลือก เช่น โอเพนซอร์ส Mapshaper.org หรือใน BigQuery โดยใช้ ST_Simplify บนรูปทรงเรขาคณิตที่ซับซ้อนได้
- คลัสเตอร์จุดที่หนาแน่นมากก่อนอัปโหลดไฟล์ โดยทำได้ใน เครื่องมือทางภูมิศาสตร์ที่คุณเลือก เช่น โอเพนซอร์ส ฟังก์ชันคลัสเตอร์ turf.js หรือใน BigQuery โดยใช้ ST_CLUSTERDBSCAN บนรูปทรงเรขาคณิตที่จุดหนาแน่น
ดูคำแนะนำเพิ่มเติมเกี่ยวกับแนวทางปฏิบัติแนะนำเกี่ยวกับชุดข้อมูลใน แสดงภาพข้อมูลด้วยชุดข้อมูลและ BigQuery
ข้อกำหนด GeoJSON
Maps Datasets API รองรับ ข้อกำหนด GeoJSON Maps Datasets API ยังรองรับไฟล์ GeoJSON ที่มีอ็อบเจกต์ประเภทต่อไปนี้ด้วย
- วัตถุเรขาคณิต วัตถุรูปทรงเรขาคณิตเป็นรูปทรงเชิงพื้นที่ ซึ่งอธิบายไว้เป็นสหภาพ ของจุด เส้น และรูปหลายเหลี่ยมพร้อมด้วยรูสำหรับเลือก
- แสดงออบเจ็กต์ ออบเจ็กต์ฟีเจอร์มีเรขาคณิตบวกเพิ่มเติม คู่ชื่อ/ค่า ซึ่งมีความหมายเฉพาะแอปพลิเคชัน
- คอลเล็กชันฟีเจอร์ คอลเล็กชันฟีเจอร์คือชุดของออบเจ็กต์ฟีเจอร์
Maps Datasets API ไม่รองรับไฟล์ GeoJSON ที่มีข้อมูลในระบบอ้างอิงพิกัด (CRS) ที่ไม่ใช่ WGS84
ดูข้อมูลเพิ่มเติมเกี่ยวกับ GeoJSON ดู สอดคล้องกับ RFC 7946
ข้อกำหนดของ KML
Maps Datasets API มีข้อกำหนดต่อไปนี้
- URL ทั้งหมดต้องอยู่ในเครื่อง (หรือต้องสัมพัทธ์) กับไฟล์
- สนับสนุนเรขาคณิตของจุด เส้น และรูปหลายเหลี่ยม
- แอตทริบิวต์ข้อมูลทั้งหมดจะถือเป็นสตริง
- ไอคอนหรือ
<styleUrl>
ที่กำหนดไว้นอกไฟล์ - ลิงก์เครือข่าย เช่น
<NetworkLink>
- การวางซ้อนภาคพื้นดิน เช่น
<GroundOverlay>
- เรขาคณิต 3 มิติหรือแท็กที่เกี่ยวข้องกับระดับความสูง เช่น
<altitudeMode>
- ข้อมูลจำเพาะของกล้อง เช่น
<LookAt>
- รูปแบบที่กำหนดในไฟล์ KML
ข้อกำหนด CSV
สำหรับไฟล์ CSV ชื่อคอลัมน์ที่รองรับจะแสดงอยู่ด้านล่างตามลำดับความสำคัญ
latitude
longitude
lat
long
x
y
wkt
(ข้อความที่รู้จักกันดี)address
,city
,state
,zip
address
- คอลัมน์เดียวที่มีข้อมูลที่อยู่ทั้งหมด เช่น
1600 Amphitheatre Parkway Mountain View, CA 94043
เช่น ไฟล์มีคอลัมน์ที่ชื่อ x
, y
และ wkt
เนื่องจาก x
และ y
มีลำดับความสำคัญสูงกว่า ตามที่ระบุโดยลำดับของ
ชื่อคอลัมน์ที่รองรับในรายการด้านบน ค่าในคอลัมน์ x
และ y
และระบบจะไม่สนใจคอลัมน์ wkt
นอกจากนี้
- ชื่อแต่ละคอลัมน์ต้องอยู่ในคอลัมน์เดียว กล่าวคือ คุณไม่สามารถตั้งชื่อคอลัมน์
xy
ที่มีทั้งข้อมูลพิกัด x และ y พิกัด x และ y ต้องอยู่ใน คอลัมน์อื่น - ชื่อคอลัมน์ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่
- ลำดับของชื่อคอลัมน์ไม่มีความสำคัญ เช่น หากไฟล์ CSV มี
คอลัมน์
lat
และlong
อาจมีลำดับอย่างไรก็ได้
จัดการข้อผิดพลาดในการอัปโหลดข้อมูล
เมื่ออัปโหลดข้อมูลไปยังชุดข้อมูล คุณอาจพบข้อผิดพลาดที่พบบ่อยตามที่อธิบายไว้ใน
ข้อผิดพลาด GeoJSON
ข้อผิดพลาดทั่วไปของ GeoJSON ได้แก่
- ไม่มีช่อง
type
หรือtype
ไม่ใช่สตริง อัปโหลดแล้ว ไฟล์ข้อมูล GeoJSON ต้องมีฟิลด์สตริงชื่อtype
เป็นส่วนหนึ่งของแต่ละฟิลด์ คำจำกัดความของออบเจ็กต์เด่นและออบเจ็กต์เรขาคณิต
ข้อผิดพลาด KML
ข้อผิดพลาด KML ที่พบบ่อย ได้แก่
- ไฟล์ข้อมูลต้องไม่มีคุณลักษณะ KML ที่ไม่สนับสนุนตามรายการข้างต้น มิฉะนั้น การนำเข้าข้อมูลอาจล้มเหลว
ข้อผิดพลาด CSV
ข้อผิดพลาด CSV ที่พบบ่อย ได้แก่
- บางแถวไม่มีค่าสำหรับคอลัมน์เรขาคณิต แถวทั้งหมดในไฟล์ CSV ต้องมี
สำหรับคอลัมน์เรขาคณิต คอลัมน์เรขาคณิตประกอบด้วยข้อมูลต่อไปนี้
latitude
longitude
lat
long
x
y
wkt
address
,city
,state
,zip
address
- คอลัมน์เดียวที่มีข้อมูลที่อยู่ทั้งหมด เช่น
1600 Amphitheatre Parkway Mountain View, CA 94043
- หาก
x
และy
คือคอลัมน์เรขาคณิตของคุณ โปรดตรวจสอบว่าหน่วยดังกล่าว ลองจิจูดและละติจูด ชุดข้อมูลสาธารณะบางรายการใช้ระบบพิกัดที่แตกต่างกันภายใต้ส่วนหัวx
และy
หากใช้หน่วยที่ไม่ถูกต้อง ชุดข้อมูลอาจนำเข้า สำเร็จ แต่ข้อมูลที่แสดงผลสามารถแสดงจุดชุดข้อมูลในตำแหน่งที่ไม่คาดคิด
สร้างชุดข้อมูล
สร้างชุดข้อมูลโดยส่งคำขอ POST
ไปยัง
ปลายทาง datasets:
https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets
ส่งเนื้อหา JSON กับคำขอกำหนดชุดข้อมูล คุณต้องปฏิบัติดังนี้
ระบุ
displayName
ของชุดข้อมูล ค่าของdisplayName
ต้อง ไม่ซ้ำกันสำหรับชุดข้อมูลทั้งหมดตั้งค่า
usage
เป็นUSAGE_DATA_DRIVEN_STYLING
เช่น
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
การตอบกลับจะมีรหัสของชุดข้อมูลในรูปแบบ
projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID
รวมถึงข้อมูลเพิ่มเติม ใช้รหัสชุดข้อมูลเมื่อส่งคำขอไปยัง
อัปเดตหรือแก้ไขชุดข้อมูล
{ "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" }
อัปโหลดข้อมูลไปยังชุดข้อมูล
หลังจากที่คุณสร้างชุดข้อมูล ให้อัปโหลดข้อมูลจาก Google Cloud Storage หรือจากไฟล์ในเครื่องไปยังชุดข้อมูล
อัปโหลดข้อมูลจาก Cloud Storage
คุณอัปโหลดจาก Cloud Storage ไปยังชุดข้อมูลโดยส่งคำขอ POST
ไปยัง
datasets ที่
รวมรหัสของชุดข้อมูล:
https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import
ในเนื้อหาคำขอ JSON:
ใช้
inputUri
เพื่อระบุเส้นทางของไฟล์ไปยังทรัพยากรที่มีข้อมูล ใน Cloud Storage เส้นทางนี้อยู่ในรูปแบบgs://GCS_BUCKET/FILE
ผู้ใช้ที่ส่งคำขอต้องใช้ Storage Object ผู้มีสิทธิ์ดู หรือบทบาทอื่นๆ ที่มีสิทธิ์
storage.objects.get
สำหรับ ข้อมูลเพิ่มเติมเกี่ยวกับการจัดการการเข้าถึง Cloud Storage โปรดดู ภาพรวมของการควบคุมการเข้าถึงใช้
fileFormat
เพื่อระบุรูปแบบไฟล์ของข้อมูลเป็นFILE_FORMAT_GEOJSON
(ไฟล์ GeoJson),FILE_FORMAT_KML
(ไฟล์ KML) หรือFILE_FORMAT_CSV
(ไฟล์ CSV)
เช่น
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
คำตอบจะอยู่ในรูปแบบดังนี้
{ "name": "projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@VERSION_NUMBER" }
อัปโหลดข้อมูลจากไฟล์
หากต้องการอัปโหลดข้อมูลจากไฟล์ ให้ส่งคำขอ HTTP POST
ไปยัง
datasets ที่
รวมรหัสของชุดข้อมูล:
https://mapsplatformdatasets.googleapis.com/upload/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import
คำขอประกอบด้วย:
ตั้งค่าส่วนหัว
Goog-Upload-Protocol
เป็นmultipart
พร็อพเพอร์ตี้
metadata
ที่ระบุเส้นทางไปยังไฟล์ที่ระบุ ประเภทข้อมูลที่จะอัปโหลด ได้แก่FILE_FORMAT_GEOJSON
(ไฟล์ GeoJSON)FILE_FORMAT_KML
(ไฟล์ KML) หรือFILE_FORMAT_CSV
(ไฟล์ CSV)เนื้อหาของไฟล์นี้จะมีรูปแบบดังต่อไปนี้
{"local_file_source": {"file_format": "FILE_FORMAT_GEOJSON"}}
พร็อพเพอร์ตี้
rawdata
ที่ระบุเส้นทางไปยังไฟล์ GeoJSON, KML หรือ CSV ที่มีข้อมูลที่จะอัปโหลด
คำขอต่อไปนี้ใช้ตัวเลือก curl -F
เพื่อระบุเส้นทางไปยัง
ไฟล์:
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
คำตอบจะอยู่ในรูปแบบดังนี้
{ "name": "projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@VERSION_NUMBER" }
อัปโหลดข้อมูลใหม่ไปยังชุดข้อมูล
หลังจากที่คุณสร้างชุดข้อมูลและอัปโหลดข้อมูลเบื้องต้นเรียบร้อยแล้ว สถานะ
ของชุดข้อมูลตั้งค่าไว้เป็น STATE_COMPLETED
ซึ่งหมายความว่าชุดข้อมูลจะพร้อม
ใช้ในแอปของคุณ หากต้องการระบุ state
ของชุดข้อมูล โปรดดูรับ
ชุดข้อมูล
นอกจากนี้ คุณยังอัปโหลดข้อมูลใหม่ลงในชุดข้อมูลเพื่อสร้างเวอร์ชันใหม่ของ ชุดข้อมูล ในการอัปโหลดข้อมูลใหม่ ให้ใช้กระบวนการเดียวกับที่คุณใช้ในการอัปโหลดข้อมูลใหม่ จาก Cloud Storage หรืออัปโหลดข้อมูลจากไฟล์ และระบุข้อมูลใหม่ที่จะอัปโหลด
หากข้อมูลใหม่อัปโหลดสำเร็จ
สถานะของชุดข้อมูลเวอร์ชันใหม่ได้รับการตั้งค่าเป็น
STATE_COMPLETED
เวอร์ชันใหม่จะเปลี่ยนเป็น "ใช้งาน" เวอร์ชันและเป็นเวอร์ชันที่ แอป
หากมีข้อผิดพลาดในการอัปโหลด ให้ทำดังนี้
สถานะของชุดข้อมูลเวอร์ชันใหม่ได้รับการตั้งค่าเป็นสถานะใดสถานะหนึ่งต่อไปนี้
STATE_IMPORT_FAILED
STATE_PROCESSING_FAILED
STATE_PUBLISHING_FAILED
STATE_DELETION_FAILED
ชุดข้อมูลเวอร์ชันก่อนหน้าที่สําเร็จจะยังคงเป็น "ใช้งานอยู่" เวอร์ชันและ เวอร์ชันที่แอปของคุณใช้