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

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

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

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

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

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

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

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

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

متطلبات GeoJSON

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

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

لا تتوافق واجهة برمجة تطبيقات مجموعات البيانات في "خرائط Google" مع ملفات 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 يحتوي على بيانات الإحداثيَين س وص. ويجب وضع الإحداثيتَين س وص في أعمدة منفصلة.
• أسماء الأعمدة غير حساسة لحالة الأحرف.
• لا يهم ترتيب أسماء الأعمدة. على سبيل المثال، إذا كان ملف 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.

مثال:

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"
}