公告：凡是在 2025 年 4 月 15 日前註冊使用 Earth Engine 的非商業專案，都必須驗證非商業用途資格，才能繼續存取 Earth Engine。

本頁面由 Cloud Translation API 翻譯而成。

驗證和初始化

您必須先驗證，並使用產生的憑證初始化 Earth Engine 用戶端，才能透過用戶端程式庫向 Earth Engine 提出要求。

Earth Engine 程式碼編輯器和 JavaScript

驗證和初始化作業會在程式碼編輯器中自動處理。您可以選擇透過程式碼編輯器右上角的登入資訊，將要求路由至 Cloud 專案。

如果您使用的是 JavaScript API (位於程式碼編輯器之外)，請在 ee.data 中使用其中一個驗證輔助程式 (例如 ee.data.authenticateViaPopup())，接著使用 ee.initialize()，如此範例所示。

Python 和指令列

使用 Earth Engine Python 用戶端程式庫前，您必須進行驗證 (確認身分)，並使用產生的憑證初始化 Python 用戶端。驗證流程會使用 Cloud 專案進行驗證，並用於免付費 (免費、非商業用途) 和付費用途。如要進行驗證和初始化，請執行

    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 VM、App Engine 和其他環境會提供可用的「環境憑證」，gcloud auth application-default login 也會建立這些憑證。

不過，建議您在所有指令碼的開頭加入 ee.Authenticate()，以便盡可能提高相容性。在沒有 auth_mode 參數的情況下，這項功能可在多數情況下運作，但如果預設模式無法運作，請按照下列詳細說明操作。預設模式的選取方式如下：

colab 如果是在 Google Colab 筆記本中執行
notebook 如果是在其他非 Colab Jupyter 筆記本中執行
localhost 如果偵測到網路瀏覽器，但未安裝 gcloud 二進位檔
gcloud，否則為在這個模式下，您必須安裝 gcloud。

快速參考指南和表格

本決策指南將說明如果 ee.Authenticate() 選取的預設模式無法運作，可能的選項為何。舉例來說，如果您在其他 Notebook 環境中執行，可能需要明確指定 notebook。

本地環境。
- 「本機」表示您在電腦上執行 Python 殼層或 Python 執行筆記本中的程式碼，也就是在您前方的電腦上執行程式碼，更精確地說，就是在您執行網路瀏覽器的同一台電腦上執行程式碼。這包括遠端桌面情況，即 Python 和瀏覽器都位於相同 (遠端) 電腦上。
- 使用 auth_mode=localhost 最簡單，如果未安裝 gcloud，系統會預設選取這個選項，但您的指令碼只能在本機環境中運作。
- auth_mode=gcloud 和 auth_mode=notebook 也適用於此。
遠端環境。
- 「遠端」表示瀏覽器位於某部 (本機) 電腦上，但程式碼則在其他位置執行，例如遠端工作站或網路式筆記本。
- 如果是在 Colab 中，請使用 auth_mode=colab；如果需要設定 scopes 來呼叫其他 API，請使用 gcloud。
- 如果您可以在遠端機器和本機電腦上安裝 gcloud，請使用 auth_mode=gcloud。
- 如果可以使用驗證專案 (請參閱下方說明)，請使用 auth_mode=notebook。
- 否則，如果您無法在同一台電腦上使用專案、安裝 gcloud、使用 Colab 或使用瀏覽器：
- 請再次與管理員聯絡，瞭解如何建立專案。例如：
  - 請管理員以擁有者、編輯者或 OAuth 設定編輯者的身分，為您設定專案
  - 或者，請管理員授予您建立專案的權限。

下表列出各模式支援的功能組合。

	是本地還是遠端？	所需專案	可設定的範圍	需要本機 CLI	專案擁有者
`localhost`	局部	是	是	否	否
`colab`	遙控器	是	否	否	否
`gcloud`	兩個	是	是	否	否
`notebook`	兩個	是	是	否	是

服務帳戶和 Compute Engine 的憑證

ee.Initialize() 會使用 Earth Engine 憑證 (ee.Authenticate() 儲存在 ~/.config/earthengine/credentials)，或從 google.auth.default() 擷取憑證。但如有需要，您可以傳遞 credentials= 引數，以便使用其他來源的憑證，而無須使用這些預設值。

