یک مجموعه داده ایجاد کنید

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

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 برای نظارت بر وضعیت مجموعه داده ارسال کنید تا مشخص شود که مجموعه داده چه زمانی برای استفاده آماده است یا آیا خطا وجود دارد. برای اطلاعات بیشتر، به دریافت وضعیت پردازش داده مراجعه کنید.

داده ها را از فضای ذخیره سازی ابری بارگذاری کنید

با ارسال یک درخواست 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

• نسخه موفق مجموعه داده قبلی به عنوان نسخه "فعال" باقی می ماند و نسخه ای است که توسط برنامه شما استفاده می شود.