ה-Data Datasets API נמצא כרגע בתצוגה מקדימה (pre-GA). יכול להיות שהתמיכה בתכונות ובמוצרים טרום-GA תהיה מוגבלת. לכן, ייתכן ששינויים בתכונות ובמוצרים לפני טרום-GA לא יתאימו לגרסאות אחרות של טרום-GA. מוצרים במצב טרום-GA כפופים לתנאים הספציפיים לשירות הפלטפורמה של מפות Google. מידע נוסף זמין בקטע תיאורים של שלבי ההשקה.

דף זה תורגם על ידי Cloud Translation API.

Switch to English

יצירת מערך נתונים

יצירת מערך נתונים היא תהליך דו-שלבי:

שולחים בקשה ליצירת מערך הנתונים.
שולחים בקשה להעלאת נתונים למערך הנתונים.

דרישות מוקדמות

כשיוצרים מערך נתונים:

השמות המוצגים צריכים להיות ייחודיים בפרויקט ב-Google Cloud.
שמות תצוגה חייבים להיות קטנים מ-64 בייטים (מכיוון שהתווים האלה מיוצגים ב-UTF-8, בשפות מסוימות כל תו יכול להיות מיוצג על ידי מספר בייטים).
התיאורים חייבים להיות בגודל של פחות מ-1,000 בייטים.

כשמעלים נתונים:

סוגי הקבצים הנתמכים הם CSV , GeoJSON ו-KML.
גודל הקובץ המקסימלי הנתמך הוא 350MB.
שמות עמודות של מאפיינים לא יכולים להתחיל במחרוזת "?_".
אין תמיכה בגאומטריה תלת-ממדית. זה כולל את הסיומת "Z" בפורמט WKT, ואת קואורדינטת הגובה בפורמט GeoJSON.

דרישות לשימוש ב-GeoJSON

ה-API של 'מערכי הנתונים של מפות Google' תומך במפרט הנוכחי של GeoJSON. ה-API של מערכי הנתונים של מפות Google תומך גם בקובצי GeoJSON שמכילים כל אחד מסוגי האובייקטים הבאים:

אובייקטים גיאומטריים. אובייקט גיאומטרי הוא צורה מרחבית, המתוארת כאיחוד של נקודות, קווים ומצולעים עם חורים אופציונליים.
אובייקטי Feature. אובייקט תכונה מכיל גיאומטריה ועוד צמדים של שם/ערך, שהמשמעות שלהם ספציפית לאפליקציה.
אוספים של תכונות אוסף תכונות הוא קבוצה של אובייקטים של תכונות.

ה-API של מערכי הנתונים של מפות Google לא תומך בקובצי GeoJSON שיש בהם נתונים במערכת הפניה לקואורדינטות (CRS) שאינה WGS84.

למידע נוסף על GeoJSON, אפשר לעיין במאמר תאימות לתקן RFC 7946.

דרישות לקובצי KML

על ה-API של מפות Google Datasets יש את הדרישות הבאות:

כל כתובות ה-URL חייבות להיות מקומיות (או יחסיות) לקובץ עצמו.
תמיכה בגאומטריה של נקודה, קווים ופוליגונים.
כל מאפייני הנתונים נחשבים למחרוזות.

תכונות 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 כחלק מכל הגדרה של אובייקט 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'

הערה: בשלב זה, USAGE_DATA_DRIVEN_STYLING הוא הערך היחיד שנתמך במאפיין usage.

לדוגמה:

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