สร้างชุดข้อมูล

การสร้างชุดข้อมูลเป็นกระบวนการที่มี 2 ขั้นตอน ดังนี้

  1. ส่งคำขอเพื่อสร้างชุดข้อมูล

  2. ส่งคำขอเพื่ออัปโหลดข้อมูลไปยังชุดข้อมูล

หลังจากอัปโหลดข้อมูลครั้งแรกแล้ว คุณจะอัปโหลดข้อมูลใหม่ไปยังชุดข้อมูลเพื่อสร้างชุดข้อมูลเวอร์ชันใหม่ได้

สิ่งที่ต้องดำเนินการก่อน

เมื่อสร้างชุดข้อมูลให้ทำดังนี้

  • ชื่อที่แสดงต้องไม่ซ้ำกันภายในโปรเจ็กต์ Google Cloud
  • ชื่อที่แสดงต้องมีขนาดไม่เกิน 64 ไบต์ (เนื่องจากอักขระเหล่านี้แสดงด้วย UTF-8 ดังนั้นอักขระบางตัวจึงอาจแทนค่าได้หลายไบต์ในบางภาษา)
  • คำอธิบายต้องมีขนาดไม่เกิน 1,000 ไบต์

เมื่ออัปโหลดข้อมูล ให้ทำดังนี้

  • ประเภทไฟล์ที่รองรับ ได้แก่ CSV, GeoJSON และ KML
  • ขนาดไฟล์สูงสุดที่รองรับคือ 350 MB
  • ชื่อคอลัมน์แอตทริบิวต์ต้องไม่ขึ้นต้นด้วยสตริง "?_"
  • ไม่สนับสนุนรูปทรงเรขาคณิตสามมิติ ซึ่งรวมถึงคำต่อท้าย "Z" ในรูปแบบ WKT และพิกัดระดับความสูงในรูปแบบ GeoJSON

แนวทางปฏิบัติแนะนำในการเตรียมข้อมูล

หากแหล่งข้อมูลของคุณมีความซับซ้อนหรือมีขนาดใหญ่ เช่น จุดหนาแน่น สตริงยาว หรือรูปหลายเหลี่ยม (ไฟล์ต้นฉบับที่มีขนาดใหญ่กว่า 50 MB จะอยู่ในหมวดหมู่นี้) ให้ลองลดความซับซ้อนของข้อมูลก่อนอัปโหลดเพื่อให้ได้ประสิทธิภาพที่ดีที่สุดในแผนที่ภาพ

แนวทางปฏิบัติแนะนำในการเตรียมข้อมูลมีดังนี้

  1. ลดคุณสมบัติของฟีเจอร์ เก็บเฉพาะคุณสมบัติของฟีเจอร์ที่ต้องใช้เพื่อจัดรูปแบบแผนที่ เช่น "id" และ "category" คุณเชื่อมโยงพร็อพเพอร์ตี้เพิ่มเติมกับฟีเจอร์ในแอปพลิเคชันไคลเอ็นต์ได้โดยใช้รูปแบบที่อิงตามข้อมูลในคีย์ตัวระบุที่ไม่ซ้ำกัน ตัวอย่างเช่น อ่านดูข้อมูลแบบเรียลไทม์ด้วยการจัดรูปแบบตามข้อมูล
  2. ใช้ประเภทข้อมูลอย่างง่ายสำหรับออบเจ็กต์พร็อพเพอร์ตี้หากเป็นไปได้ เช่น จำนวนเต็ม เพื่อลดขนาดไทล์และปรับปรุงประสิทธิภาพของแผนที่
  3. ลดความซับซ้อนของเรขาคณิตที่ซับซ้อนก่อนที่จะอัปโหลดไฟล์ โดยใช้เครื่องมือภูมิสารสนเทศที่คุณเลือก เช่น ยูทิลิตี Mapshaper.org แบบโอเพนซอร์ส หรือใน BigQuery ที่ใช้ ST_Simplify กับเรขาคณิตหลายรูปที่ซับซ้อน
  4. คลัสเตอร์จุดที่หนาแน่นมากก่อนอัปโหลดไฟล์ ซึ่งทำได้ในเครื่องมือภูมิสารสนเทศที่ต้องการ เช่น ฟังก์ชันคลัสเตอร์ 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 ทั้งหมดต้องอยู่ในเครื่อง (หรือต้องสัมพัทธ์) กับไฟล์
  • สนับสนุนเรขาคณิตของจุด เส้น และรูปหลายเหลี่ยม
  • แอตทริบิวต์ข้อมูลทั้งหมดจะถือเป็นสตริง
ระบบไม่รองรับฟีเจอร์ KML ต่อไปนี้
  • ไอคอนหรือ <styleUrl> ที่กำหนดไว้นอกไฟล์
  • ลิงก์เครือข่าย เช่น <NetworkLink>
  • การวางซ้อนภาคพื้นดิน เช่น <GroundOverlay>
  • เรขาคณิต 3 มิติหรือแท็กที่เกี่ยวข้องกับระดับความสูง เช่น <altitudeMode>
  • ข้อมูลจำเพาะของกล้อง เช่น <LookAt>
  • รูปแบบที่กำหนดในไฟล์ KML

ข้อกำหนด CSV

สำหรับไฟล์ CSV ชื่อคอลัมน์ที่รองรับจะแสดงอยู่ด้านล่างตามลำดับความสำคัญ

เช่น ไฟล์มีคอลัมน์ที่ชื่อ 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 ไปยังปลายทางชุดข้อมูลดังนี้

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 ไปยังปลายทางชุดข้อมูลที่มีรหัสของชุดข้อมูลดังนี้

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

ในเนื้อหาคำขอ JSON:

  • ใช้ inputUri เพื่อระบุเส้นทางของไฟล์ไปยังทรัพยากรที่มีข้อมูลใน Cloud Storage เส้นทางนี้อยู่ในรูปแบบ gs://GCS_BUCKET/FILE

    ผู้ใช้ที่ส่งคำขอต้องมีบทบาทผู้ดูออบเจ็กต์พื้นที่เก็บข้อมูล หรือบทบาทอื่นๆ ที่มีสิทธิ์ 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 ไปยังปลายทางชุดข้อมูลที่มีรหัสของชุดข้อมูลดังนี้

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 เพื่อระบุเส้นทางไปยังทั้ง 2 ไฟล์

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

  • เวอร์ชันก่อนหน้าที่สำเร็จของชุดข้อมูลจะยังคงเป็นเวอร์ชัน "ใช้งาน" และเป็นเวอร์ชันที่แอปของคุณใช้