Autentikasi dan Inisialisasi

Sebelum dapat membuat permintaan ke Earth Engine melalui library klien, Anda harus mengautentikasi dan menggunakan kredensial yang dihasilkan untuk melakukan inisialisasi klien Earth Engine.

Editor Kode dan JavaScript Earth Engine

Autentikasi dan inisialisasi ditangani secara otomatis di Code Editor. Anda dapat memilih untuk merutekan permintaan melalui Cloud Project dari login Anda di kanan atas Code Editor.

Jika Anda menggunakan JavaScript API (di luar Editor Kode), gunakan salah satu helper autentikasi di ee.data (misalnya, ee.data.authenticateViaPopup()) diikuti dengan ee.initialize() seperti yang ditunjukkan dalam contoh ini.

Python dan Command Line

Sebelum menggunakan library klien Python Earth Engine, Anda harus melakukan autentikasi (memverifikasi identitas) dan menggunakan kredensial yang dihasilkan untuk melakukan inisialisasi klien Python. Alur autentikasi menggunakan Project Cloud untuk melakukan autentikasi, dan digunakan untuk penggunaan yang tidak dibayar (gratis, nonkomersial) serta penggunaan berbayar. Untuk melakukan autentikasi dan melakukan inisialisasi, jalankan

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

Tindakan ini akan memilih mode autentikasi terbaik untuk lingkungan Anda terlebih dahulu, dan meminta Anda untuk mengonfirmasi akses untuk skrip Anda. Jika sudah ada, kredensial akan otomatis digunakan kembali - jalankan ee.Authenticate(force=True) untuk membuat kredensial baru.

Langkah inisialisasi memverifikasi bahwa kredensial yang valid ada, baik yang dibuat dari ee.Authenticate() maupun yang sudah ada sebagai kredensial default Google. Kemudian, kode ini akan melakukan inisialisasi library klien Python dengan metode yang didukung server backend. Anda harus menyediakan project yang Anda miliki, atau memiliki izin untuk menggunakannya. Lihat Penyiapan project cloud untuk mendaftarkan project dan mengaktifkan Earth Engine API. Project ini akan digunakan untuk menjalankan semua operasi Earth Engine.

Pada command line, panggilan yang setara adalah earthengine authenticate. Jika kredensial sudah tidak berlaku atau tidak valid, Anda mungkin perlu menjalankan earthengine authenticate --force. Pemanggilan command line akan diinisialisasi pada setiap panggilan, dan Anda dapat menggunakan argumen --project untuk menetapkan project.

Anda juga dapat mengonfigurasi project untuk semua panggilan mendatang dengan menjalankan earthengine set_project {my-project}. Command line dan ee.Initialize() akan menggunakannya setiap kali project tidak ditentukan secara langsung. Jika menggunakan autentikasi melalui gcloud (lihat di bawah), project yang ditetapkan oleh gcloud auth application-default set-quota-project {my-project} akan digunakan sebagai kasus akhir.

Detail autentikasi

Tujuan alur autentikasi Earth Engine adalah untuk mendapatkan "token" keamanan dari akun yang Anda gunakan untuk login yang dapat disimpan untuk memberi skrip izin untuk mengakses data Anda. Untuk alasan keamanan, sistem autentikasi Google hanya akan meneruskan token tersebut ke sistem yang dapat dijamin keamanannya - lihat catatan teknis di bawah.

Karena sensitivitas terhadap jenis sistem yang terlibat, ada cara yang berbeda untuk melanjutkan, bergantung pada situasi Anda. Sebagian besar opsi dikontrol oleh parameter auth_mode: sebagai ee.Authenticate(auth_mode=...), atau earthengine authenticate --auth_mode=... di command line.

Perhatikan bahwa jika kredensial Google sudah ada di lingkungan Anda, Anda mungkin tidak perlu memanggil ee.Authenticate() sama sekali. VM Google Cloud, App Engine, dan lingkungan lainnya menyediakan "kredensial standby" yang dapat digunakan, dan gcloud auth application-default login juga akan membuatnya.

