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

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

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

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

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

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

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

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 لمراقبة حالة مجموعة البيانات لتحديد وقت توفّرها للاستخدام أو ما إذا حدثت أي أخطاء. لمزيد من المعلومات، يُرجى الاطّلاع على الحصول على حالة معالجة البيانات.

تحميل البيانات من Cloud Storage

يمكنك تحميل البيانات من Cloud Storage إلى مجموعة البيانات عن طريق إرسال طلب POST إلى نقطة النهاية datasets التي تتضمّن أيضًا معرّف مجموعة البيانات:

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 إلى نقطة النهاية datasets التي تتضمّن أيضًا معرّف مجموعة البيانات::

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

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