如果您要驗證會自動執行的 Python 程式碼，建議您使用服務帳戶進行驗證，而非使用者帳戶。如要瞭解如何在 Earth Engine 中使用服務帳戶，請參閱這些文件。其他方法包括 Colab 驗證模組中的 authenticate_service_account，以及以服務帳戶身分進行驗證的 Cloud 指南中所述的方法。

如果程式碼是在 Compute Engine VM 上執行，系統會為環境建立預設服務帳戶，ee.Initialize() 預設會使用該帳戶。如果啟動 VM 的 Cloud 專案未註冊使用 Earth Engine (商業或非商業用途)，您可能需要註冊服務帳戶。

模式詳細資料

auth_mode=colab。ee.Authenticate() 會視需要執行 colab.auth.authenticate_user()，藉此建立或取得 Colab 支援的預設憑證。憑證一律會使用 cloud-platform 範圍，也可以用來呼叫其他 Cloud API。

auth_mode=gcloud。這會將驗證權限委派給 gcloud 工具，並與使用預設 Earth Engine 範圍 (earthengine、cloud-platform 和 drive) 或 scopes 引數中的範圍執行 gcloud auth application-default login 相同。gcloud 模式適用於本機和遠端案例。

gcloud 模式 (本機和遠端) 的逐步操作說明

確認本機電腦已安裝 gcloud。
- 在終端機中執行 gcloud help。如果尚未安裝 gcloud，請按照操作說明安裝 gcloud。
本機電腦終端機
- 在終端機中執行 earthengine authenticate。
- 指令輸出內容會指出 gcloud 正在使用來擷取憑證。
- 瀏覽器視窗會開啟帳戶選取頁面。如果瀏覽器沒有自動開啟，請按一下網址。
瀏覽器：帳戶選擇
- 選取要用於驗證的帳戶。
瀏覽器：同意畫面
- 指出是否願意授予要求的權限範圍，然後按一下「允許」。
瀏覽器：確認畫面
- 瀏覽器會顯示一頁確認您已通過驗證的訊息，而終端機視窗中的 earthengine authenticate 指令會回報「已成功儲存授權權杖」。
- 在極少數情況下，網頁會提供程式碼，讓您貼回 Python 環境。
繼續初始化。

auth_mode=localhost。這是在未安裝 gcloud 的情況下，類似 gcloud 的流程。它執行的步驟與 gcloud 相同，但僅適用於本機案例。您可以提供選用的網際網路通訊埠號碼 (例如 localhost:8086)，或使用 localhost:0 自動選取通訊埠。預設通訊埠為 8085。

auth_mode=notebook。這是一種通用模式，可在無法使用本機指令列的遠端情況下運作。系統會將您導向 Notebook Authenticator 頁面，您需要選擇或建立「驗證專案」-- 請參閱下方的詳細說明和疑難排解指南。傳遞至 ee.Initialize() 的專案不必與此相符。您可以在不同的 Notebook 中處理不同的專案，同時保留用於驗證的專案。建議您明確將專案傳遞至 ee.Initialize()，但系統預設會使用驗證專案。

筆記型電腦模式的逐步操作說明

瀏覽器：Notebook
1. 在筆記本程式碼儲存格中，執行下列程式碼，以「筆記本」模式啟動驗證流程。
```
import ee
ee.Authenticate()
```
  按一下儲存格輸出內容中的連結，在新分頁中開啟 Notebook Authenticator 頁面。
瀏覽器：Notebook Authenticator
1. 確認列出的使用者帳戶正確無誤。
2. 選取要用於驗證的 Google Cloud 專案。如果您需要建立新專案，建議使用「ee-xyz」命名慣例，其中 xyz 是您平常使用的 Earth Engine 使用者名稱。(如果您無法選取或建立 Cloud 專案，請參閱下方的疑難排解部分)。
3. 按一下「產生權杖」。
瀏覽器：帳戶選擇
- 系統會顯示帳戶選取頁面。按一下要授予存取權的使用者帳戶。
瀏覽器：警告頁面
- 系統會顯示警告頁面，指出 Google 並未建立應用程式 (即筆記本中的程式碼)。按一下「繼續」即可確認。
瀏覽器：同意畫面
- 指出是否願意授予要求的權限範圍，然後按一下「繼續」。
瀏覽器：授權碼畫面
- 複製授權驗證碼
瀏覽器：Notebook
- 切換回筆記本分頁，然後將驗證碼貼到筆記本儲存格輸出內容中。
- 儲存格輸出內容應顯示「Successfully saved authorization token」。
繼續初始化。

