הודעה: כל הפרויקטים הלא מסחריים שנרשמו לשימוש ב-Earth Engine לפני 15 באפריל 2025 חייבים לעבור אימות של הזכאות לשימוש לא מסחרי כדי לשמור על הגישה ל-Earth Engine.

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

אימות והפעלה

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

הכלי לעריכת קוד ב-Earth Engine ו-JavaScript

האימות וההפעלה מתבצעים באופן אוטומטי בכלי לעריכת קוד. אפשר לנתב בקשות דרך פרויקט ב-Cloud מההתחברות שלכם בפינה השמאלית העליונה של Code Editor.

אם אתם משתמשים ב-JavaScript API (מחוץ ל-Code Editor), צריך להשתמש באחת מהפונקציות העזר לאימות ב-ee.data (לדוגמה, ee.data.authenticateViaPopup()) ואז ב-ee.initialize(), כפי שמתואר בדוגמה הזו.

Python ושורת הפקודה

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

    ee.Authenticate()
    ee.Initialize(project='my-project')

קודם כול, המערכת תבחר את מצב האימות המתאים ביותר לסביבה שלכם, ואז תתבקשו לאשר את הגישה לסקריפטים. אם פרטי הכניסה כבר קיימים, הם ישמשו שוב באופן אוטומטי. כדי ליצור פרטי כניסה חדשים, מריצים את הפקודה ee.Authenticate(force=True).

בשלב האיפוס בודקים אם קיימים פרטי כניסה תקינים, שנוצרו מ-ee.Authenticate() או שהיו קיימים מראש כפרטי כניסה שמוגדרים כברירת מחדל ב-Google. לאחר מכן הוא מאתחלל את ספריית הלקוח של Python בשיטות ששרת הקצה העורפי תומך בהן. תצטרכו לספק פרויקט שבבעלותכם, או שיש לכם הרשאות להשתמש בו. במאמר הגדרת פרויקט ב-Cloud מוסבר איך לרשום את הפרויקט ולהפעיל את Earth Engine API. הפרויקט הזה ישמש להרצת כל הפעולות ב-Earth Engine.

בשורת הפקודה, הקריאה המקבילה היא earthengine authenticate. אם התוקף של פרטי הכניסה פג או שהם לא תקינים, יכול להיות שתצטרכו להריץ את הפקודה earthengine authenticate --force. הקריאות בשורת הפקודה יופעלו בכל קריאה, תוכלו להשתמש בארגומנט --project כדי להגדיר את הפרויקט.

אפשר גם להגדיר פרויקט לכל הקריאות העתידיות על ידי הפעלת earthengine set_project {my-project}. שורת הפקודה ו-ee.Initialize() ישתמשו בו בכל פעם שלא יצוין פרויקט באופן ישיר. אם משתמשים באימות דרך gcloud (ראו בהמשך), המערכת תשתמש בפרויקט שהוגדר על ידי gcloud auth application-default set-quota-project {my-project} כמקרה אחרון.

פרטי האימות

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

בגלל הרגישות לסוג המערכות המעורבות, יש דרכים שונות להמשיך בהתאם למצב הספציפי שלכם. רוב האפשרויות נשלטים על ידי הפרמטר auth_mode: בתור ee.Authenticate(auth_mode=...) או earthengine authenticate --auth_mode=... בשורת הפקודה.

הערה: אם פרטי הכניסה ל-Google כבר קיימים בסביבה, יכול להיות שלא תצטרכו להפעיל את ee.Authenticate() בכלל. מכונות וירטואליות ב-Google Cloud, ‏App Engine וסביבות אחרות מספקות "פרטי כניסה בסביבה" שאפשר להשתמש בהם, וגם gcloud auth application-default login תיצור אותם.

עם זאת, מומלץ להוסיף את ee.Authenticate() בתחילת כל סקריפט כדי למקסם את התאימות. ללא הפרמטר auth_mode, הוא אמור לפעול ברוב המצבים, אבל אם מצב ברירת המחדל לא פועל, יש לפעול לפי הפרטים שבהמשך. מצב ברירת המחדל נבחר באופן הבא:

colab אם מריצים ב-notebook של Google Colab
notebook אם מריצים את הקוד ב-notebooks אחרים של Jupyter שאינם של Colab
localhost אם מזוהה דפדפן אינטרנט ואין קובץ בינארי של gcloud מותקן
gcloud, אחרת. כדי להשתמש במצב הזה, צריך להתקין את gcloud.

מדריך וטבלה להתמצאות מהירה

במדריך הזה מפורטות האפשרויות שאפשר לבחור אם מצב ברירת המחדל שנבחר על ידי ee.Authenticate() לא פועל. לדוגמה, אם אתם מריצים את הסביבה בסביבות אחרות של מסמכי הערה, יכול להיות שתצטרכו לציין את notebook באופן מפורש.

סביבה מקומית.
- 'מקומי': אתם מריצים קוד במעטפת Python או ב-notebook של Python במחשב שלכם – או ליתר דיוק, באותו מחשב שבו פועל דפדפן האינטרנט. המצב הזה כולל מצבים של מחשב מרוחק שבהם גם Python וגם הדפדפן נמצאים באותה מכונה (מרוחקת).
- השימוש ב-auth_mode=localhost הוא הקל ביותר, והוא יבחר כברירת מחדל אם gcloud לא מותקן, אבל הסקריפט יפעל רק בסביבות מקומיות.
- גם auth_mode=gcloud וגם auth_mode=notebook זמינים.
סביבה מרוחקת.
- 'מרחוק': הדפדפן נמצא במכונה אחת (מקומית), אבל הקוד פועל במקום אחר, למשל בתחנת עבודה מרוחקת או במחשב נייד מבוסס-אינטרנט.
- אם משתמשים ב-Colab, משתמשים ב-auth_mode=colab. אם צריך להגדיר את scopes כדי לבצע קריאות לממשקי API אחרים, משתמשים ב-gcloud.
- אם אפשר להתקין את gcloud גם במכונה המרוחקת וגם במחשב המקומי, צריך להשתמש ב-auth_mode=gcloud.
- אם אפשר להשתמש בפרויקט אימות (ראו בהמשך), משתמשים ב-auth_mode=notebook.
- אם אתם לא מצליחים להשתמש בפרויקט, להתקין את gcloud, להשתמש ב-Colab או להשתמש בדפדפן באותה מכונה:
- פונים לאדמין (שוב) כדי ליצור פרויקטים. לדוגמה:
  - מבקשים מהאדמין להגדיר עבורכם פרויקט (כבעלי הפרויקט, כבעלי הרשאת עריכה או כבעלי הרשאת עריכה של הגדרות OAuth)
  - לחלופין, אפשר לבקש מהאדמין להעניק לכם הרשאות ליצירת פרויקט.

בטבלה הבאה מוצגים השילובים של התכונות שנתמכים בכל מצב.

	לשימוש מקומי או מרחוק?	פרויקט נדרש	היקפים שניתן להגדיר	נדרש CLI מקומי	בעלי הפרויקט
`localhost`	local	Y	כן	לא	לא
`colab`	שלט רחוק	Y	לא	לא	לא
`gcloud`	את שתי האפשרויות	Y	כן	לא	לא
`notebook`	את שתי האפשרויות	Y	כן	לא	Y

פרטי כניסה לחשבונות שירות ול-Compute Engine

הפונקציה ee.Initialize() תשתמש בפרטי הכניסה של Earth Engine (ש-ee.Authenticate() שומר ב-~/.config/earthengine/credentials) או תאחזר את פרטי הכניסה מ-google.auth.default(). עם זאת, אם יש צורך, אפשר להעביר את הארגומנט credentials= כדי להשתמש בפרטי כניסה ממקור אחר, ולעקוף את הגדרות ברירת המחדל האלה.

