驗證和初始化

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

Earth Engine 程式碼編輯器和 JavaScript

程式碼編輯器會自動處理驗證和初始化作業。您也可以在程式碼編輯器右上角登入，選擇透過雲端專案轉送要求。

如果您使用的是 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 參數，則適用於大多數情況，但如果預設模式無法運作，請按照下列詳細資料操作。預設模式的選取方式如下：

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

快速參考指南和表格

如果 ee.Authenticate() 選取的預設模式無法運作，本決策指南會列出可能的選項。舉例來說，如果您在其他筆記本環境中執行，可能需要明確指定 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	local	是	是	否	否
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 (商業或非商業)，您可能需要註冊服務帳戶才能使用 Earth Engine。

模式詳細資料

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

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

gcloud 模式的逐步說明 (本機和遠端案例)

下列步驟說明如何從本機電腦的指令列進行驗證。

1. 確認本機電腦已安裝 gcloud。
   • 在終端機中執行 gcloud help。如果尚未安裝 gcloud，請按照這些操作說明安裝 gcloud。
2. 本機電腦終端機
   • 在終端機中執行 earthengine authenticate。
   • 指令輸出內容會指出系統正在使用 gcloud 擷取憑證。
   • 瀏覽器視窗會開啟帳戶選取頁面。如果瀏覽器未自動開啟，請點選網址。
3. 瀏覽器：選取帳戶
   • 選取要用於驗證的帳戶。
4. 瀏覽器：同意畫面
   • 指出您是否願意授予要求的範圍，然後按一下「允許」。
5. 瀏覽器：確認畫面
   • 瀏覽器會顯示確認您已通過驗證的頁面，終端機視窗中的 earthengine authenticate 指令則會回報「Successfully saved authorization token.」(已成功儲存授權權杖)。
   • 在極少數情況下，網頁會提供一組程式碼，請將其貼回 Python 環境。
6. 繼續初始化。

auth_mode=localhost。如果未安裝 gcloud，則可採用類似 gcloud 的流程。這項工具執行的步驟與 gcloud 相同，但僅適用於本機。您可以提供選用的網際網路通訊埠編號 (例如 localhost:8086)，或使用 localhost:0 自動選取通訊埠。預設通訊埠為 8085。

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

Notebook 模式逐步說明

以下步驟說明如何從筆記本中進行驗證。

1. 瀏覽器：Notebook
   1. 在筆記本程式碼儲存格中，執行下列程式碼，使用「筆記本」模式啟動驗證流程。

      import ee
      ee.Authenticate()

      點選儲存格輸出內容中的連結，在新分頁開啟 Notebook Authenticator 頁面。
2. 瀏覽器：Notebook Authenticator
   1. 確認列出的使用者帳戶正確無誤。
   2. 選取要用於驗證的 Google Cloud 專案。如需建立新專案，建議採用「ee-xyz」的命名慣例，其中 xyz 是您常用的 Earth Engine 使用者名稱。(如果無法選取或建立雲端專案，請參閱下方的疑難排解一節)。
   您必須具備足夠的 IAM 權限才能進行驗證，例如專案的「擁有者」或「編輯者」角色，或是在其他指派的 IAM 角色之外，額外具備「OAuth 設定編輯者」預先定義的角色。如果團隊中已有其他成員在這項專案中建立驗證設定，系統會顯示額外警告。除非創作者是值得信賴的協作者，否則請勿繼續操作。
   3. 按一下「Generate Token」。
3. 瀏覽器：選取帳戶
   • 系統會顯示帳戶選取頁面。按一下要從筆記本授予存取權的使用者帳戶。
4. 瀏覽器：警告頁面
   • 系統會顯示警告頁面，指出 Google 並未建立應用程式 (即筆記本中的程式碼)。點選「繼續」表示您已瞭解。
5. 瀏覽器：同意畫面
   • 指出您是否願意授予要求的範圍，然後按一下「Continue」(繼續)。
6. 瀏覽器：授權碼畫面
   • 複製授權驗證碼
7. 瀏覽器：Notebook
   • 切換回筆記本分頁，然後將驗證碼貼到筆記本儲存格輸出內容中。
   • 儲存格輸出內容應會顯示「Successfully saved authorization token.」
8. 繼續初始化。

Notebook 模式有一個不常使用的 quiet 參數：設定後，系統會以「非互動」方式執行，不會提示並等待您輸入驗證碼。而是提供指令，讓您執行並儲存程式碼。

驗證專案

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

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

範圍詳細資料

Earth Engine 的預設驗證設定包含所有可用範圍，因此如果預設設定符合需求，您可以略過本節。

Earth Engine 範圍：OAuth 2.0 範圍定義並限制應用程式可代表使用者存取的資源和作業。使用 OAuth 向 Earth Engine 驗證時，您必須要求下列一或多個範圍：

• https://www.googleapis.com/auth/earthengine：可讀取及寫入 Earth Engine 資產和資源。建立、修改或刪除資產、管理資產權限，以及執行匯出工作時，必須具備這項角色。
• https://www.googleapis.com/auth/earthengine.readonly：具備 Earth Engine 資產的唯讀存取權。

這兩種範圍都允許執行指令碼和運算 (例如評估運算式或轉譯地圖視覺化)。

