المصادقة والإعداد

قبل أن تتمكّن من إرسال طلبات إلى Earth Engine من خلال مكتبة العملاء، عليك المصادقة واستخدام بيانات الاعتماد الناتجة لبدء تشغيل برنامج Earth Engine.

محرِّر الرموز البرمجية في Earth Engine وJavaScript

تتم معالجة المصادقة والإعداد تلقائيًا في "محرر الرموز البرمجية". يمكنك اختيار توجيه الطلبات من خلال مشروع على Cloud من خلال تسجيل الدخول في أعلى يسار محرِّر الرموز البرمجية.

إذا كنت تستخدم واجهة برمجة تطبيقات JavaScript (خارج "محرر الرموز")، استخدِم أحد مساعِدي المصادقة في ee.data (مثل، ee.data.authenticateViaPopup()) ثم ee.initialize() كما هو موضّح في هذا المثال.

لغة Python وسطر الأوامر

قبل استخدام مكتبة عملاء Python في Earth Engine، عليك المصادقة (إثبات هويتك) واستخدام بيانات الاعتماد الناتجة لبدء العميل Python. تستخدِم مسارات المصادقة مشاريع سحابة تطبيقات Google للمصادقة، ويُستخدَم ذلك للاستخدام غير المدفوع (المجاني وغير التجاري) وكذلك الاستخدام المدفوع. لتأكيد الهوية وبدء الخدمة، يمكنك تنفيذ

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

سيؤدي ذلك أولاً إلى اختيار أفضل وضع مصادقة لبيئة عملك، ثم سيطلب منك تأكيد إمكانية الوصول إلى نصوصك البرمجية. إذا كانت بيانات الاعتماد متوفّرة، تتم إعادة استخدامها تلقائيًا. يمكنك تشغيل ee.Authenticate(force=True) لإنشاء بيانات اعتماد جديدة.

تتحقّق خطوة الإعداد من توفّر بيانات اعتماد صالحة، سواء تم إنشاؤها من ee.Authenticate() أو كانت موجودة مسبقًا بصفتها بيانات الاعتماد التلقائية من Google. بعد ذلك، يتم تهيئة مكتبة Python للعملاء باستخدام الأساليب التي يقبلها خادم الخلفية. عليك تقديم مشروع تملكه أو لديك أذونات لاستخدامه. اطّلِع على إعداد مشروع على السحابة الإلكترونية لتسجيل المشروع وتفعيل واجهة برمجة التطبيقات 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() في بداية جميع النصوص البرمجية ل maximize compatibility. بدون مَعلمة auth_mode، تم تصميمه للعمل في معظم الحالات، ولكن اتّبِع التفاصيل أدناه إذا لم يعمل الوضع التلقائي. يتم اختيار الوضع التلقائي على النحو التالي:

  • colab في حال التشغيل في "مفكرة Google Colab"
  • notebook في حال التشغيل في أوراق ملاحظات Jupyter أخرى غير Colab
  • localhost في حال رصد متصفّح ويب وعدم تثبيت ملف gcloud ثنائي
  • gcloud، بخلاف ذلك لاستخدام هذا الوضع، عليك تثبيت gcloud.

الدليل المرجعي السريع والجدول

