驗證和初始化

如要透過用戶端程式庫向 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。

• 本機環境。
  • 「本機」是指您在面前的電腦上，透過 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.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 模式的逐步說明 (本機和遠端案例)

下列步驟說明如何在本機電腦上透過指令列進行驗證。

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 Authenticator」頁面，你必須選擇或建立「驗證專案」- 詳情請參閱下方的疑難排解指南。傳遞至 ee.Initialize() 的專案不必與此相符，您可以在不同筆記本的不同專案中工作時，保留相同的專案進行驗證。建議您將專案明確傳遞至 ee.Initialize()，但系統預設會使用驗證專案。

筆記本模式逐步說明

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

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

      import ee
      ee.Authenticate()

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

筆記本模式有一個很少使用的 quiet 參數：如果設定這個參數，系統會「非互動式」執行，不會提示您輸入授權碼並等待輸入。而是提供指令，讓您執行來儲存程式碼。

驗證專案

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

基於安全考量，驗證專案的「OAuth 用戶端設定」只能設定一次。如果您或其他使用者基於其他原因在專案中設定 OAuth 用戶端，則無法移除，且會看到「不相容的 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 或匯出工作輸出內容)：
  • 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 Code Editor 和用戶端程式庫 (例如 ee.Authenticate()) 設定的預設範圍包含所有這些範圍：earthengine、cloud-platform 和 drive (詳情請參閱前文)。因此，只有在特定安全限制或機構政策要求限制權限時，才需要自訂範圍 (例如在 ee.Authenticate(scopes=[...]) 中使用 scopes 參數)。

疑難排解

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

部分機構會控管哪些使用者可以建立 Cloud 專案。嘗試建立專案時，如果筆記本驗證器頁面顯示錯誤訊息，請嘗試下列做法：

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

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

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

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

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

錯誤：「gcloud failed. 請檢查上述是否有任何錯誤，並視需要安裝 gcloud。

如果未安裝 gcloud 或 gcloud 不在 PATH 中，就可能發生這個錯誤。如果您從筆記本程式碼儲存格中呼叫 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 的憑證未包含該服務 (或 cloud-platform 範圍，其中涵蓋所有 Google Cloud 服務) 的必要範圍，就會發生這個錯誤。如果您在驗證期間自訂 scopes 參數 (例如只將 Earth Engine 範圍提供給 ee.Authenticate(scopes=[...]))，或是現有憑證是在沒有這些範圍的情況下建立，通常就會發生這種情形。

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

• 使用預設範圍重新驗證：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：我們會專為你的工作建立新的授權用戶端，同意頁面上會顯示你的電子郵件地址。這個用戶端設為「開發」模式，這是特殊情況，允許使用舊版貼上模式權杖。我們必須使用您自己的專案，因為這類用戶端無法與大量使用者共用。