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

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

1. درخواستی برای ایجاد مجموعه داده ارسال کنید.

2. درخواستی برای بارگذاری داده‌ها در مجموعه داده ایجاد کنید.

پس از بارگذاری اولیه داده‌ها، می‌توانید داده‌های جدید را در مجموعه داده‌ها بارگذاری کنید تا نسخه جدیدی از مجموعه داده‌ها ایجاد شود.

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

با ارسال یک درخواست POST به نقطه پایانی datasets، یک مجموعه داده ایجاد کنید:

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" 
}

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

پس از ایجاد مجموعه داده‌ها، داده‌ها را از فضای ابری گوگل یا از یک فایل محلی به مجموعه داده‌ها آپلود کنید.

عملیات آپلود به صورت غیرهمزمان انجام می‌شود. پس از آپلود داده‌ها، داده‌ها دریافت و پردازش می‌شوند. این بدان معناست که شما باید یک درخواست HTTP GET برای نظارت بر وضعیت مجموعه داده‌ها ارسال کنید تا مشخص شود چه زمانی مجموعه داده‌ها آماده استفاده هستند یا آیا خطایی وجود دارد یا خیر. برای اطلاعات بیشتر، به بخش «دریافت وضعیت پردازش داده‌ها» مراجعه کنید.

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

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

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import

در بدنه درخواست JSON:

• از inputUri برای مشخص کردن مسیر فایل به منبعی که حاوی داده‌ها در فضای ذخیره‌سازی ابری است استفاده کنید. این مسیر به شکل gs:// GCS_BUCKET / FILE است.

  کاربری که درخواست را ارسال می‌کند، به نقش Storage Object Viewer یا هر نقش دیگری که شامل مجوز 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"
}

دریافت وضعیت پردازش داده‌ها

عملیات آپلود ناهمزمان است. این بدان معناست که پس از فراخوانی API برای آپلود داده‌ها به مجموعه داده، باید مجموعه داده را بررسی کنید تا مشخص شود که آیا دریافت و پردازش داده‌ها موفقیت‌آمیز بوده یا خیر.

برای تعیین state مجموعه داده، از Get a dataset استفاده کنید. برای مثال، در حالی که داده‌ها در حال پردازش هستند، 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 حاوی یک پیام واحد است که خطا را توصیف می‌کند. با این حال، یک پیام خطا لزوماً اطلاعات کافی برای شناسایی و رفع مشکلات را ارائه نمی‌دهد.

برای دریافت اطلاعات کامل خطا، API مربوط به 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 مجموعه داده، به بخش «دریافت مجموعه داده» مراجعه کنید.

همچنین می‌توانید داده‌های جدید را به مجموعه داده‌ها آپلود کنید تا نسخه جدیدی از مجموعه داده‌ها ایجاد شود. برای آپلود داده‌های جدید، از همان فرآیندی که برای آپلود داده‌ها از فضای ابری یا آپلود داده‌ها از یک فایل انجام دادید، استفاده کنید و داده‌های جدید را برای آپلود مشخص کنید.

اگر داده‌های جدید با موفقیت آپلود شوند:

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

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

اگر در آپلود خطایی رخ داد:

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

  • STATE_IMPORT_FAILED
  • STATE_PROCESSING_FAILED
  • STATE_PUBLISHING_FAILED
  • STATE_DELETION_FAILED

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