אם אתם מאמתים קוד Python שיופעל ללא השגחה, מומלץ לבצע את האימות באמצעות חשבון שירות במקום באמצעות חשבון משתמש. במאמרים האלה מוסבר איך משתמשים בחשבונות שירות ב-Earth Engine. שיטות אחרות כוללות את authenticate_service_account במודול האימות של Colab ואת השיטות שמתוארות במדריך של Cloud לאימות כחשבון שירות.

אם הקוד פועל במכונה וירטואלית (VM) של Compute Engine, נוצר חשבון שירות שמוגדר כברירת מחדל לסביבה, ו-ee.Initialize() ישתמש בו כברירת מחדל. יכול להיות שתצטרכו לרשום את חשבון השירות לשימוש ב-Earth Engine אם פרויקט Cloud שבו הופעל המכונה הווירטואלית לא רשום לשימוש ב-Earth Engine (מסחרי או לא מסחרי).

פרטים על המצבים

auth_mode=colab. ee.Authenticate() תיצור או תקבל את פרטי הכניסה שמוגדרים כברירת מחדל ותומכים ב-Colab, על ידי הפעלת colab.auth.authenticate_user() במקרה הצורך. פרטי הכניסה תמיד משתמשים בהיקף cloud-platform, ואפשר להשתמש בהם גם כדי לבצע קריאות ל-Cloud APIs אחרים.

auth_mode=gcloud. הפקודה הזו מעבירה את תהליך האימות לכלי gcloud, והיא זהה להרצה של gcloud auth application-default login עם היקפי הגישה שמוגדרים כברירת מחדל ב-Earth Engine‏ (earthengine, ‏ cloud-platform ו-drive) או עם היקפי הגישה שצוינו בארגומנט scopes. המצב gcloud פועל גם במקרים מקומיים וגם במקרים מרוחקים.

הוראות מפורטות לשימוש במצב gcloud (במקרים מקומיים ומרוחקים)

מוודאים ש-gcloud מותקן במחשב המקומי.
- מריצים את הפקודה gcloud help במסוף. אם gcloud לא מותקן, צריך לפעול לפי ההוראות האלה כדי להתקין את gcloud.
מסוף של מכונה מקומית
- מריצים את הפקודה earthengine authenticate במסוף.
- בפלט של הפקודה יופיע כי נעשה שימוש ב-gcloud כדי לאחזר את פרטי הכניסה.
- ייפתח חלון דפדפן עם דף לבחירת חשבון. אם הדפדפן לא נפתח באופן אוטומטי, לוחצים על כתובת ה-URL.
דפדפן: בחירת חשבון
- בוחרים את החשבון שבו רוצים להשתמש לאימות.
דפדפן: מסך הסכמה
- מציינים אם רוצים להעניק את ההיקפים המבוקשים ולוחצים על 'אישור'.
דפדפן: מסך אישור
- בדפדפן יוצג דף שמאשר שהאימות בוצע, והפקודה earthengine authenticate בחלון מסוף ה-CLI תציג את ההודעה "Successfully saved authorization token".
- במקרים נדירים, בדף האינטרנט יופיע קוד שצריך להדביק חזרה בסביבת Python.
ממשיכים בתהליך האיפוס.

auth_mode=localhost. זהו תהליך דומה ל-gcloud למקרים שבהם gcloud לא מותקן. הוא מבצע את אותם השלבים כמו gcloud, אבל פועל רק במקרה המקומי. אפשר לציין מספר יציאה אופציונלי לאינטרנט, למשל localhost:8086, או להשתמש ב-localhost:0 כדי לבחור יציאה באופן אוטומטי. יציאת ברירת המחדל היא 8085.

auth_mode=notebook. זהו מצב למטרות כלליות שמיועד לעבודה במצבים מרוחקים שבהם שורות הפקודה המקומיות לא זמינות. המערכת תעביר אתכם לדף Notebook Authenticator, שבו תצטרכו לבחור או ליצור 'פרויקט אימות'. פרטים נוספים ומדריך לפתרון בעיות מופיעים בהמשך. הפרויקט שמעבירים ל-ee.Initialize() לא חייב להתאים לזה – אפשר להשתמש באותו פרויקט לאימות תוך כדי עבודה בפרויקטים שונים במסמכי קוד שונים. מומלץ להעביר פרויקט באופן מפורש ל-ee.Initialize(), אבל המערכת תשתמש בפרויקט האימות כברירת מחדל.

