اطلاعیه : همه پروژه‌های غیرتجاری ثبت‌شده برای استفاده از Earth Engine قبل از ۱۵ آوریل ۲۰۲۵ باید واجد شرایط بودن غیرتجاری برای حفظ دسترسی Earth Engine را تأیید کنند .

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

احراز هویت و مقداردهی اولیه

قبل از اینکه بتوانید از طریق یک کتابخانه کلاینت به Earth Engine درخواست بدهید، باید اعتبارسنجی حاصل را احراز هویت کنید و از آن برای مقداردهی اولیه مشتری Earth Engine استفاده کنید.

ویرایشگر کد موتور زمین و جاوا اسکریپت

احراز هویت و مقداردهی اولیه به طور خودکار در ویرایشگر کد انجام می شود. می‌توانید مسیریابی درخواست‌ها را از طریق یک پروژه ابری از لاگین خود در سمت راست بالای ویرایشگر کد انتخاب کنید.

اگر از API جاوا اسکریپت (خارج از ویرایشگر کد) استفاده می کنید، از یکی از کمک کننده های احراز هویت در ee.data (به عنوان مثال ee.data.authenticateViaPopup() ) و به دنبال ee.initialize() همانطور که در این مثال نشان داده شده است استفاده کنید.

پایتون و خط فرمان

قبل از استفاده از کتابخانه کلاینت Earth Engine Python، باید احراز هویت (تأیید هویت خود) و استفاده از اعتبار حاصله برای مقداردهی اولیه کلاینت پایتون را انجام دهید. جریان‌های احراز هویت از پروژه‌های ابری برای احراز هویت استفاده می‌کنند، و آنها برای استفاده بدون پرداخت (رایگان، غیرتجاری) و همچنین استفاده پولی استفاده می‌شوند. برای احراز هویت و مقداردهی اولیه، اجرا کنید

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

این ابتدا بهترین حالت احراز هویت را برای محیط شما انتخاب می کند و از شما می خواهد که دسترسی به اسکریپت های خود را تأیید کنید. اگر اعتبارنامه ها از قبل وجود داشته باشند، به طور خودکار دوباره مورد استفاده قرار می گیرند - ee.Authenticate(force=True) را برای ایجاد اعتبارنامه های جدید اجرا کنید.

مرحله اولیه تأیید می‌کند که اعتبارنامه‌های معتبر وجود دارند، یا از ee.Authenticate() ایجاد شده‌اند یا از قبل به عنوان اعتبار پیش‌فرض Google وجود داشته‌اند. سپس کتابخانه کلاینت پایتون را با روش هایی که سرور پشتیبان پشتیبانی می کند، مقداردهی اولیه می کند. شما باید پروژه ای را ارائه دهید که مالک آن هستید یا مجوز استفاده از آن را دارید. برای ثبت پروژه و فعال کردن Earth Engine API به تنظیمات پروژه Cloud مراجعه کنید. این پروژه برای اجرای تمام عملیات 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 اگر در نوت بوک Google Colab اجرا شود
notebook در صورتی که در نوت بوک های غیر Colab Jupyter اجرا شود
اگر یک مرورگر وب شناسایی شود و هیچ باینری gcloud نصب نشده باشد localhost
gcloud ، در غیر این صورت. برای این حالت باید gcloud را نصب کنید .

راهنمای مرجع سریع و جدول

اگر حالت پیش‌فرض انتخاب شده توسط ee.Authenticate() کار نکند، این راهنمای تصمیم‌گیری، گزینه‌های ممکن را مشخص می‌کند. به عنوان مثال، اگر در محیط‌های نوت‌بوک دیگری در حال اجرا هستید، ممکن است مجبور باشید به صراحت notebook مشخص کنید.

