قبل البدء

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

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

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

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

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

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

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

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

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

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

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

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

1. تقليل خصائص الميزات: احتفِظ فقط بخصائص الميزات اللازمة لتصميم خريطتك، مثل "المعرّف" و "الفئة". يمكنك ربط خصائص إضافية بميزة في تطبيق عميل باستخدام أنماط مستندة إلى البيانات على مفتاح معرّف فريد. على سبيل المثال، يمكنك الاطّلاع على الاطّلاع على بياناتك في الوقت الفعلي باستخدام "التصميم المستند إلى البيانات".
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>
• أشكال هندسية ثلاثية الأبعاد أو أي علامات ذات صلة بالارتفاع، مثل <altitudeMode>
• مواصفات الكاميرا، مثل <LookAt>
• الأنماط المحدّدة داخل ملف KML

متطلبات ملفات CSV

بالنسبة إلى ملفات CSV، يتم إدراج أسماء الأعمدة المتوافقة أدناه حسب ترتيب الأولوية:

• ‫latitude، longitude
• ‫lat، long
• ‫x، y
• wkt (Well-Known Text)
• 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 كجزء من كل تعريف لعنصر Feature وعنصر 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. في حال استخدام وحدات خاطئة، قد يتم استيراد مجموعة البيانات بنجاح، ولكن قد تعرض البيانات المعروضة نقاط مجموعة البيانات في مواقع جغرافية غير متوقّعة.