قبل البدء

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

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

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

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

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

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

ملاحظة: استنادًا إلى حجم ملف البيانات، يمكن أن يستغرق اكتمال عملية التحميل دقائق أو حتى ساعات. إذا حدث خطأ في عملية التحميل، ستتلقّى رسالة خطأ. لا تحاول حذف مجموعة البيانات إلى أن تتلقّى استجابة من عملية التحميل.

ملاحظة: قد تحذف أو تبسط شرائح الخريطة التي تم إنشاؤها باستخدام البيانات المحمَّلة باستخدام واجهة برمجة التطبيقات Maps Datasets API البيانات الكثيفة أو المعقّدة عند مستويات التصغير المنخفضة. على سبيل المثال، عندما يكبِّر أحد المستخدِمين الخريطة إلى مستوى إقليم أو بلد (على سبيل المثال، من المستوى 5 إلى 12)، قد تبدو البيانات المعروضة على شكل مربّعات مختلفة عن تلك التي تظهر عند تكبير الخريطة إلى مستوى مدينة أو حي (على سبيل المثال، من المستوى 13 إلى 18). ويحدث ذلك للحفاظ على بساطة شاشات المعلومات وكفاءتها باستخدام شاشات المعلومات مع أداة عرض الخرائط.

ملاحظة: إذا كان ملف البيانات كبيرًا ويحتوي على العديد من السمات التي لا تحتاج إليها في الملف لتطبيق الأنماط، وأردت تحسين أداء العرض، عليك تعديل الملف لإزالة السمات غير المطلوبة. يؤدي تقليل عدد السمات إلى تقليل حجم مربّعات الخريطة، ما يؤدي إلى تحسين أداء العرض.

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

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

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

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

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

• يجب أن تكون جميع عناوين 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 كجزء من كل تعريف لكل عنصر من عناصر الميزة وتعريف الكائن Geometry.

أخطاء 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. في حال استخدام وحدات غير صحيحة، قد يتم استيراد مجموعة البيانات بنجاح، ولكن يمكن أن تعرض البيانات المعروضة نقاط مجموعة البيانات في مواقع غير متوقّعة.