محیط محلی .
- "محلی" به این معنی است که شما در حال اجرای کد در پوسته پایتون یا نوت بوک پایتون در دستگاه مقابل خود هستید - یا به طور دقیق تر، روی همان ماشینی که مرورگر وب شما روی آن کار می کند. این شامل موقعیت‌های دسکتاپ از راه دور است که در آن پایتون و مرورگر هر دو در یک ماشین (راه‌دور) هستند.
- استفاده از auth_mode=localhost ساده ترین است و اگر gcloud نصب نشده باشد به طور پیش فرض انتخاب می شود، اما اسکریپت شما فقط در محیط های محلی کار می کند.
- هر دو auth_mode=gcloud و auth_mode=notebook نیز در دسترس هستند.
محیط از راه دور .
- "Remote" به این معنی است که مرورگر شما روی یک ماشین (محلی) است اما کد شما در جای دیگری اجرا می شود، مانند یک ایستگاه کاری راه دور یا یک نوت بوک مبتنی بر وب.
- اگر در Colab هستید، از auth_mode=colab استفاده کنید. یا اگر نیاز به تنظیم scopes برای فراخوانی APIهای دیگر دارید از gcloud استفاده کنید.
- اگر می توانید gcloud را هم بر روی دستگاه راه دور و هم در دستگاه محلی خود نصب کنید، از auth_mode=gcloud استفاده کنید.
- اگر می توانید از یک پروژه احراز هویت استفاده کنید (به زیر مراجعه کنید)، از auth_mode=notebook استفاده کنید.
- در غیر این صورت، اگر نمی توانید از یک پروژه استفاده کنید یا gcloud را نصب کنید یا از Colab استفاده کنید یا از یک مرورگر در همان دستگاه استفاده کنید:
- درباره ایجاد پروژه ها (دوباره) با یک مدیر صحبت کنید. به عنوان مثال:
  - از سرپرست بخواهید یک پروژه را برای شما پیکربندی کند (به عنوان مالک یا ویرایشگر یا ویرایشگر پیکربندی OAuth)
  - یا از مدیر بخواهید به شما اجازه ایجاد یک پروژه را بدهد.

این جدول نشان می دهد که کدام ترکیب از ویژگی ها توسط هر حالت پشتیبانی می شود.

	برای محلی یا از راه دور؟	پروژه مورد نیاز	محدوده قابل تنظیم	CLI محلی مورد نیاز است	مالک پروژه
`localhost`	محلی	Y	Y	ن	ن
`colab`	از راه دور	Y	ن	ن	ن
`gcloud`	هر دو	Y	Y	ن	ن
`notebook`	هر دو	Y	Y	ن	Y

اعتبارنامه برای حساب های خدمات و موتور محاسباتی

ee.Initialize() از اعتبارات Earth Engine استفاده می کند (که ee.Authenticate() در ~/.config/earthengine/credentials ذخیره می کند) یا اعتبارنامه ها را از google.auth.default() بازیابی می کند، اما در صورت لزوم می توانید یک آرگومان credentials= برای استفاده از اعتبارنامه ها از جاهای دیگر عبور دهید.

اگر کد پایتون را احراز هویت می کنید که بدون نظارت اجرا می شود، ممکن است بخواهید با یک حساب سرویس به جای حساب کاربری احراز هویت کنید. برای استفاده از حساب‌های خدمات با Earth Engine به این اسناد مراجعه کنید. روش‌های دیگر عبارتند از authenticate_service_account در ماژول احراز هویت Colab و روش‌هایی که در راهنمای Cloud برای احراز هویت به‌عنوان حساب سرویس توضیح داده شده است.

اگر کد شما روی یک ماشین مجازی کامپیوتری Compute Engine اجرا می شود، یک حساب سرویس پیش فرض برای محیط ایجاد می شود که ee.Initialize() به طور پیش فرض از آن استفاده می کند. اگر پروژه Cloud که VM از طریق آن شروع به کار کرده است برای استفاده در Earth Engine (تجاری یا غیرتجاری) ثبت نشده باشد، ممکن است لازم باشد حساب سرویس را برای استفاده از Earth Engine ثبت کنید .

جزئیات در مورد حالت ها

auth_mode=colab . ee.Authenticate() اعتبار پیش فرضی را که توسط Colab پشتیبانی می شود، با اجرای colab.auth.authenticate_user() در صورت لزوم ایجاد یا به دست می آورد. اعتبارنامه ها همیشه از محدوده cloud-platform استفاده می کنند و همچنین می توانند برای فراخوانی سایر API های Cloud استفاده شوند.

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 در پنجره ترمینال شما «توکن مجوز با موفقیت ذخیره شد» را گزارش می‌دهد.
- در موارد راه دور، صفحه وب کدی را به شما می‌دهد تا دوباره در محیط پایتون قرار دهید.
مراحل اولیه را ادامه دهید.

auth_mode=localhost . این یک جریان شبیه به gcloud برای مواردی است که gcloud نصب نشده است. مراحل مشابه gcloud را انجام می دهد، اما فقط برای مورد محلی کار می کند. شما می توانید یک شماره پورت اینترنتی اختیاری، به عنوان مثال localhost:8086 ، یا از localhost:0 برای انتخاب خودکار یک پورت، ارائه دهید. پورت پیش فرض 8085 است.