הוראות מפורטות לשימוש במצב מחברת

דפדפן: Notebook
1. כדי להתחיל תהליך אימות באמצעות המצב 'notebook', מריצים את הקוד הבא בתא קוד ב-notebook.
```
import ee
ee.Authenticate()
```
  לוחצים על הקישור בפלט התא כדי לפתוח דף של Notebook Authenticator בכרטיסייה חדשה.
דפדפן: Notebook Authenticator
1. מוודאים שחשבון המשתמש הנכון מופיע.
2. בוחרים פרויקט ב-Google Cloud שישמש לאימות. אם אתם צריכים ליצור פרויקט חדש, מומלץ להשתמש במוסכמה למתן שמות 'ee-xyz', כאשר xyz הוא שם המשתמש הרגיל שלכם ב-Earth Engine. (אם לא ניתן לבחור או ליצור פרויקט ב-Cloud, אפשר לעיין בקטע פתרון בעיות בהמשך).
3. לוחצים על 'יצירת אסימון'.
דפדפן: בחירת חשבון
- תוצג דף לבחירת חשבון. לוחצים על חשבון המשתמש שרוצים להעניק לו גישה מהמחברות.
דפדפן: דף אזהרה
- יוצג דף אזהרה עם הודעה על כך ש-Google לא יצרה את האפליקציה (כלומר את הקוד ב-notebook). לוחצים על 'המשך' כדי לאשר.
דפדפן: מסך הסכמה
- מציינים אם רוצים להעניק את ההיקפים המבוקשים ולוחצים על Continue.
דפדפן: מסך קוד ההרשאה
- מעתיקים את קוד האימות של ההרשאה
דפדפן: Notebook
- חוזרים לכרטיסייה של המחברות ומדביקים את קוד האימות בפלט של תא המחברות.
- הפלט של התא אמור להציג את ההודעה "Successfully saved authorization token".
ממשיכים בתהליך האיפוס.

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

פרויקטים של אימות

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

מטעמי אבטחה, ההגדרה של 'לקוח OAuth' בפרויקט האימות היא הגדרה חד-פעמית. אם אתם או משתמשים אחרים הגדרתם לקוח OAuth בפרויקט מסיבות אחרות, לא תוכלו להסיר אותו ותופיע הודעת השגיאה 'הגדרת לקוח OAuth2 לא תואמת'. תצטרכו להשתמש בפרויקט אחר לאימות, או להשתמש במצבים colab, ‏ localhost או gcloud שצוינו למעלה.

פתרון בעיות

מה קורה אם אי אפשר ליצור פרויקט ב-Cloud?

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

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

שגיאה: "לא נעשה שימוש ב-Earth Engine API בפרויקט XXX בעבר או שהוא מושבת"

קודם כול, חשוב לוודא שהגדרתם פרויקט ב-ee.Initialize() או בשורת הפקודה (בפרויקטים שמוגדרים כברירת מחדל ב-Cloud וב-Colab, Earth Engine לא מופעל). שנית, מוודאים ש-Earth Engine API מופעל בפרויקט.

שגיאה: "Project has an incompatible OAuth2 Client configuration"

לפרויקטים ב-Cloud יכולה להיות הגדרה אחת בלבד של לקוח OAuth2. כדי לבדוק אם בפרויקט ב-Cloud מוגדרת הגדרה של לקוח OAuth2, אפשר לבדוק את מזהי הלקוחות של OAuth 2.0 בדף Credentials. צריך לבחור פרויקט אחר ב-Cloud שכבר הוגדר לו תצורה תואמת על ידי Notebook Authenticator, או לבחור פרויקט ב-Cloud או ליצור פרויקט ב-Cloud ללא לקוחות OAuth2. האימות יקבע את הפרויקט הזה באופן אוטומטי. לצערנו, מערכת OAuth לא מאפשרת למשתמשים למחוק הגדרות, ולכן צריך להשתמש בפרויקט אחר. הפרויקט הזה לא חייב להיות זהה לפרויקט שבו אתם משתמשים לעבודות אחרות ב-Earth Engine. חשוב לזכור שהשגיאה הזו לא מתרחשת במצב Colab.

