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

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

  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 أو من ملف محلي إلى مجموعة البيانات.

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

تحميل البيانات من 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.

    يجب أن يكون لدى المستخدم الذي يرسل الطلب دور عارض عنصر الت101}خزين أو أي دور آخر يتضمّن الإذن 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

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