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