يوضّح دليل اتخاذ القرار هذا الخيارات المحتملة في حال عدم عمل الوضع التلقائي الذي اختارهee.Authenticate(). على سبيل المثال، إذا كنت تستخدم بيئة دفتر ملاحظات أخرى، قد تحتاج إلى تحديد notebook صراحةً.

  • البيئة المحلية:
    • تشير الحالة "على الجهاز" إلى أنّك تُنفِّذ رمزًا في بيئة Python أو "دفتر ملاحظات Python" على الجهاز أمامك، أو على وجه التحديد، على الجهاز نفسه الذي يعمل عليه متصفح الويب. ويشمل ذلك حالات الكمبيوتر المكتبي عن بُعد التي يكون فيها كلّ من Python و المتصفّح على الجهاز (البعيد) نفسه.
    • إنّ استخدام auth_mode=localhost هو الأسهل، وسيتم اختياره تلقائيًا في حال عدم تثبيت gcloud، ولكن لن يعمل النص البرمجي إلا في البيئات المحلية.
    • يتوفّر أيضًا كل من auth_mode=gcloud وauth_mode=notebook.
  • البيئة البعيدة:
    • "عن بُعد" يعني أنّ المتصفّح مثبّت على جهاز (محلي) واحد ولكن الرمز البرمجي يتم تنفيذه في مكان آخر، مثل محطة عمل عن بُعد أو دفتر ملاحظات على الويب.
    • إذا كنت تستخدم Colab، استخدِم auth_mode=colab، أو استخدِم gcloud إذا كنت بحاجة إلى ضبط scopes لطلب بيانات من واجهات برمجة تطبيقات أخرى.
    • إذا كان بإمكانك تثبيت gcloud على كلّ من الجهاز البعيد والجهاز المحلي، استخدِم auth_mode=gcloud.
    • إذا كان بإمكانك استخدام مشروع مصادقة (راجِع المعلومات أدناه)، استخدِم auth_mode=notebook.
    • في حال تعذّر عليك استخدام مشروع أو تثبيت gcloud أو استخدام Colab أو استخدام browser على الجهاز نفسه:
    • تواصل مع أحد المشرفين (مرة أخرى) بشأن إنشاء المشاريع. على سبيل المثال:
      • اطلب من المشرف ضبط إعدادات مشروع لك (بصفتك مالكًا أو محرِّرًا أو محرِّر إعدادات OAuth).
      • أو اطلب من المشرف منحك الأذونات اللازمة لإنشاء مشروع.

يعرض هذا الجدول مجموعات الميزات المتاحة لكل وضع.

هل المطلوب للاستخدام على الجهاز أو عن بُعد؟ المشروع مطلوب النطاقات التي يمكن ضبطها يجب توفُّر واجهة سطر أوامر محلية. مالك المشروع
localhost local نعم نعم لا لا
colab جهاز تحكّم عن بُعد نعم لا لا لا
gcloud كلاهما نعم نعم لا لا
notebook كلاهما نعم نعم لا نعم

بيانات الاعتماد لحسابات الخدمة وCompute Engine

سيستخدم ee.Initialize() بيانات اعتماد Earth Engine (التي يتم تخزينها في ee.Authenticate()) أو سيسترجع بيانات الاعتماد من google.auth.default()، ولكن إذا لزم الأمر، يمكنك تمرير وسيطة credentials= لاستخدام بيانات الاعتماد من مكان آخر، مع تجاوز هذه الإعدادات التلقائية.~/.config/earthengine/credentials

إذا كنت بصدد مصادقة رمز Python البرمجي الذي سيتم تشغيله بدون إشراف، قد تحتاج إلى المصادقة باستخدام حساب خدمة بدلاً من حساب مستخدم. اطّلِع على هذه المستندات لمعرفة كيفية استخدام حسابات الخدمة مع Earth Engine. تشمل الطرق الأخرى authenticate_service_account في وحدة مصادقة Colab والطرق الموضّحة في دليل Cloud للمصادقة باستخدام حساب خدمة.

إذا كان الرمز البرمجي يعمل على جهاز افتراضي في Compute Engine، يتم إنشاء حساب خدمة default للبيئة، وسيستخدمه ee.Initialize() تلقائيًا. قد تحتاج إلى تسجيل حساب الخدمة لاستخدام Earth Engine إذا لم يكن مشروع Cloud الذي تم من خلاله تشغيل الجهاز الظاهري مسجّلاً لاستخدامه مع Earth Engine (تجاري أو غير تجاري).

تفاصيل عن الأوضاع

auth_mode=colab. سينشئ ee.Authenticate() بيانات الاعتماد الافتراضية التي تتوافق مع Colab أو سيحصل عليها، وذلك من خلال تشغيل colab.auth.authenticate_user() إذا لزم الأمر. تستخدم بيانات الاعتماد دائمًا النطاق cloud-platform ويمكن أيضًا استخدامها لطلب بيانات من واجهات برمجة تطبيقات Cloud الأخرى.

