Autentikasi dan Inisialisasi

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

Editor Kode Earth Engine dan JavaScript

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

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 Anda) dan menggunakan kredensial yang dihasilkan untuk melakukan inisialisasi klien Python. Alur autentikasi menggunakan Project Cloud untuk melakukan autentikasi, dan digunakan untuk penggunaan tidak berbayar (gratis, nonkomersial) serta penggunaan berbayar. Untuk melakukan autentikasi dan inisialisasi, jalankan

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

Tindakan ini akan memilih mode autentikasi terbaik untuk lingkungan Anda terlebih dahulu, dan meminta Anda mengonfirmasi akses untuk skrip Anda. Jika kredensial sudah ada, kredensial tersebut 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() atau yang sudah ada sebelumnya sebagai kredensial default Google. Kemudian, library klien Python diinisialisasi dengan metode yang didukung oleh server backend. Anda harus menyediakan project yang Anda miliki, atau yang Anda miliki 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 melakukan inisialisasi 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 terakhir.

Detail autentikasi

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

Karena sensitivitas terhadap jenis sistem yang terlibat, ada berbagai cara untuk melanjutkan, bergantung pada situasi spesifik Anda. Sebagian besar opsi dikontrol oleh parameter auth_mode: baik 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 ambien" 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, mode 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 dijalankan 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 opsi yang memungkinkan 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 komputer di depan Anda - atau lebih tepatnya, di komputer yang sama dengan yang menjalankan browser web Anda. 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.
  • Atau, jika Anda tidak dapat menggunakan project atau menginstal gcloud atau menggunakan Colab atau menggunakan browser di mesin yang sama:
  • Berbicara dengan administrator (lagi) tentang cara membuat project. Misalnya:
    • Minta administrator untuk mengonfigurasi project untuk Anda (sebagai Pemilik atau Editor atau OAuth Config Editor)
    • Atau, minta administrator untuk memberi Anda izin membuat project.

Tabel ini menunjukkan kombinasi fitur yang didukung oleh setiap mode.

	Untuk Lokal atau Jarak Jauh?	Project Diperlukan	Cakupan yang Dapat Ditetapkan	Perlu CLI Lokal	Project Owner
localhost	lokal	Y	Y	T	T
colab	remote	Y	T	T	T
gcloud	keduanya	Y	Y	T	T
notebook	keduanya	Y	Y	T	Y

Kredensial untuk Akun Layanan dan Compute Engine