筆記本模式有一個不常使用的 quiet 參數：如果已設定，則會以「非交互式」方式執行，且不會提示並等待您輸入驗證碼。而是提供可執行的指令來儲存程式碼。

驗證專案

您必須是使用 Notebook 模式的驗證專案的擁有者、編輯者或 OAuth 設定編輯者。在許多情況下 (尤其是在較小的團隊中)，您在 Notebook Authenticator 頁面上使用的驗證專案，可以與您用於其他工作的主專案相同。

基於安全性考量，驗證專案中的「OAuth 用戶端設定」是一次性的設定。如果您或其他使用者基於其他原因在專案中設定 OAuth 用戶端，就無法移除該用戶端，並會看到「不相容的 OAuth2 用戶端設定」錯誤訊息。您必須使用其他專案進行驗證，或使用上述的 Colab、localhost 或 gcloud 模式。

疑難排解

如果無法建立 Cloud 專案，該怎麼辦？

部分機構會控管哪些使用者可以建立 Cloud 專案。如果在嘗試建立專案時，Notebook Authenticator 頁面顯示錯誤訊息，請嘗試以下幾種方法：

請嘗試直接建立專案，確認您是否具備必要權限。
請與貴機構的管理員聯絡，瞭解建立專案的程序。
透過非機構帳戶建立專案，然後將用於工作用途的帳戶新增為專案擁有者。注意：部分機構設有安全性政策，禁止外部專案存取 OAuth 用戶端。

錯誤：「Earth Engine API 先前未用於專案 XXX，或已遭停用」

首先，請確認您已在 ee.Initialize() 或命令列中設定專案 (Cloud 和 Colab 提供的預設專案不會啟用 Earth Engine)。其次，請確認專案已啟用 Earth Engine API。

錯誤：「專案的 OAuth2 用戶端設定不相容」

Cloud 專案只能有一個 OAuth2 用戶端設定。您可以查看憑證頁面上的 OAuth 2.0 用戶端 ID，確認 Cloud 專案是否已設定 OAuth2 用戶端。您必須選取另一個 Cloud 專案，該專案已由 Notebook Authenticator 設定相容的設定，或是選取或建立不含 OAuth2 用戶端的 Cloud 專案。驗證器會自動設定這個專案。很抱歉，OAuth 系統不允許使用者刪除設定，因此您必須使用其他專案。這個專案不必與用於其他 Earth Engine 工作相同。請注意，這項錯誤不會在 Colab 模式中發生。

錯誤：「gcloud 失敗。請檢查上述錯誤，並視需要安裝 gcloud。」

如果未安裝 gcloud 或未在 PATH 中，就可能會發生這個錯誤。如果你在 Notebook 程式碼單元中呼叫 ee.Authenticate(auth_mode='gcloud')，也可能會發生這個問題。請改用 ee.Authenticate()，預設會使用 Notebook 模式驗證。如果無法建立專案，請參閱上述解決方案。

如果我沒有本機機器可用來安裝 gcloud，該怎麼辦？

如果您在僅限網頁的環境中工作，無法存取本機終端機，但仍需要使用遠端終端機，您仍可透過執行 earthengine authenticate --auth_mode=notebook 指令觸發 Notebook 模式，來初始化指令列工具。

錯誤 400：redirect_uri_mismatch

如果您在沒有網路瀏覽器可供存取的遠端機器上進行驗證，可能會收到這項錯誤。如果您是透過指令列執行 earthengine authenticate，請嘗試新增 --quiet；如果您使用 Python 用戶端，請新增 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：這會使用 gcloud 參考資料中所述的 --launch-browser 流程，如果是在遠端機器上，則會使用 --no-launch-browser。使用的驗證用戶端為「Google 驗證程式庫」。
notebook：我們會為您的工作建立新的授權用戶端，您會在同意聲明頁面中看到自己的電子郵件地址。這個用戶端會設為「開發」模式，這是允許舊版貼上模式符記的特殊情況。我們需要使用您自己的專案，因為這類用戶端無法與大量使用者共用。