Namun, ee.Authenticate() direkomendasikan di awal semua skrip untuk memaksimalkan kompatibilitas. Tanpa parameter auth_mode, parameter ini dirancang untuk berfungsi dalam sebagian besar situasi, tetapi ikuti detail di bawah jika mode default tidak berfungsi. Mode default dipilih sebagai berikut:

• colab jika berjalan di notebook Google Colab
• notebook jika berjalan di notebook Jupyter non-Colab lainnya
• localhost jika browser web terdeteksi dan tidak ada biner gcloud yang diinstal
• gcloud, jika tidak. Untuk mode ini, Anda harus menginstal gcloud.

Panduan dan tabel referensi cepat

Panduan keputusan ini menguraikan kemungkinan opsi jika mode default yang dipilih oleh ee.Authenticate() tidak berfungsi. Misalnya, jika Anda menjalankan di lingkungan notebook lain, Anda mungkin harus menentukan notebook secara eksplisit.

• Lingkungan lokal.
  • "Lokal" berarti Anda menjalankan kode di shell Python atau notebook Python di mesin di depan Anda - atau lebih tepatnya, di mesin yang sama dengan browser web Anda berjalan. Hal ini mencakup situasi desktop jarak jauh saat Python dan browser berada di komputer (jarak jauh) yang sama.
  • Menggunakan auth_mode=localhost adalah cara termudah, dan akan dipilih secara default jika gcloud tidak diinstal, tetapi skrip Anda hanya akan berfungsi di lingkungan lokal.
  • auth_mode=gcloud dan auth_mode=notebook juga tersedia.
• Lingkungan jarak jauh.
  • "Jarak jauh" berarti browser Anda berada di satu komputer (lokal), tetapi kode Anda berjalan di tempat lain, seperti di workstation jarak jauh atau notebook berbasis web.
  • Jika di Colab, gunakan auth_mode=colab; atau gunakan gcloud jika Anda perlu menetapkan scopes untuk memanggil API lain.
  • Jika Anda dapat menginstal gcloud di mesin jarak jauh dan mesin lokal, gunakan auth_mode=gcloud.
  • Jika Anda dapat menggunakan project autentikasi (lihat di bawah), gunakan auth_mode=notebook.
  • Jika tidak, jika Anda tidak dapat menggunakan project atau menginstal gcloud atau menggunakan Colab atau menggunakan browser di mesin yang sama:
  • Hubungi administrator (lagi) untuk membuat project. Misalnya:
    • Minta administrator untuk mengonfigurasi project untuk Anda (sebagai Pemilik atau Editor atau Editor Konfigurasi OAuth)
    • Atau minta administrator untuk memberi Anda izin membuat project.

Tabel ini menunjukkan kombinasi fitur yang didukung oleh setiap mode.

Kredensial untuk Akun Layanan dan Compute Engine

ee.Initialize() akan menggunakan kredensial Earth Engine (yang disimpan oleh ee.Authenticate() di ~/.config/earthengine/credentials) atau mengambil kredensial dari google.auth.default(), tetapi jika perlu, Anda dapat meneruskan argumen credentials= untuk menggunakan kredensial dari tempat lain, sehingga mengabaikan setelan default ini.

Jika mengautentikasi kode Python yang akan berjalan tanpa pengawasan, sebaiknya autentikasi dengan akun layanan, bukan akun pengguna. Lihat dokumen ini untuk menggunakan akun layanan dengan Earth Engine. Metode lainnya mencakup authenticate_service_account di modul autentikasi Colab dan metode yang dijelaskan dalam panduan Cloud untuk melakukan autentikasi sebagai akun layanan.

Jika kode Anda berjalan di VM Compute Engine, akun layanan default akan dibuat untuk lingkungan, yang akan digunakan ee.Initialize() secara default. Anda mungkin perlu mendaftarkan akun layanan untuk menggunakan Earth Engine jika Project Cloud tempat VM dimulai tidak terdaftar untuk digunakan dengan Earth Engine (komersial atau non-komersial).

Detail tentang mode

auth_mode=colab. ee.Authenticate() akan membuat atau mendapatkan kredensial default yang didukung oleh Colab, dengan menjalankan colab.auth.authenticate_user() jika diperlukan. Kredensial selalu menggunakan cakupan cloud-platform dan juga dapat digunakan untuk memanggil Cloud API lainnya.

