قبل‌از شروع

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

پیش‌نیازها

هنگام ایجاد مجموعه داده:

  • نام‌های نمایشی باید در پروژه Google Cloud شما یکتا باشند.
  • نام‌های نمایشی باید کمتر از ۶۴ بایت باشند (چون این نویسه‌ها در UTF-8 نشان داده می‌شوند، در برخی‌از زبان‌ها هر نویسه می‌تواند با چند بایت نشان داده شود).
  • شرح باید کمتر از ۱۰۰۰ بایت باشد.

هنگام بارگذاری داده‌ها:

  • انواع فایل‌های پشتیبانی‌شده عبارت‌اند از CSV،‏ GeoJSON، و KML.
  • حداکثر اندازه فایل پشتیبانی‌شده ۵۰۰ مگابایت است.
  • نام ستون مشخصه نمی‌تواند با رشته «?_» شروع شود.
  • هندسه‌های سه‌بعدی پشتیبانی نمی‌شوند. این شامل پسوند «Z» در قالب WKT، و مختصات ارتفاع در قالب GeoJSON می‌شود.

روال‌های مطلوب آماده‌سازی داده‌ها

اگر داده‌های منبع شما پیچیده یا بزرگ است، مانند نقاط متراکم، رشته‌های خطی طولانی یا چندضلعی‌ها (اغلب اندازه‌های فایل منبع بزرگ‌تر از ۵۰ مگابایت در این دسته قرار می‌گیرند)، برای دستیابی به بهترین عملکرد در نقشه بصری، داده‌های خود را قبل از بارگذاری ساده کنید.

در اینجا برخی‌از روال‌های مطلوب برای آماده‌سازی داده‌هایتان آورده شده است:

  1. ویژگی‌های مشخصه را کوچک کنید. فقط ویژگی‌های عارضه‌ای را که برای سبک‌بندی نقشه‌تان لازم است نگه دارید، برای مثال «شناسه» و «دسته». می‌توانید بااستفاده از سبک‌های داده‌محور در کلید شناسه یکتا، دارایی‌های بیشتری را به ویژگی در برنامه کارخواه ملحق کنید. برای مثال، دیدن داده‌ها به‌طور هم‌زمان با «سبک‌بندی داده‌محور» را ببینید.
  2. درصورت امکان، برای اشیای ویژگی از انواع داده‌های ساده استفاده کنید، مانند اعداد صحیح، تا اندازه کاشی‌ها را به حداقل برسانید و عملکرد نقشه را بهبود بخشید.
  3. پیش‌از بارگذاری فایل، هندسه‌های پیچیده را ساده کنید. می‌توانید این کار را در ابزار جغرافیایی فضایی دلخواهتان، مثل برنامه کمکی منبع باز Mapshaper.org، یا در BigQuery بااستفاده از ST_Simplify در هندسه‌های چندضلعی پیچیده انجام دهید.
  4. پیش‌از بارگذاری فایل، نقاط بسیار متراکم را خوشه‌بندی کنید. می‌توانید این کار را در ابزار جغرافیایی-فضایی موردنظرتان، مثل توابع خوشه turf.js متن‌باز، یا در BigQuery بااستفاده از ST_CLUSTERDBSCAN روی هندسه‌های نقطه متراکم انجام دهید.

در دیداری‌سازی کردن داده‌ها با مجموعه‌های داده و BigQuery، راهنمایی‌های بیشتری درباره روال‌های مطلوب مجموعه‌های داده ببینید.

الزامات GeoJSON

«میانای برنامه‌سازی کاربردی مجموعه‌های داده Maps» از مشخصات GeoJSON فعلی پشتیبانی می‌کند. «میانای برنامه‌سازی کاربردی مجموعه‌های داده Maps» از فایل‌های GeoJSON که حاوی هریک از انواع شیء زیر است نیز پشتیبانی می‌کند:

  • اشیاء هندسی. شیء هندسی شکلی فضایی است که به‌عنوان مجموعه‌ای از نقاط، خطوط، و چندضلعی‌ها با سوراخ‌های اختیاری توصیف می‌شود.
  • ویژگی‌های اشیا. یک شیء عارضه حاوی یک هندسه به‌علاوه جفت‌های نام/مقدار اضافی است که معنی آن مختص برنامه است.
  • مجموعه‌های ویژگی. مجموعه عارضه‌ها مجموعه‌ای از اشیای عارضه است.

«میانای برنامه‌سازی کاربردی مجموعه‌های داده Maps» از فایل‌های GeoJSON که داده‌هایشان در سیستم مرجع مختصات (CRS) دیگری به‌جز WGS84 باشد پشتیبانی نمی‌کند.

برای کسب اطلاعات بیشتر درباره GeoJSON، به مطابق با RFC 7946 مراجعه کنید.

الزامات KML

‫Maps Datasets API الزامات زیر را دارد:

  • همه نشانی‌های وب باید نسبت به خود فایل محلی (یا نسبی) باشند.
  • از هندسه‌های نقطه‌ای، خطی، و چندضلعی پشتیبانی می‌شود.
  • همه مشخصه‌های داده رشته درنظر گرفته می‌شوند.
از ویژگی‌های KML زیر پشتیبانی نمی‌شود:
  • نمادها یا <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 را به‌عنوان بخشی از هر تعریف شیء «ویژگی» و شیء «هندسه» داشته باشد.

خطاهای 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 استفاده می‌کنند. اگر از واحدهای اشتباه استفاده شود، مجموعه داده ممکن است با موفقیت وارد شود، اما داده‌های پردازش‌شده می‌توانند نقاط مجموعه داده را در مکان‌های غیرمنتظره نشان دهند.