auth_mode = نوت بوک . این یک حالت همه منظوره است که برای کار در موقعیت های راه دور که خطوط فرمان محلی در دسترس نیستند، طراحی شده است. شما را به صفحه تأیید اعتبار Notebook می فرستد، جایی که باید یک "پروژه احراز هویت" را انتخاب یا ایجاد کنید - جزئیات و راهنمای عیب یابی را در زیر ببینید. پروژه به ee.Initialize() نباید با آن مطابقت داشته باشد - می توانید همان پروژه را برای احراز هویت در حین کار در پروژه های مختلف در نوت بوک های مختلف نگه دارید. توصیه می شود که یک پروژه را به طور صریح به ee.Initialize() ارسال کنید، اما پروژه احراز هویت به طور پیش فرض استفاده می شود.

دستورالعمل های گام به گام برای حالت نوت بوک

مرورگر: نوت بوک
1. در سلول کد نوت بوک، کد زیر را اجرا کنید تا یک جریان احراز هویت با استفاده از حالت "notebook" شروع شود.
```
import ee
ee.Authenticate()
```
  روی پیوند موجود در خروجی سلول کلیک کنید تا صفحه Notebook Authenticator در یک برگه جدید باز شود.
مرورگر: Notebook Authenticator
1. بررسی کنید که حساب کاربری صحیح فهرست شده باشد.
2. یک پروژه Google Cloud را برای استفاده برای احراز هویت انتخاب کنید. اگر نیاز به ایجاد یک پروژه جدید دارید، ما قرارداد نامگذاری "ee-xyz" را توصیه می کنیم که xyz نام کاربری معمول Earth Engine شما است. (اگر نمی توانید یک پروژه Cloud را انتخاب یا ایجاد کنید، بخش عیب یابی زیر را ببینید.)
3. روی Generate Token کلیک کنید.
مرورگر: انتخاب حساب
- صفحه انتخاب حساب به شما نشان داده می شود. روی حساب کاربری که می‌خواهید از دفترچه یادداشت به آن اجازه دسترسی بدهید کلیک کنید.
مرورگر: صفحه هشدار
- یک صفحه هشدار ارائه می شود که نشان می دهد Google برنامه را ایجاد نکرده است (یعنی کد موجود در نوت بوک). برای تایید روی Continue کلیک کنید.
مرورگر: صفحه رضایت
- مشخص کنید که آیا مایل به اعطای محدوده های درخواستی هستید و روی Continue کلیک کنید.
مرورگر: صفحه کد مجوز
- کد تأیید مجوز را کپی کنید
مرورگر: نوت بوک
- به برگه نوت بوک برگردید و کد تأیید را در خروجی سلول نوت بوک قرار دهید.
- خروجی سلول باید نشانگر "توکن مجوز با موفقیت ذخیره شد."
مراحل اولیه را ادامه دهید.

حالت نوت بوک دارای یک پارامتر quiet است که به ندرت استفاده می شود: اگر تنظیم شود، به صورت "noninteractive" اجرا می شود و از شما درخواست نمی کند و منتظر نمی ماند تا کد احراز هویت را وارد کنید. در عوض، دستوری برای اجرا برای ذخیره کد می دهد.

پروژه های احراز هویت

شما باید مالک، ویرایشگر یا ویرایشگر پیکربندی OAuth در پروژه احراز هویت مورد استفاده در حالت نوت بوک باشید. در بسیاری از موارد، به‌ویژه در تیم‌های کوچک‌تر، پروژه احراز هویتی که در صفحه تأییدکننده Notebook استفاده می‌کنید، می‌تواند مانند پروژه اولیه‌ای باشد که برای کارهای دیگر استفاده می‌کنید.

به دلیل نگرانی های امنیتی ، "پیکربندی سرویس گیرنده OAuth" در پروژه احراز هویت یک بار راه اندازی است. اگر شما یا سایر کاربران به دلایل دیگری یک سرویس گیرنده OAuth را در پروژه راه اندازی کرده اید، نمی توان آن را حذف کرد و با خطایی مواجه خواهید شد که می گوید "تنظیمات مشتری OAuth2 ناسازگار است." برای احراز هویت باید از پروژه دیگری استفاده کنید یا از حالت های colab، localhost یا gcloud بالا استفاده کنید.

عیب یابی

اگر نتوانم یک پروژه ابری ایجاد کنم چه؟

برخی از سازمان ها کنترل می کنند که چه کسی می تواند پروژه های ابری ایجاد کند. اگر هنگام تلاش برای ایجاد یک پروژه خطایی در صفحه تأیید اعتبار Notebook دریافت کردید، چند چیز وجود دارد که باید امتحان کنید:

