העלאת מניפסט של טבלה

אם אתם זקוקים לגמישות רבה יותר בהעלאת טבלאות ל-Google Earth Engine ‏ (EE) מזו שמספקים ממשק המשתמש של Code Editor או הפקודה upload של כלי שורת הפקודה'earthengine', תוכלו לתאר את ההעלאה של הטבלה באמצעות קובץ JSON שנקרא 'מניפסט', ולהשתמש בפקודה upload table --manifest של כלי שורת הפקודה.

הגדרה חד-פעמית

1. העלאות של מניפסט פועלות רק עם קבצים שנמצאים ב-Google Cloud Storage. כדי להתחיל להשתמש ב-Google Cloud Storage, צריך ליצור פרויקט ב-Google Cloud, אם עדיין אין לכם פרויקט כזה. לתשומת ליבכם: בתהליך ההגדרה צריך לציין כרטיס אשראי לחיוב. בשלב הזה, EE לא מחייבת אף אחד, אבל העברת קבצים ל-Google Cloud Storage לפני ההעלאה ל-EE כרוכה בעלות קטנה. לגבי נתונים רגילים להעלאה (עשרות או מאות ג'יגה-בייט), העלות תהיה נמוכה למדי.
2. בפרויקט, מפעילים את Cloud Storage API ויוצרים קטגוריה.
3. מתקינים את הלקוח של Earth Engine ל-Python. הוא כולל את כלי שורת הפקודה earthengine, שבו נשתמש כדי להעלות נתונים.
4. להעלאות אוטומטיות, מומלץ להשתמש בחשבון שירות ב-Google Cloud שמשויך לפרויקט. אין צורך בחשבון שירות לצורך בדיקה, אבל כדאי להתחיל להכיר את השימוש בו כשיש לכם זמן.

שמות ומזהים של נכסים

לנכסים בפרויקטים ב-Cloud, משתמשים ב-projects/my_cloud_project/assets/my_asset.

בפרויקטים ישנים יותר, שם הנכס במניפסט צריך להיות שונה במקצת ממזהה הנכס שמוצג במקום אחר ב-Earth Engine. כדי להעלות נכסים שמזהי הנכסים שלהם מתחילים ב-users/some_user או ב-projects/some_project, צריך להוסיף את המחרוזת projects/earthengine-legacy/assets/ לתחילת השם של הנכס במניפסט. לדוגמה, צריך להעלות את מזהה הנכס EE‏ users/username/my_table בשם projects/earthengine-legacy/assets/users/username/my_table.

כן, כלומר מזהי projects/some_projects/some_asset מומרים לשמות שבהם projects מופיע פעמיים: projects/earthengine-legacy/assets/projects/some_projects/some_asset. זה אולי מבלבל, אבל הדבר נדרש כדי לעמוד בסטנדרטים של Google Cloud API.

שימוש במניפסטים

מניפסט פשוט ככל האפשר מוצג בהמשך. הפונקציה מעלה קובץ בשם small.csv מקטגוריה של Google Cloud Storage בשם gs://earthengine-test.

{
  "name": "projects/some-project-id/assets/some-asset-id",
  "sources": [
    {
      "uris": [
        "gs://earthengine-test/small.csv"
      ]
    }
  ]
}

כדי להשתמש בו, שומרים אותו בקובץ בשם manifest.json ומריצים את הפקודה הבאה:

earthengine upload table --manifest /path/to/manifest.json

(הקובץ gs://earthengine-test/small.csv קיים ואפשר לקרוא אותו באופן ציבורי – אפשר להשתמש בו לצורך בדיקה).

בהעלאות של קובצי shapefile, מציינים רק את הקובץ עם הסיומת ‎.shp. הקבצים האחרים יזוהו באופן אוטומטי.

מספר מקורות

אפשר לציין כמה מקורות של קובצי CSV או shapefile, עם קובץ אחד לכל מקור. במקרה כזה, לכל קובץ CSV צריך להיות אותו מבנה. לדוגמה, יש לנו שני קובצי CSV, region1.csv ו-region2.csv:

id [מזהה]	צורה
1	{"type":"Point","coordinates":[-119,36]}
2	{"type":"Point","coordinates":[-118,37]}
3	{"type":"Point","coordinates":[-117,38]}

id [מזהה]	צורה
4	{"type":"Point","coordinates":[-112,40]}
5	{"type":"Point","coordinates":[-111,41]}
6	{"type":"Point","coordinates":[-110,42]}

יש להם מבנה זהה, אבל תוכן שונה. הם הועלאו לקטגוריות של Cloud Storage: gs://earthengine-test/region1.csv ו-gs://earthengine-test/region2.csv. כדי להטמיע אותם כנכס של Earth Engine, יוצרים מניפסט עם שתי רשומות ברשימה sources, באופן הבא:

{
  "name": "projects/some-project-id/assets/some-asset-id",
  "sources": [
    {
      "uris": [
        "gs://earthengine-test/region1.csv"
      ]
    },
    {
      "uris": [
        "gs://earthengine-test/region2.csv"
      ]
    }
  ]
}

שעת התחלה ושעת סיום

כדאי לציין את שעת ההתחלה ושעת הסיום של כל הנכסים כדי לספק הקשר נוסף לנתונים, במיוחד אם הם כלולים באוספים. השדות האלה לא נדרשים, אבל מומלץ מאוד להשתמש בהם כשהדבר אפשרי.

בדרך כלל, זמן ההתחלה והסיום מתייחסים לזמן התצפית, ולא לזמן יצירת קובץ המקור.

מטעמי פשטות, זמן הסיום נחשב כגבול בלעדי. לדוגמה, לנכסים שנמשכים יום אחד בדיוק, צריך להשתמש בשעת חצות של שני ימים רצופים (לדוגמה, 1980-01-31T00:00:00 ו-1980-02-01T00:00:00) לשעת ההתחלה ולשעת הסיום. אם לנכס אין משך זמן, מגדירים את שעת הסיום כזוה לשעת ההתחלה. ייצוג השעות במניפסטים כמחרוזות ISO 8601. כדי לפשט את ערכי התאריכים, מומלץ להניח שזמן הסיום הוא בלעדי (לדוגמה, חצות של היום הבא לנכסים יומיים).

דוגמה:

{
  "name": "projects/some-project-id/assets/some-asset-id",
  "sources": [
    {
      "uris": [
        "gs://bucket/table_20190612.csv"
      ]
    }
  ],
  "startTime": "1980-01-31T00:00:00Z",
  "endTime": "1980-02-01T00:00:00Z"
}

מסמך עזר בנושא מבנה המניפסט

מבנה ה-JSON הבא כולל את כל השדות האפשריים של מניפסט להעלאת טבלה. הגדרות השדות מפורטות בקטע הגדרות השדות של המניפסט שבהמשך.

{
  "name": <string>,
  "sources": [
    {
      "uris": [
        <string>
      ],
      "charset": <string>,
      "maxErrorMeters": <double>,
      "maxVertices": <int32>,
      "crs": <string>,
      "geodesic": <boolean>,
      "primaryGeometryColumn": <string>,
      "xColumn": <string>,
      "yColumn": <string>,
      "dateFormat": <string>,
      "csvDelimiter": <string>,
      "csvQualifier": <string>,
    }
  ],
  "uriPrefix": <string>,
  "startTime": {
    "seconds": <integer>
  },
  "endTime": {
    "seconds": <integer>
  },
  "properties": {
    <unspecified>
  }
}

הגדרות של שדות מניפסט

שם

string

השם של הנכס שייווצר. name הוא בפורמט 'projects/*/assets/**' (לדוגמה, projects/earthengine-legacy/assets/users/USER/ASSET).

מקורות

list

רשימה של שדות שמגדירים את המאפיינים של קובץ טבלה ואת קובצי הצדדים שלו. מידע נוסף זמין בשדות הבאים של רכיבי המילון sources.

sources[i].uris

list

רשימה של מזהי ה-URI של הנתונים להטמעה. בשלב הזה יש תמיכה רק במזהי URI של Google Cloud Storage. כל מזהה URI צריך להיות מוגדר בפורמט הבא: gs://bucket-id/object-id. האובייקט הראשי צריך להיות הרכיב הראשון ברשימה, והקונטיינרים המשניים צריכים להופיע אחריו. אם ההגדרה מוגדרת, לכל מזהה URI מצורפת הקידומת TableManifest.uri_prefix.

sources[i].charset

string

השם של ברירת המחדל של ערכת התווים לצורך פענוח מחרוזות. אם השדה ריק, המערכת תשתמש בברירת המחדל של קודק 'UTF-8'.

sources[i].maxErrorMeters

double

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

sources[i].maxVertices

int32

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

sources[i].crs

string

קוד ברירת המחדל של CRS או מחרוזת WKT שמציינת את מערכת העזר של הקואורדינטות של כל גיאומטריה שלא צוינה לה מערכת כזו. אם השדה הזה יישאר ריק, ברירת המחדל תהיה EPSG:4326. למקורות CSV/TFRecord בלבד.

sources[i].geodesic

boolean

שיטת ברירת המחדל לניתוח קצוות בגיאומטריה שלא הוגדרה להם שיטת ניתוח אחרת. אם הערך הוא false, הקצוות ישרים בתצוגה. אם הערך הוא true, הקצוות יהיו מעוגלים כדי לעקוב אחרי הנתיב הקצר ביותר על פני כדור הארץ. אם השדה הזה ריק, ברירת המחדל היא false אם מערכת העזר היא מערכת קואורדינטות פרויקטיבית. למקורות CSV/TFRecord בלבד.

sources[i].primaryGeometryColumn

string

עמודת הגיאומטריה שישמש כגיאומטריה הראשית של השורה כשיש יותר מעמודת גיאומטריה אחת.

אם השדה הזה נשאר ריק ויש יותר מעמודת גיאומטריה אחת, המערכת תשתמש בעמודת הגיאומטריה הראשונה שנמצאת. למקורות CSV/TFRecord בלבד.

sources[i].xColumn

string

השם של עמודת קואורדינטת ה-x המספרי, לצורך הסקת הגיאומטריה של הנקודה. אם גם הערך של yColumn צוין ושתי העמודות מכילות ערכים מספריים, תיבנה עמודה של גיאומטריה של נקודה עם ערכי x,y במערכת הקואורדינטות שצוינה ב-CRS. אם השדה הזה יישאר ריק, ומערכת העזר לא מציינת מערכת קואורדינטות פרויקטיבית, הערך שמוגדר כברירת מחדל הוא 'longtitude'. אם השדה הזה יישאר ריק ומערכת העזר לשרטוט מפה כן מציינת מערכת קואורדינטות מוקרנת, ברירת המחדל היא מחרוזת ריקה ולא נוצרת גיאומטריה של נקודה.

עמודת גיאומטריה של נקודה שנוצרה תיקרא {xColumn}_{yColumn}_N, כאשר הספרה N תתווסף כך ש-{xColumn}_{yColumn}_N יהיה ייחודי אם כבר קיימת עמודה בשם {xColumn}_{yColumn}. למקורות CSV/TFRecord בלבד.

sources[i].yColumn

string

השם של עמודת הקואורדינטה המספרית של ציר y, לצורך הסקת הגיאומטריה של הנקודה. אם גם הערך של xColumn צוין ושתי העמודות מכילות ערכים מספריים, תיבנה עמודה של גיאומטריה של נקודה עם ערכי x,y במערכת הקואורדינטות שצוינה ב-CRS. אם השדה הזה יישאר ריק, ומערכת העזר לא מציינת מערכת קואורדינטות פרויקטיבית, הערך שמוגדר כברירת מחדל הוא 'latitude'. אם השדה הזה יישאר ריק ומערכת העזר לשרטוט מפה כן מציינת מערכת קואורדינטות מוקרנת, ברירת המחדל היא מחרוזת ריקה ולא נוצרת גיאומטריה של נקודה.

עמודת גיאומטריה של נקודה שנוצרה תיקרא {xColumn}_{yColumn}_N, כאשר הספרה N תתווסף כך ש-{xColumn}_{yColumn}_N יהיה ייחודי אם כבר קיימת עמודה בשם {xColumn}_{yColumn}. למקורות CSV/TFRecord בלבד.

sources[i].dateFormat

string

פורמט לניתוח שדות שמקודדים תאריכים. דפוס הפורמט חייב להיות כפי שמתואר בתיעוד של הכיתה DateTimeFormat ב-Joda-Time. אם השדה הזה יישאר ריק, התאריכים ייובאו כמחרוזות. רק למקורות מסוג CSV/TFRecord.

sources[i].csvDelimiter

string

כשמזינים קובצי CSV, תו יחיד שמשמש כמפריד בין ערכי העמודות בשורה. אם השדה הזה יישאר ריק, הערך שמוגדר כברירת מחדל הוא ','. למקורות CSV בלבד.

sources[i].csvQualifier

string

כשמזינים קובצי CSV, תו שמקיף את ערכי העמודות (נקרא גם "תו מירכאות"). אם השדה הזה יישאר ריק, הערך שמוגדר כברירת מחדל הוא ". למקורות CSV בלבד.

אם ערך עמודת לא מוקף במאפייני הסינון, הרווח ליד הערך ובסופו ייחתך. לדוגמה:

    ..., test,...            <== this value is not qualified
becomes the string value:
    "test"                   <== leading whitespace is stripped

בזמן:

    ...," test",...          <== this value IS qualified with quotes
becomes the string value:
    " test"                  <== leading whitespace remains!

uriPrefix

string

קידומת אופציונלית שנוספת לכל הערכים של uris שמוגדרים במניפסט.

startTime

integer

חותמת הזמן המשויכת לנכס, אם יש כזו. בדרך כלל הוא תואם לזמן שבו הנתונים נאספו. בנכסים שתואמים למרווח זמן מסוים, כמו ערכים ממוצעים לאורך חודש או שנה, חותמת הזמן הזו תואמת לתחילת המרווח. מצוין בשניות ובנאנו-שניות (אופציונלי) מאז תחילת הזמן (1 בינואר 1970). ההנחה היא שהשעה היא לפי אזור הזמן UTC.

endTime

integer

בנכסים שתואמים למרווח זמן מסוים, כמו ערכים ממוצעים במהלך חודש או שנה, חותמת הזמן הזו תואמת לסוף המרווח הזה (לא כולל). מצוין בשניות ובנאנו-שניות (אופציונלי) מאז תחילת הזמן (1 בינואר 1970). ההנחה היא שהשעה היא לפי אזור הזמן UTC.

נכסים

dictionary

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

columnDataTypeOverrides

dictionary

אם זיהוי הסוג האוטומטי לא פועל בצורה תקינה, אפשר להשתמש בשדה הזה עם שמות העמודות כמפתחות ואחת מהקבועות הבאות כערכים: COLUMN_DATA_TYPE_STRING, ‏ COLUMN_DATA_TYPE_NUMERIC,‏ COLUMN_DATA_TYPE_LONG.

מגבלות

גודל המניפסט ב-JSON

מגבלת הגודל של קובץ המניפסט בפורמט JSON היא 10MB. אם אתם צריכים להעלות הרבה קבצים, כדאי למצוא דרכים לצמצם את מספר התווים הנדרשים לתיאור מערך הנתונים. לדוגמה, אפשר להשתמש בשדה uriPrefix כדי לבטל את הצורך לספק את נתיב הקטגוריה ב-GCP לכל URI ברשימה uris. אם צריך לצמצם את הגודל עוד יותר, אפשר לנסות לקצר את שמות הקבצים.