Google Cloud 和雲端硬碟範圍：如果 Earth Engine 查詢或指令碼參照外部資料或資產，憑證也必須包含這些服務的適當範圍：

• Cloud Storage (GCS) (讀取或寫入 Cloud Storage bucket 時，例如載入雲端最佳化 GeoTIFF (COG) 或匯出工作輸出內容)：
  • 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) (讀取資料表或將匯出內容寫入 BigQuery 時)：
  • https://www.googleapis.com/auth/bigquery
• Google 雲端硬碟 (存取或匯出資料至 Google 雲端硬碟時)：
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.readonly

Google Cloud 也提供涵蓋所有 Google Cloud 服務的廣泛範圍：

• Cloud Platform (廣泛存取 Google Cloud 服務，包括 Earth Engine、Cloud Storage 和 BigQuery；請注意，Google 雲端硬碟是獨立的 Workspace 服務，不屬於這些範圍)：
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

預設範圍：Earth Engine 程式碼編輯器和用戶端程式庫 (例如 ee.Authenticate()) 設定的預設範圍包含下列所有範圍：earthengine、cloud-platform 和 drive (詳情請參閱上文)。因此，只有在您有特定的安全性限制或組織政策，需要限制權限時，才需要自訂範圍 (例如在 ee.Authenticate(scopes=[...]) 中使用 scopes 參數)。

疑難排解

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

部分組織會控管哪些人可以建立雲端專案。如果在嘗試建立專案時，Notebook 驗證器頁面顯示錯誤，請嘗試下列做法：

1. 請嘗試直接建立專案，確認是否具備必要權限。
2. 請洽詢貴組織的管理員，瞭解有哪些程序可用於建立專案。
3. 使用非組織帳戶建立專案，並將工作帳戶新增為專案擁有者。注意：部分組織設有安全性政策，禁止存取外部專案的 OAuth 用戶端。

錯誤：「專案 XXX 未曾使用或已停用 Earth Engine API」

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

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

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

錯誤：gcloud 失敗。請檢查上方是否有任何錯誤，並視需要安裝 gcloud。」

如果未安裝 gcloud 或 PATH 中沒有 gcloud，就可能發生這項錯誤。從筆記本程式碼儲存格中呼叫 ee.Authenticate(auth_mode='gcloud')，也可能發生這種情況。請改用 ee.Authenticate()，系統預設會使用筆記本模式驗證。如果無法建立專案，請參閱上方的解決方案。

如果無法存取本機電腦，該如何安裝 gcloud？

如果您在僅限網頁的環境中工作，無法存取本機終端機，但仍需要使用遠端終端機，則可執行 earthengine authenticate --auth_mode=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。

錯誤：「缺少 [Cloud Storage/BigQuery] 的必要範圍」

如果 Earth Engine 要求存取 Cloud Storage 或 BigQuery 資源，但用於初始化 Earth Engine 的憑證不包含該服務所需的範圍 (或涵蓋所有 Google Cloud 服務的 cloud-platform 範圍)，就會發生這項錯誤。這通常是因為您在驗證期間自訂了 scopes 參數 (例如僅向 ee.Authenticate(scopes=[...]) 提供 Earth Engine 範圍)，或現有憑證建立時未包含這些範圍。

解決這個問題的方法有兩種：

• 使用預設範圍重新驗證：Earth Engine 的預設憑證包含 cloud-platform 範圍，涵蓋 Cloud Storage 和 BigQuery。使用預設設定重新驗證：
  • Python：ee.Authenticate(force=True)
  • 在指令列中：earthengine authenticate --force
• 加入必要範圍：如果環境需要自訂範圍，請確認 scopes 清單包含 https://www.googleapis.com/auth/cloud-platform 或特定服務範圍 (例如 Cloud Storage 的 https://www.googleapis.com/auth/devstorage.full_control 或 https://www.googleapis.com/auth/devstorage.read_only，或 BigQuery 的 https://www.googleapis.com/auth/bigquery)。

如要進一步瞭解可用範圍，請參閱「範圍詳細資料」。

技術附註

技術細節：之所以需要這些不同的憑證建立機制，是因為必須將憑證傳遞至已知且受信任的環境。以下簡要說明上述不同情況。

• 過去曾有 paste 模式，可提供權杖讓您貼到任何地方，但這項功能被認為風險過高，因此已停用。
• colab：auth.authenticate_user() 會提示您與「Colab」驗證用戶端 (即筆記本環境本身) 共用憑證。這些資料可透過 google.auth.default() 取得，並由 ee.Initialize() 使用。
• localhost：憑證會從瀏覽器傳遞至本機電腦上的通訊埠。在這種情況下，端對端安全防護機制取決於本機電腦是否遭到入侵。您會看到的驗證用戶端是「Earth Engine Authenticator」。
• gcloud：這會使用 gcloud 參考資料中說明的 --launch-browser 流程，如果是在遠端機器上，則會使用 --no-launch-browser。使用的驗證用戶端是「Google Auth Library」。
• notebook：我們會專為您的工作建立新的驗證用戶端，您會在同意頁面上看到自己的電子郵件地址。這個用戶端設為「開發」模式，這是一種特殊情況，允許使用舊版貼上模式權杖。我們必須使用您自己的專案，因為這類用戶端無法與大量使用者共用。