سعی کنید مستقیماً یک پروژه ایجاد کنید تا تأیید کنید که آیا مجوزهای لازم را دارید یا خیر.
با مدیر سازمان خود صحبت کنید تا بدانید چه فرآیندهایی برای ایجاد یک پروژه در دسترس هستند.
یک پروژه از یک حساب غیر سازمانی ایجاد کنید و حسابی را که برای کار به عنوان مالک پروژه استفاده می کنید اضافه کنید. توجه: برخی از سازمان ها دارای سیاست های امنیتی هستند که از دسترسی به مشتریان OAuth از پروژه های خارجی جلوگیری می کند.

خطا: "Earth Engine API قبلاً در پروژه XXX استفاده نشده است یا غیرفعال است"

ابتدا مطمئن شوید که پروژه ای را در ee.Initialize() یا در خط فرمان پیکربندی کرده اید (پروژه های پیش فرض ارائه شده توسط Cloud و Colab فاقد Earth Engine هستند). در مرحله دوم، مطمئن شوید که Earth Engine API در پروژه شما فعال است.

خطا: "پروژه دارای یک پیکربندی مشتری OAuth2 ناسازگار است"

پروژه های Cloud فقط می توانند یک پیکربندی OAuth2 Client داشته باشند. می‌توانید با بررسی شناسه‌های مشتری OAuth 2.0 در صفحه اعتبارنامه، بررسی کنید که آیا پروژه Cloud دارای تنظیمات OAuth2 Client است یا خیر. باید پروژه Cloud دیگری را انتخاب کنید که دارای پیکربندی سازگاری است که قبلاً توسط Notebook Authenticator تنظیم شده است، یا یک پروژه Cloud را بدون کلاینت OAuth2 انتخاب یا ایجاد کنید. Authenticator این پروژه را به صورت خودکار پیکربندی می کند. متأسفانه، سیستم OAuth به کاربران اجازه حذف تنظیمات را نمی دهد، بنابراین باید از پروژه دیگری استفاده کرد. این پروژه نباید همان پروژه ای باشد که برای سایر کارهای Earth Engine استفاده می شود. توجه داشته باشید که این خطا در حالت Colab رخ نمی دهد.

خطا: "gcloud شکست خورد. لطفاً خطاهای بالا را بررسی کنید و در صورت نیاز gcloud را نصب کنید."

اگر gcloud روی PATH شما نصب نشده باشد یا نباشد این خطا ممکن است رخ دهد. همچنین اگر از داخل سلول کد نوت بوک ee.Authenticate(auth_mode='gcloud') تماس بگیرید، ممکن است رخ دهد. به جای آن از ee.Authenticate() استفاده کنید که به طور پیش فرض از احراز هویت حالت نوت بوک استفاده می کند. اگر نمی توانید پروژه ای ایجاد کنید، راه حل بالا را ببینید.

اگر برای نصب gcloud به یک ماشین محلی دسترسی نداشته باشم چه می شود؟

اگر در یک محیط فقط وب و بدون دسترسی به ترمینال محلی کار می‌کنید، و همچنان نیاز به استفاده از ترمینال راه دور دارید، همچنان می‌توانید ابزار خط فرمان را با راه‌اندازی حالت نوت‌بوک با اجرای دستور earthengine authenticate --auth_mode=notebook مقداردهی اولیه کنید.

خطای 400: redirect_uri_mismatch

در صورت احراز هویت در یک دستگاه راه دور بدون دسترسی به مرورگر وب، ممکن است این خطا را دریافت کنید. در صورت اجرای earthengine authenticate از خط فرمان --quiet یا اگر از کلاینت پایتون استفاده می کنید ee.Authenticate(quiet=True) را اضافه کنید. برای این کار باید با gcloud از دستگاهی که به مرورگر وب دسترسی دارد احراز هویت کنید.

خطا: "برنامه شما با استفاده از اعتبار پیش فرض برنامه محلی در حال احراز هویت است. Earthengine.googleapis.com API به یک پروژه سهمیه نیاز دارد که به طور پیش فرض تنظیم نشده است."

این خطا ممکن است زمانی رخ دهد که Earth Engine نتواند ID پروژه شما را تعیین کند. اگر گزینه‌های عیب‌یابی 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 : ما یک کلاینت تأیید اعتبار جدید به طور خاص برای کار شما ایجاد می کنیم - آدرس ایمیل خود را در صفحه رضایت خواهید دید. این کلاینت در حالت "توسعه" تنظیم شده است، که یک مورد خاص است که به توکن های حالت چسباندن قدیمی تر اجازه می دهد. برای این کار باید از پروژه خودتان استفاده کنیم، زیرا چنین کلاینت هایی را نمی توان با تعداد زیادی کاربر به اشتراک گذاشت.