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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

يمكنك إنشاء مجموعة بيانات من خلال إرسال طلب 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

ملاحظة: يختلف عنوان URL لطلب تحميل البيانات من ملف عن عنوان URL. من تحميل البيانات من Google Cloud Storage

ويحتوي الطلب على:

• تم ضبط عنوان 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

• تظل النسخة الناجحة من مجموعة البيانات السابقة على الحالة "نشطة" الإصدار وهو الإصدار الذي يستخدمه تطبيقك.