Autentikasi dan Inisialisasi

Sebelum dapat membuat permintaan ke Earth Engine melalui library klien, Anda harus melakukan autentikasi dan menggunakan kredensial yang dihasilkan untuk menginisialisasi 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 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 Anda) dan menggunakan kredensial yang dihasilkan untuk menginisialisasi klien Python. Alur autentikasi menggunakan Project Cloud untuk melakukan autentikasi, dan digunakan untuk penggunaan yang tidak berbayar (gratis, nonkomersial) serta penggunaan berbayar. Untuk mengautentikasi 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 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 sebagai kredensial default Google. Kemudian, library ini menginisialisasi library klien Python dengan metode yang didukung server backend. Anda harus memberikan 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 menggunakan ini 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 memberikan izin kepada skrip Anda agar dapat mengakses data Anda. Untuk alasan keamanan, sistem autentikasi Google hanya akan meneruskan token tersebut ke sistem yang dapat diamankan - lihat catatan teknis di bawah.

Karena sensitivitas terhadap jenis sistem yang terlibat, ada berbagai cara untuk melanjutkan, bergantung pada situasi khusus 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 sekitar" 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 dijalankan 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 yang menjalankan browser web Anda. Hal ini mencakup situasi desktop jarak jauh di mana 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 mesin (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 menyetel 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:
    • Bicaralah dengan administrator (lagi) tentang pembuatan 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.

Untuk Lokal atau Jarak Jauh? Project yang Dibutuhkan Cakupan yang Dapat Ditetapkan CLI Lokal Diperlukan 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 ee.Authenticate() disimpan 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 melewati nilai default ini.

Jika Anda mengautentikasi kode Python yang akan berjalan tanpa pengawasan, sebaiknya lakukan 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. Hal 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)

  1. Pastikan gcloud telah diinstal di komputer lokal.
    • Di terminal, jalankan gcloud help. Jika gcloud tidak diinstal, ikuti petunjuk ini untuk menginstal gcloud.
  2. Terminal Mesin 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 Persetujuan
    • Tunjukkan apakah Anda bersedia memberikan cakupan yang diminta, lalu klik "Izinkan".
  5. Browser: Layar Konfirmasi
    • Browser akan menampilkan halaman yang mengonfirmasi bahwa Anda telah diautentikasi, dan perintah earthengine authenticate di jendela terminal Anda 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. Tindakan ini melakukan langkah-langkah yang sama seperti 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 project 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

  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. (Jika Anda tidak dapat memilih atau membuat Project Cloud, lihat bagian pemecahan masalah di bawah.)
    3. Klik Buat 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 ditampilkan, yang menunjukkan bahwa Google tidak membuat aplikasi tersebut (yaitu kode di notebook). Klik Lanjutkan untuk mengonfirmasi.
  5. Browser: Layar Persetujuan
    • Tunjukkan apakah Anda bersedia memberikan cakupan yang diminta, lalu klik Lanjutkan.
  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 harus menunjukkan "Successfully saved authorization token."
  8. Lanjutkan inisialisasi.

Mode notebook memiliki parameter quiet yang jarang digunakan: jika disetel, parameter ini akan berjalan "secara noninteraktif" dan tidak meminta serta menunggu Anda memasukkan kode otorisasi. Sebagai gantinya, perintah akan diberikan untuk menjalankan penyimpanan 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 lainnya.

Karena masalah keamanan, konfigurasi klien OAuth di project autentikasi adalah penyiapan sekali saja. 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 aplikasi atas nama pengguna. Saat menggunakan OAuth untuk mengautentikasi 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 mereferensikan 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 GeoTIFF yang Dioptimalkan untuk Cloud 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 berikut: earthengine, cloud-platform, dan drive (lihat sebelumnya untuk mengetahui detailnya). 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. Bicaralah dengan 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 kantor 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 dalam project XXX sebelumnya 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 memiliki konfigurasi Klien OAuth2 yang tidak kompatibel)

Project cloud hanya dapat memiliki satu konfigurasi Klien OAuth2. Anda dapat memeriksa apakah konfigurasi Klien OAuth2 telah ditetapkan untuk project Cloud dengan memeriksa ID Klien OAuth 2.0 di halaman Kredensial. Anda harus memilih project Cloud lain yang telah menyiapkan konfigurasi yang kompatibel 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 Anda 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() sebagai gantinya, 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 tetap 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 melakukan autentikasi 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 saat 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]" (Cakupan yang diperlukan untuk [Cloud Storage/BigQuery] tidak ada)

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:

  • Mengautentikasi 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 pembahasan singkat tentang berbagai kasus di atas.

  • Dulu ada mode paste yang memberi Anda token untuk ditempel 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, opsi ini 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 end-to-end 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 komputer jarak jauh. Klien autentikasi yang digunakan adalah "Google Auth Library".
  • 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 lama. Kita harus menggunakan project Anda sendiri untuk hal ini, karena klien tersebut tidak dapat dibagikan kepada banyak pengguna.