ee.Initialize() akan menggunakan kredensial Earth Engine (yang disimpan 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, dengan mengabaikan setelan default ini.

Jika Anda mengautentikasi kode Python yang akan berjalan tanpa pengawasan, Anda mungkin ingin melakukan autentikasi dengan akun layanan, bukan akun pengguna. Lihat dokumen ini untuk menggunakan akun layanan dengan Earth Engine. Metode lainnya mencakup authenticate_service_account dalam 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 dengan 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.

Petunjuk langkah demi langkah untuk mode gcloud (kasus lokal dan jarak jauh)

Langkah-langkah berikut menjelaskan cara melakukan autentikasi dari command line di komputer lokal.

1. Pastikan gcloud telah diinstal di komputer lokal.
   • Di terminal, jalankan gcloud help. Jika gcloud belum diinstal, ikuti petunjuk ini untuk menginstal gcloud.
2. Terminal Komputer Lokal
   • Di terminal, jalankan earthengine authenticate.
   • Output perintah akan menunjukkan bahwa gcloud sedang digunakan untuk mengambil kredensial.
   • Jendela browser akan terbuka ke halaman pemilihan akun. Jika browser tidak terbuka secara otomatis, klik URL.
3. Browser: Pemilihan Akun
   • Pilih akun yang ingin Anda gunakan untuk autentikasi.
4. Browser: Layar Izin
   • Tunjukkan apakah Anda bersedia memberikan cakupan yang diminta dan klik "Izinkan".
5. Browser: Layar Konfirmasi
   • Browser akan menampilkan halaman yang mengonfirmasi bahwa Anda telah diautentikasi, dan perintah earthengine authenticate di jendela terminal akan melaporkan "Successfully saved authorization token".
   • Dalam kasus jarak jauh, halaman web akan memberi Anda kode untuk ditempelkan kembali ke lingkungan Python.
6. Lanjutkan inisialisasi.

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. Anda akan diarahkan 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 mengerjakan project yang berbeda di notebook yang berbeda. Sebaiknya teruskan project secara eksplisit ke ee.Initialize(), tetapi project autentikasi akan digunakan secara default.

Petunjuk langkah demi langkah untuk mode notebook

Langkah-langkah berikut menjelaskan cara melakukan autentikasi dari dalam notebook.

1. Browser: Notebook
   1. Di sel kode notebook, jalankan kode berikut untuk memulai alur autentikasi menggunakan mode "notebook".

      import ee
      ee.Authenticate()

      Klik link di output sel untuk membuka halaman Notebook Authenticator di tab baru.
2. Browser: Notebook Authenticator
   1. Pastikan akun pengguna yang benar tercantum.
   2. Pilih Project Google Cloud yang akan digunakan untuk Autentikasi. Jika Anda perlu membuat project baru, sebaiknya gunakan konvensi penamaan "ee-xyz" dengan xyz adalah nama pengguna Earth Engine Anda yang biasa. (Jika Anda tidak dapat memilih atau membuat Project Cloud, lihat bagian pemecahan masalah di bawah.)
   Anda harus diberi izin IAM yang memadai untuk autentikasi, seperti Owner atau Editor di project, atau peran bawaan "OAuth Config Editor" tambahan selain peran IAM lain yang ditetapkan. Jika orang lain di tim Anda telah membuat konfigurasi autentikasi di project ini, Anda akan mendapatkan peringatan tambahan. Anda hanya boleh melanjutkan jika kreator adalah kolaborator tepercaya.
   3. Klik Generate Token.
3. Browser: Pemilihan Akun
   • Anda akan melihat halaman pemilihan akun. Klik akun pengguna yang ingin Anda beri akses dari notebook.
4. Browser: Halaman peringatan
   • Halaman peringatan akan ditampilkan, yang menunjukkan bahwa Google tidak membuat aplikasi (yaitu kode di notebook). Klik Lanjutkan untuk mengonfirmasi.
5. Browser: Layar Izin
   • Tunjukkan apakah Anda bersedia memberikan cakupan yang diminta, lalu klik Continue.
6. Browser: Layar Kode Otorisasi
   • Salin kode verifikasi otorisasi
7. Browser: Notebook
   • Beralih kembali ke tab notebook, lalu tempelkan kode verifikasi ke output sel notebook.
   • Output sel akan menunjukkan "Successfully saved authorization token."
8. Lanjutkan inisialisasi.

Mode notebook memiliki parameter quiet yang jarang digunakan: jika ditetapkan, mode ini akan berjalan "secara non-interaktif" dan tidak akan meminta serta menunggu Anda memasukkan kode autentikasi. Sebagai gantinya, Gemini akan 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 di 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" pada project autentikasi adalah penyiapan sekali pakai. 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 menyatakan "konfigurasi klien OAuth2 tidak kompatibel". Anda harus menggunakan project lain untuk autentikasi, atau menggunakan mode colab, localhost, atau gcloud di atas.

Detail tentang cakupan

Setelan autentikasi default Earth Engine mencakup semua cakupan yang tersedia, sehingga Anda dapat melewati bagian ini jika setelan default memenuhi persyaratan Anda.

Cakupan Earth Engine: Cakupan OAuth 2.0 menentukan dan membatasi kumpulan resource dan operasi yang diizinkan untuk diakses oleh aplikasi atas nama pengguna. Saat menggunakan OAuth untuk melakukan autentikasi dengan Earth Engine, Anda harus meminta satu atau beberapa cakupan berikut:

• https://www.googleapis.com/auth/earthengine: Akses baca dan tulis ke aset dan resource Earth Engine. Diperlukan untuk membuat, mengubah, atau menghapus aset, mengelola izin aset, dan menjalankan tugas ekspor.
• https://www.googleapis.com/auth/earthengine.readonly: Akses hanya baca ke aset Earth Engine.

Kedua cakupan memungkinkan eksekusi skrip dan menjalankan komputasi (seperti mengevaluasi ekspresi atau merender visualisasi peta).

Cakupan Google Cloud dan Drive: Jika kueri atau skrip Earth Engine Anda merujuk ke data atau aset eksternal, kredensial Anda juga harus menyertakan cakupan yang sesuai untuk layanan tersebut:

• Cloud Storage (GCS) (saat membaca dari atau menulis ke bucket Cloud Storage, seperti memuat Cloud Optimized GeoTIFF (COG) atau mengekspor output tugas):
  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.read_only
• BigQuery (BQ) (saat membaca tabel atau menulis ekspor ke BigQuery):
  • https://www.googleapis.com/auth/bigquery
• Google Drive (saat mengakses atau mengekspor data ke Google Drive):
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.readonly

Google Cloud juga menawarkan cakupan luas yang mencakup semua layanan Google Cloud:

• Cloud Platform (akses luas ke layanan Google Cloud, yang mencakup Earth Engine, Cloud Storage, dan BigQuery; perhatikan bahwa Google Drive adalah layanan Workspace terpisah dan tidak tercakup dalam cakupan ini):
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

Cakupan default: Cakupan default yang dikonfigurasi oleh Editor Kode Earth Engine dan library klien (seperti ee.Authenticate()) mencakup semua cakupan ini: earthengine, cloud-platform, dan drive (lihat detailnya di atas). Oleh karena itu, penyesuaian cakupan (misalnya, menggunakan parameter scopes di ee.Authenticate(scopes=[...])) hanya diperlukan jika Anda memiliki batasan keamanan atau kebijakan organisasi tertentu yang memerlukan pembatasan izin.

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 yang tersedia untuk membuat project.
3. Buat project dari akun non-organisasi, dan 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 has not been used in project XXX before or it is disabled"

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 sudah 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 lain. 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 apakah ada 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. Gunakan ee.Authenticate(), yang secara default akan 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 Anda 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 mesin 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. Tindakan ini akan mengharuskan Anda melakukan autentikasi dengan gcloud dari komputer yang memiliki akses ke browser web.

Error: "Your application is authenticating by using local Application Default Credentials. 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 berhasil, coba jalankan earthengine set_project YOUR_PROJECT_ID atau gcloud auth application-default set-quota-project YOUR_PROJECT_ID.

Error: "Missing required scopes for [Cloud Storage / BigQuery]"

Error ini terjadi saat permintaan Earth Engine mengakses resource Cloud Storage atau BigQuery, tetapi kredensial yang digunakan untuk melakukan inisialisasi Earth Engine tidak menyertakan cakupan yang diperlukan untuk layanan tersebut (atau cakupan cloud-platform, yang mencakup semua layanan Google Cloud). Hal ini biasanya terjadi jika Anda menyesuaikan parameter scopes selama autentikasi (misalnya, hanya memberikan cakupan Earth Engine ke ee.Authenticate(scopes=[...])) atau jika kredensial yang ada dibuat tanpa cakupan tersebut.

Ada dua cara untuk mengatasi masalah ini:

• Autentikasi ulang dengan cakupan default: Kredensial default untuk Earth Engine mencakup cakupan cloud-platform, yang mencakup Cloud Storage dan BigQuery. Lakukan autentikasi ulang menggunakan setelan default:
  • Di Python: ee.Authenticate(force=True)
  • Di command line: earthengine authenticate --force
• Sertakan cakupan yang diperlukan: Jika lingkungan Anda memerlukan penyesuaian cakupan, pastikan daftar scopes Anda menyertakan https://www.googleapis.com/auth/cloud-platform atau cakupan layanan tertentu (seperti https://www.googleapis.com/auth/devstorage.full_control atau https://www.googleapis.com/auth/devstorage.read_only untuk Cloud Storage, atau https://www.googleapis.com/auth/bigquery untuk BigQuery).

Untuk mengetahui detail selengkapnya tentang cakupan yang tersedia, lihat Detail tentang cakupan.

Catatan teknis

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

• Sebelumnya ada mode paste yang memberi Anda token untuk ditempelkan di mana saja, dan mode ini dianggap terlalu berisiko dan tidak lagi tersedia.
• colab: auth.authenticate_user() akan meminta Anda untuk membagikan kredensial kepada klien autentikasi "Colab", yaitu lingkungan notebook itu sendiri. Data ini kemudian tersedia melalui google.auth.default() dan digunakan oleh ee.Initialize().
• localhost: kredensial diteruskan dari browser ke port di komputer lokal Anda. Dalam situasi ini, keamanan end-to-end bergantung pada fakta bahwa mesin lokal Anda belum disusupi. Klien autentikasi yang akan Anda lihat adalah "Earth Engine Authenticator".
• gcloud: Tindakan 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 Google Auth".
• 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. Kita perlu menggunakan project Anda sendiri untuk ini, karena klien tersebut tidak dapat dibagikan kepada banyak pengguna.