auth_mode=gcloud. يفوّض هذا الإجراء عملية المصادقة إلى أداة gcloud، وهو مماثل لمحاولة تشغيل gcloud auth application-default login باستخدام نطاقات Earth Engine التلقائية (earthengine وcloud-platform وdrive) أو النطاقات الواردة في الوسيطة scopes. يعمل وضع gcloud في كلٍّ من الحالات المحلية والحالات البعيدة.

تعليمات مفصّلة لاستخدام وضع gcloud (في الحالتَين المحلية والبعيدة)

  1. تأكَّد من تثبيت gcloud على الجهاز المحلي.
    • في وحدة طرفية، شغِّل gcloud help. إذا لم يكن gcloud قد تم تثبيته، اتّبِع هذه التعليمات لتثبيت gcloud.
  2. تطبيق Terminal على الجهاز المحلي
    • في وحدة طرفية، شغِّل earthengine authenticate.
    • سيشير ناتج الأمر إلى أنّه يتم استخدام gcloud ل retrieving credentials.
    • ستفتح نافذة متصفّح لعرض صفحة اختيار الحساب. إذا لم يفتح المتصفّح تلقائيًا، انقر على عنوان URL.
  3. المتصفّح: اختيار الحساب
    • اختَر الحساب الذي تريد استخدامه للمصادقة.
  4. المتصفّح: شاشة الموافقة
    • حدِّد ما إذا كنت على استعداد لمنح النطاقات المطلوبة وانقر على "السماح".
  5. المتصفّح: شاشة التأكيد
    • سيعرض المتصفّح صفحة تؤكّد أنّه تمّت مصادقة حسابك، وسيُظهر الأمر earthengine authenticate في نافذة المحطة الطرفية الرسالة التالية: "تمّ حفظ رمز التفويض بنجاح".
    • في الحالات البعيدة، ستمنحك صفحة الويب رمزًا لكي تُلصقه مرة أخرى في بيئة Python.
  6. واصِل عملية الإعداد.

auth_mode=localhost. هذه عملية مشابهة لعملية gcloud في الحالات التي لم يتم فيها تثبيت gcloud. وينفِّذ الخطوات نفسها التي نفّذها gcloud، ولكنّه لا يعمل إلا في الحالة المحلية. يمكنك تقديم رقم منفذ اختياري على الإنترنت، مثل localhost:8086، أو استخدام localhost:0 لاختيار منفذ تلقائيًا. المنفذ التلقائي هو 8085.

auth_mode=notebook. هذا وضع لأغراض عامة مصمّم للعمل في المواقف البعيدة التي لا تتوفّر فيها سطور الأوامر المحلية. سينقلك هذا الإجراء إلى صفحة "مصادق Notebook" حيث عليك اختيار أو إنشاء "مشروع مصادقة". اطّلِع على التفاصيل ودليل تحديد المشاكل وحلّها أدناه. ليس من الضروري أن يتطابق المشروع الذي تم تمريره إلى ee.Initialize() مع هذا المشروع، فيمكنك الاحتفاظ بالمشروع نفسه للمصادقة أثناء العمل في مشاريع مختلفة في دفاتر ملاحظات مختلفة. يُنصح بتمرير مشروع صراحةً إلى ee.Initialize()، ولكن سيتم استخدام مشروع المصادقة تلقائيًا.

تعليمات مفصّلة حول وضع دفتر ملاحظات

  1. المتصفّح: دفتر ملاحظات
    1. في خلية رمز دفتر ملاحظات، نفِّذ الرمز البرمجي التالي لبدء عملية مصادقة باستخدام وضع "دفتر ملاحظات". 
      import ee
