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

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

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

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

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