auth_mode=gcloud. Tindakan ini mendelegasikan autentikasi ke alat gcloud dan sama seperti menjalankan gcloud auth application-default login dengan cakupan Earth Engine default (earthengine, cloud-platform, dan drive) atau cakupan dalam argumen scopes. Mode gcloud berfungsi dalam kasus lokal dan jarak jauh.

auth_mode=localhost. Ini adalah alur seperti gcloud untuk kasus saat gcloud tidak diinstal. Langkah-langkahnya sama dengan gcloud, tetapi hanya berfungsi untuk kasus lokal. Anda dapat memberikan nomor port internet opsional, misalnya localhost:8086, atau menggunakan localhost:0 untuk memilih port secara otomatis. Port defaultnya adalah 8085.

auth_mode=notebook. Ini adalah mode tujuan umum yang dirancang untuk berfungsi dalam situasi jarak jauh saat command line lokal tidak tersedia. Tindakan ini akan mengarahkan Anda ke halaman Notebook Authenticator tempat Anda harus memilih atau membuat "project autentikasi" - lihat detail dan panduan pemecahan masalah di bawah. Project yang diteruskan ke ee.Initialize() tidak harus cocok dengan ini - Anda dapat mempertahankan project yang sama untuk autentikasi saat bekerja di project yang berbeda di notebook yang berbeda. Sebaiknya teruskan project secara eksplisit ke ee.Initialize(), tetapi project autentikasi akan digunakan secara default.

Mode notebook memiliki parameter quiet yang jarang digunakan: jika ditetapkan, parameter ini akan berjalan "noninteraktif" dan tidak meminta serta menunggu Anda memasukkan kode autentikasi. Sebagai gantinya, perintah ini memberikan perintah untuk dijalankan guna menyimpan kode.

Project autentikasi

Anda harus menjadi Pemilik, Editor, atau Editor Konfigurasi OAuth di project autentikasi yang digunakan dalam mode notebook. Dalam banyak kasus, terutama dalam tim yang lebih kecil, project autentikasi yang Anda gunakan di halaman Notebook Authenticator dapat sama dengan project utama yang Anda gunakan untuk pekerjaan lain.

Karena masalah keamanan, "Konfigurasi klien OAuth" di project autentikasi adalah penyiapan satu kali. Jika Anda atau pengguna lain telah menyiapkan klien OAuth di project karena alasan lain, klien tersebut tidak dapat dihapus dan Anda akan melihat error yang bertuliskan "konfigurasi klien OAuth2 tidak kompatibel". Anda harus menggunakan project yang berbeda untuk autentikasi, atau menggunakan mode colab, localhost, atau gcloud di atas.

Pemecahan masalah

Bagaimana jika saya tidak dapat membuat Project Cloud?

Beberapa organisasi mengontrol siapa yang dapat membuat Project Cloud. Jika Anda menerima error di halaman Notebook Authenticator saat mencoba membuat project, ada beberapa hal yang dapat dicoba:

1. Coba buat project secara langsung untuk mengonfirmasi apakah Anda memiliki izin yang diperlukan atau tidak.
2. Hubungi administrator organisasi Anda untuk mengetahui proses apa saja yang tersedia untuk membuat project.
3. Buat project dari akun non-organisasi, lalu tambahkan akun yang Anda gunakan untuk bekerja sebagai Pemilik project. Catatan: beberapa organisasi memiliki kebijakan keamanan yang mencegah akses ke klien OAuth dari project eksternal.

Error: "Earth Engine API belum pernah digunakan di project XXX atau dinonaktifkan"

Pertama, pastikan Anda telah mengonfigurasi project di ee.Initialize() atau di command line (project default yang disediakan oleh Cloud dan Colab tidak akan mengaktifkan Earth Engine). Kedua, pastikan Earth Engine API diaktifkan di project Anda.

Error: "Project has an incompatible OAuth2 Client configuration"

