يُعدّ إنشاء مجموعة بيانات عملية من خطوتَين:
قدم طلبًا لإنشاء مجموعة البيانات.
قدِّم طلبًا لتحميل البيانات إلى مجموعة البيانات.
بعد تحميل البيانات الأولية، يمكنك تحميل بيانات جديدة إلى مجموعة البيانات لإنشاء إصدار جديد منها.
إنشاء مجموعة البيانات
يمكنك إنشاء مجموعة بيانات عن طريق إرسال طلب 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
تظل مجموعة البيانات السابقة الناجحة هي الإصدار "النشط" وهي النسخة التي يستخدمها تطبيقك.