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

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

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

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

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

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

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

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

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

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

דרישות ל-GeoJSON

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

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

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

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

דרישות לגבי KML

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

כל כתובות ה-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 חייבות להיות בעמודות נפרדות.
שמות העמודות לא תלויי אותיות רישיות (case-sensitive).
אין חשיבות לסדר של שמות העמודות. לדוגמה, אם קובץ ה-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
הערה: שגיאה זו מתוארת לעיתים קרובות באמצעות הודעה מסוג "לא ניתן להמיר את ' ' ל-double" או "לא ניתן לנתח את הקלט למיקום גיאוגרפי.: הערך הגיאוגרפי חסר".
אם 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 הוא 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"
}

העלאת נתונים מקובץ

כדי להעלות נתונים מקובץ, צריך לשלוח בקשת HTTP POST לנקודת הקצה 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"
}