ee.Authenticate()
       انقر على الرابط في إخراج الخلية لفتح صفحة "مصادقة دفتر ملاحظات Google" في علامة تبويب جديدة.
  2. المتصفّح: تطبيق Notebook Authenticator
    1. تأكَّد من إدراج حساب المستخدم الصحيح.
    2. اختَر مشروع Google Cloud لاستخدامه في المصادقة. إذا كنت بحاجة إلى إنشاء مشروع جديد، ننصحك باستخدام اصطلاح التسمية "ee-xyz" حيث يكون xyz هو اسم المستخدم المعتاد في Earth Engine. (إذا لم تتمكّن من اختيار مشروع على Cloud أو إنشائه، اطّلِع على قسم تحديد المشاكل وحلّها أدناه).
    3. انقر على "إنشاء رمز مميّز".
  3. المتصفّح: اختيار الحساب
    • ستظهر لك صفحة اختيار الحساب. انقر على حساب المستخدم الذي تريد منحه إذن الوصول من المفكرة.
  4. المتصفّح: صفحة التحذير
    • يتم عرض صفحة تحذير تشير إلى أنّ Google لم تنشئ التطبيق (أي الرمز البرمجي في دفتر الملاحظات). انقر على "متابعة" للإقرار.
  5. المتصفّح: شاشة الموافقة
    • حدِّد ما إذا كنت على استعداد لمنح النطاقات المطلوبة وانقر على متابعة.
  6. المتصفّح: شاشة رمز التفويض
    • نسخ رمز إثبات الهوية الخاص بالتفويض
  7. المتصفّح: دفتر ملاحظات
    • انتقِل مرة أخرى إلى علامة تبويب دفتر الملاحظات والصق رمز إثبات الملكية في إخراج خلية دفتر الملاحظات.
    • من المفترض أن يشير ناتج الخلية إلى "تم حفظ رمز التفويض بنجاح".
  8. واصِل عملية الإعداد.

يحتوي وضع "دفتر ملاحظات" على مَعلمة quiet نادرًا ما يتم استخدامها: في حال ضبطها، يتم تشغيلها "بدون تفاعل" ولا تطلب منك إدخال رمز التفويض وتنتظرك إلى أن تُدخله. بدلاً من ذلك، يتم تقديم أمر لتنفيذه لحفظ الرمز.

مشاريع المصادقة

يجب أن تكون مالكًا أو محرِّرًا أو محرِّر إعدادات OAuth في مشروع المصادقة المستخدَم في وضع دفتر الحسابات. في كثير من الحالات، خاصةً في الفِرق الأصغر حجمًا، يمكن أن يكون مشروع المصادقة الذي تستخدمه في صفحة مصادقة "دفتر ملاحظات Google" هو نفسه المشروع الأساسي الذي تستخدمه للقيام بأعمال أخرى.

بسبب مخاوف تتعلّق بالأمان، يتم تنفيذ "إعداد عميل OAuth" في مشروع المصادقة لمرة واحدة فقط. إذا أعددت أنت أو مستخدمون آخرون عميل OAuth في المشروع لأسباب أخرى، لا يمكن إزالته وسيظهر لك خطأ يفيد بأنّه "إعدادات عميل OAuth2 غير متوافقة". ستحتاج إلى استخدام مشروع مختلف للمصادقة، أو استخدام وضع colab أو localhost أو gcloud أعلاه.

تحديد المشاكل وحلّها

ماذا لو لم أتمكّن من إنشاء مشروع على Cloud؟

تتحكّم بعض المؤسسات في المستخدمين الذين يمكنهم إنشاء مشاريع على Cloud. إذا ظهرت لك رسالة خطأ في صفحة "مصادقة دفتر النوْت" عند محاولة إنشاء مشروع، هناك بعض الإجراءات التي يمكنك اتّخاذها:

  1. حاوِل إنشاء مشروع مباشرةً للتأكّد مما إذا كانت لديك الأذونات اللازمة أم لا.
  2. تواصل مع مشرف مؤسستك لمعرفة العمليات المتوفّرة لإنشاء مشروع.
  3. أنشئ مشروعًا من حساب غير تابع لمؤسسة، وأضِف الحساب الذي تستخدمه للعمل بصفتك مالكًا للمشروع. ملاحظة: تفرض بعض المؤسسات سياسات أمان تمنع الوصول إلى عملاء OAuth من projects الخارجية.

الخطأ: "لم يتم استخدام واجهة برمجة التطبيقات Earth Engine API في المشروع XXX من قبل أو أنّها غير مفعّلة"

