ساختن مجموعه داده

ایجاد مجموعه داده فرایندی دو مرحله‌ای است:

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

با ارسال درخواست POST به نقطه پایانی مجموعه داده‌ها که شامل شناسه مجموعه داده‌ها نیز می‌شود، از Cloud Storage به مجموعه داده‌هایتان بارگذاری می‌کنید:

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 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 است. این آرایه حاوی حداکثر ۵۰ خطای نوع Status در هر تماس است و در مجموع از حداکثر ۵۰۰ خطا پشتیبانی می‌کند:

{
  "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)"
    },
    ...
  ]
}

اگر بیش‌از ۵۰ خطا وجود داشته باشد، یعنی بیش‌از یک صفحه خطا وجود داشته باشد، پاسخ حاوی یک کد صفحه در فیلد 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"

به‌طور پیش‌فرض، پاسخ حداکثر حاوی ۵۰ خطا در هر صفحه است. از پارامتر پُرسمان pageSize برای کنترل اندازه صفحه استفاده کنید.

بارگذاری داده‌های جدید در مجموعه داده

پس‌از ایجاد مجموعه داده و بارگذاری موفقیت‌آمیز داده‌های اولیه، وضعیت مجموعه داده روی STATE_COMPLETED تنظیم می‌شود. این یعنی مجموعه داده برای استفاده در برنامه‌تان آماده است. برای تعیین state مجموعه داده، به دریافت مجموعه داده مراجعه کنید.

همچنین می‌توانید داده‌های جدیدی را در مجموعه داده بارگذاری کنید تا نسخه جدیدی از مجموعه داده ایجاد کنید. برای بارگذاری داده‌های جدید، از همان روندی که برای بارگذاری داده‌ها از Cloud Storage یا بارگذاری داده‌ها از فایل استفاده کردید استفاده کنید و داده‌های جدید را برای بارگذاری مشخص کنید.

اگر داده‌های جدید باموفقیت بارگذاری شد:

• وضعیت نسخه جدید مجموعه داده روی STATE_COMPLETED تنظیم شده است.

• نسخه جدید به نسخه «فعال» تبدیل می‌شود و نسخه‌ای است که برنامه‌تان از آن استفاده می‌کند.

اگر خطایی در بارگذاری وجود دارد:

• وضعیت نسخه مجموعه داده جدید روی یکی از وضعیت‌های زیر تنظیم شده است:

  • STATE_IMPORT_FAILED
  • STATE_PROCESSING_FAILED
  • STATE_PUBLISHING_FAILED
  • STATE_DELETION_FAILED

• نسخه موفق قبلی مجموعه داده به‌عنوان نسخه «فعال» باقی می‌ماند و نسخه‌ای است که برنامه‌تان از آن استفاده می‌کند.