واجهة برمجة التطبيقات لمجموعات البيانات في "خرائط Google" متوفّرة حاليًا في وضع المعاينة (في مرحلة ما قبل التوفّر للجمهور العام). قد تكون منتجات وميزات مرحلة ما قبل التوفّر للجمهور العام متوافقة بشكل محدود، وقد لا تتوافق التغييرات التي تم إجراؤها على منتجات وميزات مرحلة ما قبل التوفّر للجمهور العام مع إصدارات "إحصاءات Google ما قبل التوفّر للجمهور العام". تخضع "عروض مرحلة ما قبل التوفّر للجمهور العام" للبنود المحدّدة لخدمة "منصة خرائط Google". لمزيد من المعلومات، راجِع أوصاف مراحل الإطلاق.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

إنشاء مجموعة بيانات هي عملية من خطوتين:

قدم طلبًا لإنشاء مجموعة البيانات.
قدم طلبًا لتحميل البيانات إلى مجموعة البيانات.

بعد تحميل البيانات الأولية، يمكنك تحميل بيانات جديدة إلى مجموعة البيانات لإنشاء نسخة جديدة من مجموعة البيانات.

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

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

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

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

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

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

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

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

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

الحدّ من خصائص الميزات: احتفظ فقط بسمات الميزات المطلوبة لتصميم خريطتك، مثل "id" و "category". يمكنك دمج مواقع إضافية مع ميزة في أحد تطبيقات العميل باستخدام الأنماط المستندة إلى البيانات على مفتاح معرّف فريد. على سبيل المثال، راجِع القسم الاطّلاع على بياناتك في الوقت الفعلي باستخدام النمط المستند إلى البيانات.
استخدِم أنواع بيانات بسيطة لعناصر السمات متى أمكن ذلك، مثل الأعداد الصحيحة، لتقليل حجم المربّعات وتحسين أداء الخريطة.
يجب تبسيط الأشكال الهندسية المعقّدة قبل تحميل ملف. يمكنك إجراء ذلك في أداة جغرافية مكانية من اختيارك، مثل الأداة المفتوحة المصدر Mapshaper.org، أو في BigQuery باستخدام ST_Simplify على الأشكال الهندسية للمضلّعات المعقدة.
تجميع نقاط شديدة الكثافة قبل تحميل ملف ويمكنك إجراء ذلك في أداة جغرافية مكانية من اختيارك، مثل دوال التجميع العنقودي 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 كجزء من كل تعريف لكل عنصر من عناصر الميزة وتعريف الكائن 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. في حال استخدام وحدات خاطئة، قد يتم استيراد مجموعة البيانات بنجاح، ولكن يمكن أن تعرض البيانات المعروضة نقاط مجموعة البيانات في مواقع جغرافية غير متوقّعة.

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

يمكنك إنشاء مجموعة بيانات عن طريق إرسال طلب POST إلى نقطة نهاية مجموعات البيانات:

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

مرِّر نص JSON إلى الطلب الذي يحدّد مجموعة البيانات. يجب تنفيذ ما يلي:

حدِّد displayName لمجموعة البيانات. يجب أن تكون قيمة displayName فريدة لجميع مجموعات البيانات.
اضبط السمة usage على USAGE_DATA_DRIVEN_STYLING.

ملاحظة: USAGE_DATA_DRIVEN_STYLING هي القيمة الوحيدة المتوافقة مع usage.

مثلاً:

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 لتحديد مسار الملفين:

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
تظل مجموعة البيانات السابقة الناجحة هي الإصدار "النشط" وهي النسخة التي يستخدمها تطبيقك.