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

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

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

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

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

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

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

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

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

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

متطلبات GeoJSON

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

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

لا تدعم واجهة برمجة تطبيقات مجموعات بيانات الخرائط ملفات 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 (نص معروف)
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. في حال استخدام وحدات خاطئة، قد يتم استيراد مجموعة البيانات بنجاح، إلا أنّ البيانات المعروضة قد تُظهر نقاط مجموعة البيانات في مواقع جغرافية غير متوقّعة.

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

أنشئ مجموعة بيانات عن طريق إرسال طلب 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"
}