أولاً، تأكَّد من ضبط مشروع في ee.Initialize() أو على سطر الأوامر (لن يتم تفعيل Earth Engine في المشاريع التلقائية التي تقدّمها Cloud وColab). ثانيًا، تأكَّد من أنّ واجهة برمجة التطبيقات Earth Engine API مفعَّلة في مشروعك.

الخطأ: "يحتوي المشروع على إعدادات عميل OAuth2 غير متوافقة"

يمكن أن تتضمّن مشاريع السحابة الإلكترونية إعدادًا واحدًا فقط لعميل OAuth2. يمكنك التحقّق مما إذا كان مشروع Cloud يتضمّن إعدادات عميل OAuth2 من خلال التحقّق من معرّفات العميل لبروتوكول OAuth 2.0 في صفحة "بيانات الاعتماد". عليك اختيار مشروع آخر على Google Cloud يتضمّن إعدادات متوافقة تم إعدادها من قِبل عنصر مصادقة Notebook ، أو اختيار مشروع على Google Cloud أو إنشاؤه بدون عملاء OAuth2. سيضبط مصادقة العميل هذا المشروع تلقائيًا. لا يسمح نظام OAuth للمستخدمين بحذف الإعدادات، لذا يجب استخدام مشروع مختلف. ولا يلزم أن يكون هذا المشروع هو المشروع نفسه المستخدَم في أعمال أخرى على Earth Engine. يُرجى العِلم أنّ هذا الخطأ لا يحدث في وضع Colab.

خطأ: "تعذّر استخدام gcloud. يُرجى التحقّق من أي أخطاء أعلاه وتثبيت gcloud إذا لزم الأمر".

قد يحدث هذا الخطأ إذا لم يكن gcloud مثبّتًا أو لم يكن مضمّنًا في PATH. وقد يحدث ذلك أيضًا إذا اتصلت بالرقم ee.Authenticate(auth_mode='gcloud') من داخل خلية رمز دفتر ملاحظات. استخدِم ee.Authenticate() بدلاً من ذلك، وسيؤدي ذلك تلقائيًا إلى استخدام مصادقة وضع notebook. إذا لم تتمكّن من إنشاء مشروع، اطّلِع على الحلّ أعلاه.

ماذا لو لم يكن لديّ إذن الوصول إلى جهاز محلي لتثبيت gcloud؟

إذا كنت تعمل في بيئة على الويب فقط بدون إمكانية الوصول إلى وحدة تحكّم محلية، وكنت لا تزال بحاجة إلى استخدام وحدة تحكّم عن بُعد، سيظل بإمكانك بدء استخدام أداة سطر الأوامر من خلال تفعيل وضع دفتر الملاحظات من خلال تشغيل الأمر earthengine authenticate --auth_mode=notebook.

الخطأ 400: redirect_uri_mismatch

قد يظهر لك هذا الخطأ في حال المصادقة على جهاز بعيد بدون إمكانية الوصول إلى متصفّح ويب. جرِّب إضافة --quiet في حال تشغيل earthengine authenticate من سطر الأوامر أو ee.Authenticate(quiet=True) في حال استخدام ملف Python العملاء. سيتطلب ذلك منك المصادقة باستخدام gcloud من جهاز يمكنه الوصول إلى متصفّح ويب.

الخطأ: "يُجري تطبيقك عملية مصادقة باستخدام بيانات الاعتماد التلقائية للتطبيق على الجهاز. تتطلّب واجهة برمجة التطبيقات 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".
  • gcloud: يستخدم هذا الإجراء عملية --launch-browser الموضّحة في مرجع gcloud، و--no-launch-browser إذا كان على جهاز كمبيوتر عن بُعد. مكتبة المصادقة المستخدَمة هي "مكتبة Google للمصادقة".
  • notebook: ننشئ عميل مصادقة جديدًا خصيصًا لعملك. وستظهر عنوان بريدك الإلكتروني في صفحة الموافقة. تم ضبط هذا العميل في وضع "التطوير"، وهو حالة خاصة تسمح باستخدام علامات وضع اللصق القديم. يجب استخدام مشروعك لإجراء ذلك، لأنّه لا يمكن مشاركة هذه الحسابات مع أعداد كبيرة من المستخدمين.