قبل البدء

يصف هذا المستند المتطلّبات الأساسية وأفضل الممارسات والأخطاء الشائعة. عند العمل على مجموعات البيانات.

المتطلبات الأساسية

عند إنشاء مجموعة بيانات:

  • يجب أن تكون الأسماء المعروضة فريدة ضمن مشروعك على Google Cloud.
  • يجب أن تكون الأسماء المعروضة أقل من 64 بايت (نظرًا لأن هذه الأحرف ممثلة بترميز UTF-8، في بعض اللغات، يمكن تمثيل كل حرف بعدة بايت).
  • يجب أن تكون الأوصاف أقل من 1000 بايت.

عند تحميل البيانات:

  • وأنواع الملفات المتوافقة هي CSV وGeoJSON وKML.
  • الحد الأقصى لحجم الملف المسموح به هو 500 ميغابايت.
  • لا يمكن أن تبدأ أسماء أعمدة السمات بالسلسلة "?_".
  • لا يتم توفير الأشكال الهندسية الثلاثية الأبعاد. وهذا يشمل الحرف "Z" بتنسيق WKT، وإحداثي الارتفاع بتنسيق GeoJSON.

أفضل ممارسات إعداد البيانات

في حال كانت بيانات المصدر معقدة أو كبيرة، مثل النقاط الكثيفة أو السلاسل الخطية الطويلة أو المضلّعات (تندرج غالبًا أحجام الملفات المصدر التي تزيد عن 50 ميغابايت ضمن هذه الفئة)، ننصحك بتبسيط بياناتك قبل التحميل لتحقيق أفضل أداء في الخريطة المرئية.

فيما يلي بعض أفضل الممارسات لإعداد بياناتك:

  1. الحدّ من خصائص الميزات: الاحتفاظ فقط بخصائص الميزات المطلوبة لتصميم النمط خريطتك، على سبيل المثال "id" و"category". يمكنك دمج مواقع إضافية مع ميزة في أحد البرامج. المستخدم باستخدام أنماط تستند إلى البيانات على مفتاح معرّف فريد. على سبيل المثال، راجع الاطّلاع على بياناتك في الوقت الفعلي باستخدام النمط المستند إلى البيانات
  2. استخدام أنواع بيانات بسيطة لعناصر المواقع، حيثما أمكن، مثل الأعداد الصحيحة لتقليل حجم المربعات وتحسين أداء الخريطة.
  3. يجب تبسيط الأشكال الهندسية المعقّدة قبل تحميل ملف. يمكنك إجراء ذلك أداة جغرافية مكانية من اختيارك، مثل الأداة المفتوحة المصدر Mapshaper.org، أو في BigQuery باستخدام ST_Simplify على الأشكال الهندسية للمضلّعات المعقدة.
  4. تجميع نقاط كثيفة جدًا قبل تحميل ملف يمكنك إجراء ذلك أداة جغرافية مكانية من اختيارك، مثل الأداة المفتوحة المصدر دوال مجموعات Turf.js أو في BigQuery. باستخدام ST_CLUSTERDBSCAN على الأشكال الهندسية النقطية الكثيفة.

اطّلِع على إرشادات إضافية حول أفضل ممارسات مجموعات البيانات على تمثيل بياناتك مرئيًا باستخدام مجموعات البيانات وBigQuery.

متطلبات GeoJSON

تتوافق واجهة برمجة تطبيقات مجموعات بيانات الخرائط مع واجهة مواصفات GeoJSON تتوافق واجهة برمجة تطبيقات مجموعات بيانات الخرائط أيضًا مع ملفات GeoJSON التي تحتوي على أي من أنواع الكائنات التالية:

  • العناصر الهندسية: الكائن الهندسي هو شكل مكاني يوصف بأنه اتحاد النقاط والخطوط والمضلّعات مع ثقوب اختيارية.
  • العناصر المميّزة: يحتوي كائن الميزة على شكل هندسي بالإضافة إلى أزواج الأسماء/القيم، والتي يكون معنى الخاص بها خاصًا بالتطبيق.
  • مجموعات الميزات: إنّ مجموعة الميزات هي مجموعة من العناصر المميّزة.

لا تتوافق واجهة برمجة تطبيقات مجموعات بيانات الخرائط مع ملفات GeoJSON التي تحتوي على بيانات في نظام مرجعي إحداثي (CRS) بخلاف WGS84.

لمزيد من المعلومات حول GeoJSON، يمكنك الاطّلاع على متوافق مع RFC 7946

متطلبات KML

تتطلب واجهة برمجة التطبيقات لمجموعات بيانات الخرائط المتطلبات التالية:

  • يجب أن تكون جميع عناوين URL محلية (أو نسبية) للملف نفسه.
  • يُسمح بأشكال هندسية النقاط والخطوط والمضلّعات.
  • تعتبر جميع تصنيفات البيانات سلاسل.
ميزات KML التالية غير متاحة:
  • رموز أو <styleUrl> محددة خارج الملف.
  • روابط الشبكة، مثل <NetworkLink>
  • طبقات الأرض المركّبة، مثل <GroundOverlay>
  • الأشكال الهندسية الثلاثية الأبعاد أو أي علامات ذات صلة بالارتفاع، مثل <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" في حال استخدام وحدات خاطئة، قد يتم استيراد مجموعة البيانات ولكن البيانات المعروضة قد تُظهر نقاط مجموعة البيانات في مواقع غير متوقعة.