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

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

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

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

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

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

يمكنك إنشاء مجموعة بيانات عن طريق إرسال طلب 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 أو من ملف على الجهاز إلى مجموعة البيانات.

عملية التحميل غير متزامنة. بعد تحميل البيانات، يتم نقل البيانات ومعالجتها. وهذا يعني أنّه عليك إرسال طلب HTTP GET لمراقبة حالة مجموعة البيانات من أجل تحديد وقت استعدادها للاستخدام أو ما إذا كانت هناك أي أخطاء. لمزيد من المعلومات، يُرجى الاطّلاع على الحصول على حالة processing المعالجة للبيانات.

تحميل البيانات من 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 ل مجموعة البيانات، استخدِم الحصول على مجموعة بيانات. على سبيل المثال، أثناء معالجة البيانات، يتم ضبط state على STATE_PROCESSING. عندما تكون مجموعة البيانات جاهزة للاستخدام في تطبيقك، يتم ضبط state على STATE_COMPLETED.

على سبيل المثال، يمكنك إجراء طلب GET على مجموعة البيانات:

curl -X GET \
  -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \
  -H "Authorization: Bearer $TOKEN" \
  "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46"

لكي تكون عملية التحميل ناجحة، يجب أن يكون state لمجموعة البيانات STATE_COMPLETED:

{
  "name": "projects/119757857/datasets/f57074a0-a8b6-403e-9df1-e9fc46",
  "displayName": "My Test Dataset",
  "description": " ",
  "versionId": "837c5a9e-c885-4a5f-a462-7e35673e5218",
  "usage": [
    "USAGE_DATA_DRIVEN_STYLING"
  ],
  "localFileSource": {
    "filename": "Parks_Properties_20240529.csv",
    "fileFormat": "FILE_FORMAT_CSV"
  },
  "createTime": "2024-05-30T16:41:11.130816Z",
  "updateTime": "2024-05-30T16:41:14.416130Z",
  "versionCreateTime": "2024-05-30T16:41:14.416130Z",
  "status": {
    "state": "STATE_COMPLETED",
  },
  "sizeBytes": "6916924",
  "downloadable": true
}

عند تعذُّر معالجة البيانات، يتم ضبط state على قيمة غير STATE_COMPLETED، مثل STATE_PUBLISHING_FAILED أو أي حالة تنتهي بسلسلة_FAILED.

على سبيل المثال، يمكنك تحميل البيانات إلى مجموعة بيانات ثمّ تقديم طلب GET للحصول على تفاصيل مجموعة البيانات. بالإضافة إلى سمة state، يحتوي الردّ أيضًا على سمة errorMessage واحدة تحتوي على وصف للخطأ.

{
  "name": "projects/119757857/datasets/f57074a0-a8b6-403e-9df1-e9fc46",
  "displayName": "My Test Dataset",
  "description": " ",
  "versionId": "837c5a9e-c885-4a5f-a462-7e35673e5218",
  "usage": [
    "USAGE_DATA_DRIVEN_STYLING"
  ],
  "localFileSource": {
    "filename": "Parks_Properties_20240529.csv",
    "fileFormat": "FILE_FORMAT_CSV"
  },
  "createTime": "2024-05-30T16:41:11.130816Z",
  "updateTime": "2024-05-30T16:41:14.416130Z",
  "versionCreateTime": "2024-05-30T16:41:14.416130Z",
  "status": {
    "state": "STATE_PUBLISHING_FAILED",
    "errorMessage": "INVALID_ARGUMENT: Skipping row because address could not be geocoded: 5521 18 AVENUE (from line 79)"
  },
  "sizeBytes": "6916924",
  "downloadable": true
}

الحصول على أخطاء معالجة البيانات

عند تعذُّر نقل البيانات ومعالجتها، يحتوي الحقل errorMessage على رسالة واحدة تصف الخطأ. ومع ذلك، لا تقدّم رسالة الخطأ الواحدة بالضرورة معلومات كافية لتحديد المشاكل وحلّها.

للحصول على معلومات كاملة عن الخطأ، يمكنك طلب بيانات من واجهة برمجة التطبيقات fetchDatasetErrors . تعرض واجهة برمجة التطبيقات هذه جميع أخطاء معالجة البيانات المرتبطة بمجموعة بيانات:

curl -X GET \
  -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \
  -H "Authorization: Bearer $TOKEN" \
  "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:fetchDatasetErrors"

يحتوي الردّ على صفيف errors. يحتوي هذا الصفيف على ما يصل إلى 50 خطأً من نوع Status لكل مكالمة، ويسمح بما يصل إلى 500 خطأ في المجمل:

{
  "nextPageToken": "cigKJkIkMTU3MzM0NjQtYzlmMy00YzYxLWIxM2YtYmVkYjFjYjRkYzRj",
  "errors": [
    {
      "code": 3,
      "message": "INVALID_ARGUMENT: No address was derived from fields 2. (from line 631)"
    },
    {
      "code": 3,
      "message": "INVALID_ARGUMENT: No address was derived from fields 2. (from line 457)"
    },
    {
      "code": 3,
      "message": "INVALID_ARGUMENT: No address was derived from fields 2. (from line 31)"
    },
    ...
  ]
}

إذا كان هناك أكثر من 50 خطأ، أي أكثر من صفحة واحدة من الأخطاء، سيحتوي الردّ على رمز تعريف صفحة في الحقل nextPageToken. مرِّر هذه القيمة في معلَمة طلب البحث pageToken لطلب لاحق للحصول على الصفحة التالية من الأخطاء. عندما يكون الحقل nextPageToken فارغًا، يعني ذلك أنّه ما مِن صفحات أخرى.

على سبيل المثال، للحصول على الصفحة التالية من الأخطاء باستخدام الرمز المميّز من الردّ السابق: 

curl -X GET \
  -H "content-type: application/json" \
  -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \
  -H "Authorization: Bearer $TOKEN" \
  "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:fetchDatasetErrors?pageToken=cigKJkIkMTU3MzM0NjQtYzlmMy00YzYxLWIxM2YtYmVkYjFjYjRkYzRj"

يحتوي الردّ تلقائيًا على 50 خطأ كحد أقصى في كل صفحة. استخدِم معلَمة طلب البحث pageSize للتحكّم في حجم الصفحة.

تحميل بيانات جديدة إلى مجموعة البيانات

بعد إنشاء مجموعة البيانات وتحميل البيانات الأولية بنجاح، يتم ضبط حالة مجموعة البيانات على STATE_COMPLETED. وهذا يعني أنّ مجموعة البيانات جاهزة للاستخدام في تطبيقك. لتحديد state لمجموعة البيانات، اطّلِع على مقالة الحصول على مجموعة بيانات.

يمكنك أيضًا تحميل بيانات جديدة إلى مجموعة البيانات لإنشاء إصدار جديد من مجموعة البيانات. لتحميل بيانات جديدة، اتّبِع العملية نفسها التي استخدمتها في تحميل البيانات من Cloud Storage أو تحميل البيانات من ملف، وحدِّد البيانات الجديدة لتحميلها.

في حال تحميل البيانات الجديدة بنجاح:

  • تم ضبط حالة الإصدار الجديد من مجموعة البيانات على STATE_COMPLETED.

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

إذا حدث خطأ في عملية التحميل:

  • يتم ضبط حالة إصدار مجموعة البيانات الجديدة على إحدى الحالات التالية:

    • STATE_IMPORT_FAILED
    • STATE_PROCESSING_FAILED
    • STATE_PUBLISHING_FAILED
    • STATE_DELETION_FAILED

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