Project cloud hanya dapat memiliki satu konfigurasi Klien OAuth2. Anda dapat memeriksa apakah project Cloud memiliki konfigurasi Klien OAuth2 yang ditetapkan dengan memeriksa Client ID OAuth 2.0 di halaman Kredensial. Anda harus memilih project Cloud lain yang memiliki konfigurasi kompatibel yang telah disiapkan oleh Notebook Authenticator, atau memilih atau membuat project Cloud tanpa klien OAuth2. Pengautentikasi akan mengonfigurasi project ini secara otomatis. Sayangnya, sistem OAuth tidak mengizinkan pengguna menghapus konfigurasi, sehingga pengguna harus menggunakan project yang berbeda. Project ini tidak harus sama dengan project yang digunakan untuk pekerjaan Earth Engine lainnya. Perhatikan bahwa error ini tidak terjadi dalam mode Colab.

Error: "gcloud failed. Periksa error di atas dan instal gcloud jika diperlukan."

Error ini dapat terjadi jika gcloud tidak diinstal atau tidak ada di PATH Anda. Hal ini juga dapat terjadi jika Anda memanggil ee.Authenticate(auth_mode='gcloud') dari dalam sel kode notebook. Sebagai gantinya, gunakan ee.Authenticate(), yang akan secara default menggunakan autentikasi mode notebook. Jika Anda tidak dapat membuat project, lihat solusi di atas.

Bagaimana jika saya tidak memiliki akses ke komputer lokal untuk menginstal gcloud?

Jika Anda bekerja di lingkungan khusus web tanpa akses ke terminal lokal, dan masih perlu menggunakan terminal jarak jauh, Anda masih dapat melakukan inisialisasi alat command line dengan memicu mode notebook dengan menjalankan perintah earthengine authenticate --auth_mode=notebook.

Error 400: redirect_uri_mismatch

Anda mungkin mendapatkan error ini jika melakukan autentikasi di komputer jarak jauh tanpa akses ke browser web. Coba tambahkan --quiet jika menjalankan earthengine authenticate dari command line atau ee.Authenticate(quiet=True) jika menggunakan klien Python. Anda harus mengautentikasi dengan gcloud dari komputer yang memiliki akses ke browser web.

Error: "Aplikasi Anda melakukan autentikasi menggunakan Kredensial Default Aplikasi lokal. API earthengine.googleapis.com memerlukan project kuota, yang tidak ditetapkan secara default."

Error ini dapat terjadi jika Earth Engine tidak dapat menentukan project ID Anda. Jika opsi pemecahan masalah Google Cloud tidak berfungsi, coba jalankan earthengine set_project YOUR_PROJECT_ID atau gcloud auth application-default set-quota-project YOUR_PROJECT_ID.

Catatan teknis

Bagi yang ingin tahu secara teknis: kebutuhan akan berbagai mekanisme pembuatan kredensial ini berasal dari kebutuhan untuk meneruskan kredensial ke lingkungan yang dikenal dan tepercaya. Berikut adalah diskusi singkat tentang berbagai kasus di atas.

• Dulu ada mode paste yang memberi Anda token untuk ditempelkan di mana saja, dan hal ini dianggap terlalu berisiko dan tidak lagi tersedia.
• colab: auth.authenticate_user() akan meminta Anda untuk membagikan kredensial dengan klien autentikasi "Colab", yaitu lingkungan notebook itu sendiri. Kemudian, data tersebut tersedia melalui google.auth.default() dan digunakan oleh ee.Initialize().
• localhost: kredensial diteruskan dari browser ke port di mesin lokal Anda. Dalam situasi ini, keamanan menyeluruh bergantung pada fakta bahwa komputer lokal Anda belum disusupi. Klien autentikasi yang akan Anda lihat adalah "Earth Engine Authenticator".
• gcloud: Ini menggunakan alur --launch-browser yang dijelaskan dalam referensi gcloud, dan --no-launch-browser jika berada di mesin jarak jauh. Klien autentikasi yang digunakan adalah "Library Autentikasi Google".
• notebook: Kami membuat klien autentikasi baru khusus untuk pekerjaan Anda - Anda akan melihat alamat email Anda di halaman izin. Klien ini disetel dalam mode "pengembangan", yang merupakan kasus khusus yang memungkinkan token mode tempel yang lebih lama. Kami perlu menggunakan project Anda sendiri untuk ini, karena klien tersebut tidak dapat dibagikan kepada banyak pengguna.