שגיאה: "gcloud failed. עליך לבדוק אם יש שגיאות למעלה ולהתקין את gcloud אם יש צורך."

השגיאה הזו עשויה להתרחש אם gcloud לא מותקן או לא נמצא ב-PATH. הוא עשוי להתרחש גם אם קוראים ל-ee.Authenticate(auth_mode='gcloud') מתוך תא קוד של מחברת. במקום זאת, צריך להשתמש ב-ee.Authenticate(), שתשתמש כברירת מחדל באימות במצב של מחברת. אם אתם לא מצליחים ליצור פרויקט, תוכלו להיעזר בפתרון שמפורט למעלה.

מה קורה אם אין לי גישה למכונה מקומית כדי להתקין את gcloud?

אם אתם עובדים בסביבת אינטרנט בלבד ללא גישה לטרמינל מקומי, ועדיין צריכים להשתמש בטרמינל מרוחק, תוכלו להפעיל את מצב היומן על ידי הפעלת הפקודה earthengine authenticate --auth_mode=notebook כדי לאתחל את הכלי של שורת הפקודה.

שגיאה 400: redirect_uri_mismatch

יכול להיות שתקבלו את השגיאה הזו אם מבצעים אימות במחשב מרוחק בלי גישה לדפדפן אינטרנט. נסו להוסיף את --quiet אם אתם מריצים את earthengine authenticate משורת הפקודה, או את ee.Authenticate(quiet=True) אם אתם משתמשים בלקוח Python. לשם כך, תצטרכו לבצע אימות באמצעות gcloud ממחשב שיש לו גישה לדפדפן אינטרנט.

שגיאה: "Your application is authenticating by using local Application Default Credentials. כדי להשתמש ב-API של earthengine.googleapis.com, צריך להגדיר מכסה בפרויקט, והיא לא מוגדרת כברירת מחדל".

השגיאה הזו עשויה להתרחש אם מערכת Earth Engine לא מצליחה לקבוע את מזהה הפרויקט שלכם. אם אפשרויות פתרון הבעיות ב-Google Cloud לא עובדות, אפשר לנסות להריץ את הפקודה earthengine set_project YOUR_PROJECT_ID או gcloud auth application-default set-quota-project YOUR_PROJECT_ID.

הערות טכניות

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

בעבר היה מצב paste שהעניק אסימון להדבקה בכל מקום, אבל הוא נחשב מסוכן מדי והוא לא זמין יותר.
colab: auth.authenticate_user() יבקש מכם לשתף את פרטי הכניסה עם לקוח האימות של Colab, כלומר סביבת המחברות עצמה. לאחר מכן, הן יהיו זמינות דרך google.auth.default() וee.Initialize() ישתמש בהן.
localhost: פרטי הכניסה מועברים מהדפדפן ליציאה במחשב המקומי. במקרה כזה, האבטחה מקצה לקצה תלויה בכך שהמכונה המקומית לא נפרצה. לקוח האימות שיופיע הוא 'Earth Engine Authenticator'.
gcloud: האפשרות הזו משתמשת בתהליך --launch-browser שמתואר בחומר העזר של gcloud, וב---no-launch-browser אם מדובר במכונה מרוחקת. לקוח האימות שבו נעשה שימוש הוא 'Google Auth Library'.
notebook: אנחנו יוצרים לקוח אימות חדש במיוחד לעבודה שלכם – כתובת האימייל שלכם תופיע בדף ההסכמה. הלקוח הזה מוגדר במצב 'פיתוח', שהוא מקרה מיוחד שמאפשר את האסימונים הקודמים של מצב הדבקה. לשם כך נצטרך להשתמש בפרויקט משלכם, כי לא ניתן לשתף לקוחות כאלה עם מספר גדול של משתמשים.