יצירת מערך נתונים היא תהליך דו-שלבי:
שולחים בקשה ליצירת מערך הנתונים.
שולחים בקשה להעלאת נתונים למערך הנתונים.
אחרי העלאת הנתונים הראשונית, אפשר להעלות נתונים חדשים למערך הנתונים כדי ליצור גרסה חדשה של מערך הנתונים.
דרישות מוקדמות
כשיוצרים מערך נתונים:
- השמות המוצגים חייבים להיות ייחודיים בפרויקט שלכם ב-Google Cloud.
- השמות לתצוגה צריכים להיות קטנים מ-64 בייטים (מכיוון שהתווים האלה מיוצגים ב-UTF-8, בשפות מסוימות כל תו יכול להיות מיוצג על ידי מספר בייטים).
- התיאורים חייבים להיות קטנים מ-1,000 בייטים.
כשמעלים נתונים:
- סוגי הקבצים הנתמכים הם CSV , GeoJSON ו-KML.
- גודל הקובץ המקסימלי הנתמך הוא 350MB.
- השמות של עמודות המאפיינים לא יכולים להתחיל במחרוזת "?_".
- אין תמיכה בגיאומטריה תלת ממדית. הנתונים האלה כוללים את הסיומת 'Z' בפורמט WKT ואת קואורדינטות הגובה בפורמט GeoJSON.
שיטות מומלצות להכנת נתונים
אם נתוני המקור מורכבים או גדולים, כמו נקודות צפופות, מחרוזות שורות ארוכות או פוליגונים (בדרך כלל קובצי מקור בגודל של יותר מ-50MB נכללים בקטגוריה הזו), כדאי לפשט את הנתונים לפני ההעלאה כדי להשיג את הביצועים הטובים ביותר במפה ויזואלית.
ריכזנו כאן כמה שיטות מומלצות להכנת הנתונים:
- מזעור המאפיינים של התכונות. צריך לשמור רק את מאפייני התכונות שנדרשים כדי לעצב את המפה, למשל 'id' ו-'category'. אפשר לצרף מאפיינים נוספים לתכונה באפליקציית לקוח באמצעות סגנונות מבוססי-נתונים במפתח מזהה ייחודי. לדוגמה, אפשר לעיין במאמר הצגת הנתונים בזמן אמת בעזרת סגנון מבוסס-נתונים.
- אם אפשר, כדאי להשתמש בסוגי נתונים פשוטים לאובייקטים של המאפיינים, כמו מספרים שלמים, כדי להקטין את גודל המשבצות ולשפר את ביצועי המפה.
- לפני העלאת קובץ, הגדירו צורות גיאומטריות מורכבות. אפשר לעשות את זה בכלי גיאו-מרחבי לבחירתכם, כמו כלי הקוד הפתוח Mapshaper.org, או ב-BigQuery באמצעות ST_Simplify עם צורות גיאומטריות מורכבות של פוליגונים.
- לאסוף נקודות צפופות מאוד לפני העלאת קובץ. אפשר לעשות את זה בכלי גיאו-מרחבי לבחירתך, כמו הפונקציות של אשכול turf.js בקוד פתוח, או ב-BigQuery באמצעות ST_CLUSTERDBSCAN על צורות גיאומטריות של נקודות צפופות.
הנחיות נוספות לגבי שיטות מומלצות במערכי נתונים מפורטות במאמר המחשה חזותית של נתונים באמצעות מערכי נתונים ו-BigQuery.
דרישות לגבי GeoJSON
Maps Datasets API תומך במפרט GeoJSON הנוכחי. ב-Maps Datasets API יש גם תמיכה בקובצי GeoJSON שמכילים כל אחד מסוגי האובייקטים הבאים:
- אובייקטים גיאומטריים. אובייקט גיאומטרי הוא צורה מרחבית, שמתוארת כאיחוד של נקודות, קווים ופוליגונים עם חורים אופציונליים.
- הצגת אובייקטים. אובייקט של מאפיין מכיל גיאומטריה יחד עם צמדים נוספים של שם/ערך, שהמשמעות שלהם היא ספציפית לאפליקציה.
- אוספים של תכונות אוסף פיצ'רים הוא קבוצה של אובייקטים של ישויות.
ב-Maps Datasets API אין תמיכה בקובצי GeoJSON שמכילים נתונים במערכת ייחוס קואורדינטות (CRS), מלבד WGS84.
מידע נוסף על GeoJSON זמין במאמר תאימות ל-RFC 7946.
דרישות KML
ממשק ה-API של מפות Google כולל את הדרישות הבאות:
- כל כתובות ה-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
כחלק מכל אובייקט של תכונה והגדרה של אובייקט גיאומטרי.
שגיאות 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 או מקובץ מקומי למערך הנתונים.
העלאת נתונים מ-Cloud Storage
כדי להעלות מ-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.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" }
העלאת נתונים מקובץ
כדי להעלות נתונים מקובץ, שולחים בקשת POST
HTTP לנקודת הקצה datasets שכוללת גם את המזהה של מערך הנתונים:
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
של מערך הנתונים, ראו קבלת מערך נתונים.
אפשר גם להעלות נתונים חדשים למערך הנתונים כדי ליצור גרסה חדשה של מערך הנתונים. כדי להעלות נתונים חדשים, פועלים לפי אותו תהליך שביצעתם כדי להעלות נתונים מ-Cloud Storage או להעלות נתונים מקובץ, ומציינים את הנתונים החדשים להעלאה.
אם הנתונים החדשים יועלו בהצלחה:
המצב של הגרסה החדשה של מערך הנתונים מוגדר כ-
STATE_COMPLETED
.הגרסה החדשה הופכת לגרסה ה "פעילה", והיא הגרסה שבה האפליקציה משתמשת.
אם יש שגיאה בהעלאה:
המצב של הגרסה החדשה של מערך הנתונים מוגדר לאחד מהמצבים הבאים:
STATE_IMPORT_FAILED
STATE_PROCESSING_FAILED
STATE_PUBLISHING_FAILED
STATE_DELETION_FAILED
הגרסה הקודמת של מערך הנתונים שהסתיימה בהצלחה נשארת כגרסה ה'פעילה', והיא הגרסה שבה האפליקציה משתמשת.