ایجاد یک مجموعه داده یک فرآیند دو مرحله ای است:
برای ایجاد مجموعه داده درخواست دهید.
درخواستی برای آپلود داده ها در مجموعه داده ارائه دهید.
پس از آپلود داده های اولیه، می توانید داده های جدید را در مجموعه داده آپلود کنید تا نسخه جدیدی از مجموعه داده ایجاد کنید.
پیش نیازها
هنگام ایجاد یک مجموعه داده:
- نامهای نمایشی باید در پروژه Google Cloud شما منحصربهفرد باشند.
- نام های نمایشی باید کمتر از 64 بایت باشند (از آنجایی که این کاراکترها در UTF-8 نشان داده می شوند، در برخی از زبان ها هر کاراکتر را می توان با چندین بایت نشان داد).
- توضیحات باید کمتر از 1000 بایت باشد.
هنگام آپلود داده ها:
- انواع فایل های پشتیبانی شده CSV، GeoJSON و KML هستند.
- حداکثر اندازه فایل پشتیبانی شده 350 مگابایت است.
- نام ستون های مشخصه نمی تواند با رشته "?_" شروع شود.
- هندسه های سه بعدی پشتیبانی نمی شوند. این شامل پسوند "Z" در قالب WKT و مختصات ارتفاع در قالب GeoJSON است.
بهترین شیوه های آماده سازی داده ها
اگر دادههای منبع شما پیچیده یا بزرگ است، مانند نقاط متراکم، رشتههای بلند یا چند ضلعی (اغلب اندازه فایل منبع بزرگتر از 50 مگابایت در این دسته قرار میگیرد)، قبل از آپلود، دادههای خود را ساده کنید تا به بهترین عملکرد در نقشه بصری دست یابید.
در اینجا برخی از بهترین روش ها برای آماده سازی داده های شما آورده شده است:
- ویژگی های ویژگی را به حداقل برسانید . فقط ویژگی های ویژگی مورد نیاز برای استایل دادن به نقشه خود را حفظ کنید، به عنوان مثال "id" و "category". میتوانید ویژگیهای اضافی را با استفاده از سبکهای مبتنی بر داده در یک کلید شناسه منحصربهفرد به یک ویژگی در برنامه مشتری ملحق کنید. برای مثال، مشاهده دادههای خود را در زمان واقعی با استایل مبتنی بر دادهها ببینید.
- در صورت امکان از انواع داده های ساده برای اشیاء دارایی، مانند اعداد صحیح، برای به حداقل رساندن اندازه کاشی و بهبود عملکرد نقشه استفاده کنید .
- قبل از آپلود فایل ، هندسه های پیچیده را ساده کنید . میتوانید این کار را در یک ابزار جغرافیایی انتخابی خود، مانند ابزار منبع باز Mapshaper.org یا در BigQuery با استفاده از ST_Simplify در هندسههای چندضلعی پیچیده انجام دهید.
- قبل از آپلود فایل ، نقاط بسیار متراکم را دسته بندی کنید . شما می توانید این کار را در یک ابزار مکانی انتخابی خود، مانند توابع خوشه منبع باز turf.js ، یا در BigQuery با استفاده از ST_CLUSTERDBSCAN در هندسه های نقطه متراکم انجام دهید.
در Visualize your data with Datasets و BigQuery، راهنماییهای اضافی درباره بهترین شیوههای مجموعه دادهها را ببینید.
الزامات GeoJSON
Maps Datasets API از مشخصات GeoJSON فعلی پشتیبانی می کند. Maps Datasets API همچنین از فایلهای GeoJSON که حاوی هر یک از انواع شیء زیر هستند پشتیبانی میکند:
- اجسام هندسی شیء هندسی یک شکل فضایی است که به عنوان اتحاد نقاط، خطوط و چندضلعی ها با سوراخ های اختیاری توصیف می شود.
- اشیاء را مشخص کنید . یک شیء ویژگی شامل یک هندسه به اضافه جفتهای نام/مقدار اضافی است که معنای آنها مختص کاربرد است.
- مجموعه های ویژه مجموعه ویژگی مجموعه ای از اشیاء ویژگی است.
Maps Datasets API از فایلهای GeoJSON که دادههایی در یک سیستم مرجع مختصات (CRS) غیر از WGS84 دارند، پشتیبانی نمیکند.
برای اطلاعات بیشتر در مورد GeoJSON، مطابق با RFC 7946 را ببینید.
الزامات KML
Maps Datasets API شرایط زیر را دارد:
- همه URL ها باید محلی (یا نسبی) به خود فایل باشند.
- هندسه نقطه، خط و چند ضلعی پشتیبانی می شود.
- تمام ویژگی های داده رشته ها در نظر گرفته می شوند.
- نمادها یا
<styleUrl>
که خارج از فایل تعریف شده است. - پیوندهای شبکه، مانند
<NetworkLink>
- پوشش های زمینی، مانند
<GroundOverlay>
- هندسه های سه بعدی یا هر برچسب مرتبط با ارتفاع مانند
<altitudeMode>
- مشخصات دوربین مانند
<LookAt>
- سبک های تعریف شده در داخل فایل KML.
الزامات CSV
برای فایلهای CSV، نام ستونهای پشتیبانیشده به ترتیب اولویت در زیر فهرست شدهاند:
-
latitude
longitude
-
lat
،long
-
x
،y
-
wkt
(متن معروف) -
address
،city
،state
،zip
-
address
- یک ستون شامل تمام اطلاعات آدرس، مانند
1600 Amphitheatre Parkway Mountain View, CA 94043
به عنوان مثال، فایل شما حاوی ستون هایی با نام های x
، y
و wkt
است. از آنجایی که x
و y
اولویت بیشتری دارند، همانطور که با ترتیب نام ستون های پشتیبانی شده در لیست بالا مشخص می شود، از مقادیر ستون های x
و y
استفاده می شود و ستون wkt
نادیده گرفته می شود.
علاوه بر این:
- نام هر ستون باید متعلق به یک ستون باشد. یعنی شما نمی توانید ستونی به نام
xy
داشته باشید که حاوی داده های مختصات x و y باشد. مختصات x و y باید در ستون های جداگانه باشند. - نام ستون ها به حروف بزرگ و کوچک حساس هستند.
- ترتیب نام ستون ها مهم نیست. به عنوان مثال، اگر فایل CSV شما حاوی ستون های
lat
وlong
باشد، می توانند به هر ترتیبی رخ دهند.
خطاهای آپلود داده را مدیریت کنید
هنگام آپلود داده ها در یک مجموعه داده، ممکن است یکی از خطاهای رایج شرح داده شده در این بخش را تجربه کنید.
خطاهای GeoJSON
خطاهای رایج GeoJSON عبارتند از:
- فیلد
type
وجود ندارد، یاtype
رشته نیست. فایل داده GeoJSON آپلود شده باید دارای یک فیلد رشته ای به نامtype
به عنوان بخشی از هر شی Feature و تعریف شی هندسه باشد.
خطاهای KML
خطاهای رایج KML عبارتند از:
- فایل داده نباید دارای هیچ یک از ویژگی های KML پشتیبانی نشده ذکر شده در بالا باشد، در غیر این صورت ممکن است وارد کردن داده ها با شکست مواجه شود.
خطاهای CSV
خطاهای رایج CSV عبارتند از:
- برخی از سطرها مقادیری برای یک ستون هندسه ندارند. همه ردیفهای یک فایل CSV باید حاوی مقادیر غیر خالی برای ستونهای هندسه باشند. ستون های هندسی عبارتند از:
-
latitude
longitude
-
lat
،long
-
x
،y
-
wkt
-
address
،city
،state
،zip
-
address
- یک ستون شامل تمام اطلاعات آدرس، مانند
1600 Amphitheatre Parkway Mountain View, CA 94043
-
- اگر
x
وy
ستون های هندسی شما هستند، مطمئن شوید که واحدها طول و عرض جغرافیایی هستند. برخی از مجموعه داده های عمومی از سیستم های مختصات متفاوتی در زیر سربرگ هایx
وy
استفاده می کنند. اگر از واحدهای اشتباه استفاده شود، مجموعه داده ممکن است با موفقیت وارد شود، اما داده های ارائه شده می توانند نقاط داده را در مکان های غیرمنتظره نشان دهند.
مجموعه داده را ایجاد کنید
با ارسال یک درخواست 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 یا از یک فایل محلی در مجموعه داده آپلود کنید.
داده ها را از فضای ذخیره سازی ابری بارگذاری کنید
با ارسال یک درخواست 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" }
داده های جدید را در مجموعه داده آپلود کنید
پس از ایجاد مجموعه داده و آپلود داده های اولیه با موفقیت، وضعیت مجموعه داده روی STATE_COMPLETED
تنظیم می شود. این بدان معناست که مجموعه داده برای استفاده در برنامه شما آماده است. برای تعیین state
مجموعه داده، به دریافت یک مجموعه داده مراجعه کنید.
همچنین می توانید داده های جدیدی را در مجموعه داده آپلود کنید تا نسخه جدیدی از مجموعه داده ایجاد کنید. برای آپلود دادههای جدید، از همان فرآیندی که برای آپلود دادهها از فضای ذخیرهسازی ابری یا آپلود دادهها از یک فایل انجام دادید، استفاده کنید و دادههای جدید را برای آپلود مشخص کنید.
اگر داده های جدید با موفقیت آپلود شوند:
وضعیت نسخه جدید مجموعه داده روی
STATE_COMPLETED
تنظیم شده است.نسخه جدید به نسخه "فعال" تبدیل می شود و نسخه ای است که توسط برنامه شما استفاده می شود.
اگر در آپلود خطایی وجود دارد:
وضعیت نسخه مجموعه داده جدید به یکی از حالات زیر تنظیم شده است:
-
STATE_IMPORT_FAILED
-
STATE_PROCESSING_FAILED
-
STATE_PUBLISHING_FAILED
-
STATE_DELETION_FAILED
-
نسخه موفق مجموعه داده قبلی به عنوان نسخه "فعال" باقی می ماند و نسخه ای است که توسط برنامه شما استفاده می شود.