ایجاد یک مجموعه داده یک فرآیند دو مرحله ای است:
برای ایجاد مجموعه داده درخواست دهید.
درخواستی برای آپلود داده ها در مجموعه داده ارائه دهید.
پس از آپلود داده های اولیه، می توانید داده های جدید را در مجموعه داده آپلود کنید تا نسخه جدیدی از مجموعه داده ایجاد کنید.
مجموعه داده را ایجاد کنید
با ارسال یک درخواست 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 برای نظارت بر وضعیت مجموعه داده ارسال کنید تا مشخص شود که مجموعه داده چه زمانی برای استفاده آماده است یا آیا خطا وجود دارد. برای اطلاعات بیشتر، به دریافت وضعیت پردازش داده مراجعه کنید.
داده ها را از فضای ذخیره سازی ابری بارگذاری کنید
با ارسال یک درخواست POST
به نقطه پایانی مجموعه دادهها که شامل شناسه مجموعه داده نیز میشود، از فضای ذخیرهسازی ابری در مجموعه داده خود آپلود میکنید:
https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import
در بدنه درخواست JSON:
از
inputUri
برای تعیین مسیر فایل به منبع حاوی داده در Cloud Storage استفاده کنید. این مسیر به شکلgs:// GCS_BUCKET / FILE
است.کاربر درخواست کننده به نقش Storage Object Viewer یا هر نقش دیگری که شامل مجوز
storage.objects.get
باشد نیاز دارد. برای اطلاعات بیشتر در مورد مدیریت دسترسی به فضای ذخیرهسازی ابری، به نمای کلی کنترل دسترسی مراجعه کنید.از
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" }
وضعیت پردازش داده را دریافت کنید
عملیات آپلود ناهمزمان است. این بدان معناست که پس از بازگشت فراخوان API برای آپلود دادهها در مجموعه داده، باید از مجموعه داده نظرسنجی کنید تا تعیین کنید که آیا جذب و پردازش دادهها موفقیتآمیز بوده است یا ناموفق.
برای تعیین 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
API تماس بگیرید. این API تمام خطاهای پردازش داده مرتبط با یک مجموعه داده را برمی گرداند:
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
است. آن مقدار را در پارامتر query 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
query برای کنترل اندازه صفحه استفاده کنید.
داده های جدید را در مجموعه داده آپلود کنید
پس از ایجاد مجموعه داده و آپلود داده های اولیه با موفقیت، وضعیت مجموعه داده روی STATE_COMPLETED
تنظیم می شود. این بدان معناست که مجموعه داده برای استفاده در برنامه شما آماده است. برای تعیین state
مجموعه داده، به دریافت یک مجموعه داده مراجعه کنید.
همچنین می توانید داده های جدیدی را در مجموعه داده آپلود کنید تا نسخه جدیدی از مجموعه داده ایجاد کنید. برای آپلود دادههای جدید، از همان فرآیندی که برای آپلود دادهها از فضای ذخیرهسازی ابری یا آپلود دادهها از یک فایل انجام دادید، استفاده کنید و دادههای جدید را برای آپلود مشخص کنید.
اگر داده های جدید با موفقیت آپلود شوند:
وضعیت نسخه جدید مجموعه داده روی
STATE_COMPLETED
تنظیم شده است.نسخه جدید به نسخه "فعال" تبدیل می شود و نسخه ای است که توسط برنامه شما استفاده می شود.
اگر در آپلود خطایی وجود دارد:
وضعیت نسخه مجموعه داده جدید روی یکی از حالات زیر تنظیم شده است:
-
STATE_IMPORT_FAILED
-
STATE_PROCESSING_FAILED
-
STATE_PUBLISHING_FAILED
-
STATE_DELETION_FAILED
-
نسخه موفق مجموعه داده قبلی به عنوان نسخه "فعال" باقی می ماند و نسخه ای است که توسط برنامه شما استفاده می شود.