身份验证和初始化

在通过客户端库向 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 虚拟机、App Engine 和其他环境提供可用的“环境凭据”，gcloud auth application-default login 也会创建这些凭据。

不过，建议在所有脚本的开头使用 ee.Authenticate()，以最大限度地提高兼容性。如果没有 auth_mode 参数，该函数应能在大多数情况下正常运行，但如果默认模式无法正常运行，请按照以下详细信息操作。 默认模式的选择方式如下：

• colab 如果在 Google Colab 笔记本中运行
• notebook 如果在其他非 Colab Jupyter 笔记本中运行
• localhost 如果检测到 Web 浏览器，但未安装 gcloud 二进制文件
• gcloud，否则。对于此模式，您需要安装 gcloud。

快速参考指南和表格

本决策指南概述了 ee.Authenticate() 选择的默认模式无法正常运行时可能出现的选项。例如，如果您在其他笔记本环境中运行，可能需要明确指定 notebook。

• 本地环境。
  • 本地是指您在面前的机器上（更准确地说，在 Web 浏览器运行的同一台机器上）的 Python shell 或 Python 笔记本中运行代码。这包括 Python 和浏览器都在同一（远程）机器上的远程桌面情况。
  • 使用 auth_mode=localhost 最简单，如果未安装 gcloud，系统会默认选择此选项，但您的脚本只能在本地环境中运行。
  • auth_mode=gcloud 和 auth_mode=notebook 也均可使用。
• 远程环境。
  • “远程”是指浏览器位于一台（本地）机器上，但代码在其他位置运行，例如在远程工作站或基于 Web 的笔记本上运行。
  • 如果在 Colab 中，请使用 auth_mode=colab；如果需要设置 scopes 以调用其他 API，请使用 gcloud。
  • 如果您可以在远程机器和本地机器上都安装 gcloud，请使用 auth_mode=gcloud。
  • 如果您可以使用身份验证项目（见下文），请使用 auth_mode=notebook。
  • 否则，如果您无法使用项目、安装 gcloud、使用 Colab 或在同一台机器上使用浏览器，请执行以下操作：
  • 再次与管理员讨论创建项目的事宜。例如：
    • 让管理员为您配置项目（作为所有者、编辑者或 OAuth 配置编辑者）
    • 或者，请管理员授予您创建项目的权限。

下表显示了每种模式支持的功能组合。

	本地还是远程？	所需项目	可设置的范围	需要本地 CLI	Project Owner
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 虚拟机上运行，系统会为该环境创建一个默认服务账号，ee.Initialize() 将默认使用该账号。如果启动虚拟机的 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 身份验证器页面，您需要在该页面上选择或创建“身份验证项目” - 请参阅下方的详细信息和问题排查指南。传递给 ee.Initialize() 的项目不必与此项目匹配 - 您可以在不同的笔记本中使用不同的项目，同时保持相同的项目进行身份验证。建议您明确将项目传递给 ee.Initialize()，但系统默认会使用身份验证项目。

笔记本模式的分步说明

以下步骤介绍了如何在笔记本中进行身份验证。

1. 浏览器：笔记本
   1. 在笔记本代码单元格中，运行以下代码以使用“笔记本”模式启动身份验证流程。

      import ee
      ee.Authenticate()

      点击单元格输出中的链接，在新标签页中打开笔记本验证器页面。
2. 浏览器：笔记本验证器
   1. 确认列出的用户账号正确无误。
   2. 选择要用于身份验证的 Google Cloud 项目。如果您需要创建新项目，我们建议您采用“ee-xyz”的命名惯例，其中 xyz 是您常用的 Earth Engine 用户名。（如果您无法选择或创建 Cloud 项目，请参阅下方的问题排查部分。）
   您必须被分配足够的 IAM 权限以进行身份验证，例如项目的“所有者”或“编辑者”角色，或者除了已分配的其他 IAM 角色之外，还需拥有“OAuth 配置编辑器”预定义角色。如果团队中的其他成员已在此项目上创建身份验证配置，您会收到额外的警告。只有在您信任该创作者时，才应继续操作。
   3. 点击“生成令牌”。
3. 浏览器：账号选择
   • 系统会显示账号选择页面。点击要授予笔记本访问权限的用户账号。
4. 浏览器：警告页面
   • 系统会显示一个警告页面，指出该应用（即笔记本中的代码）并非由 Google 创建。点击“继续”以确认。
5. 浏览器：同意屏幕
   • 指明您是否愿意授予所请求的范围，然后点击继续。
6. 浏览器：授权代码界面
   • 复制授权验证码
7. 浏览器：笔记本
   • 切换回笔记本标签页，然后将验证码粘贴到笔记本单元格输出中。
   • 单元格输出应显示“Successfully saved authorization token.”
8. 继续初始化。

Notebook 模式有一个很少使用的 quiet 参数：如果设置了该参数，系统会以“非互动”方式运行，不会提示您输入授权代码并等待您输入。而是会提供一个用于保存代码的运行命令。

身份验证项目

您需要是笔记本模式下所用身份验证项目的 Owner、Editor 或 OAuth 配置 Editor。在许多情况下（尤其是在较小的团队中），您在“笔记本身份验证器”页面上使用的身份验证项目可以与您用于其他工作的主项目相同。

出于安全考虑，身份验证项目中的“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 和 Google 云端硬盘范围：如果您的 Earth Engine 查询或脚本引用了外部数据或资源，您的凭据还必须包含这些服务的相应范围：

• Cloud Storage (GCS)（从 Cloud Storage 存储桶读取数据或向其中写入数据时，例如加载 Cloud-Optimized 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 代码编辑器和客户端库（例如 ee.Authenticate()）配置的默认范围包括以下所有范围：earthengine、cloud-platform 和 drive（详见上文）。因此，只有在您有特定的安全限制或组织政策要求限制权限时，才需要自定义范围（例如，在 ee.Authenticate(scopes=[...]) 中使用 scopes 参数）。

问题排查

如果我无法创建 Cloud 项目，该怎么办？

有些组织会控制哪些人可以创建 Cloud 项目。如果您在尝试创建项目时，在笔记本验证器页面上收到错误，可以尝试以下几种方法：

1. 尝试直接创建项目，以确认您是否拥有必要的权限。
2. 请与贵组织的管理员联系，了解创建项目的可用流程。
3. 使用非组织账号创建项目，并将您用于工作的账号添加为项目的所有者。注意：部分组织的安全政策会禁止从外部项目访问 OAuth 客户端。

错误：“Earth Engine API 之前未用于项目 XXX，或者已停用”

首先，请确保您已在 ee.Initialize() 中或通过命令行配置项目（Cloud 和 Colab 提供的默认项目不会启用 Earth Engine）。其次，确保已在您的项目中 启用 Earth Engine API。

错误：“项目具有不兼容的 OAuth2 客户端配置”

云项目只能有一个 OAuth2 客户端配置。您可以通过检查“凭据”页面上的 OAuth 2.0 客户端 ID 来查看云项目是否已设置 OAuth2 客户端配置。您需要选择另一个已由 Notebook 身份验证器设置兼容配置的云项目，或者选择或创建没有 OAuth2 客户端的云项目。身份验证器会自动配置此项目。遗憾的是，OAuth 系统不允许用户删除配置，因此必须使用其他项目。此项目不一定得是用于其他 Earth Engine 工作的项目。请注意，此错误不会在 Colab 模式下发生。

错误：“gcloud 失败。请检查是否存在上述任何错误，并根据需要安装 gcloud。”

如果未安装 gcloud 或 gcloud 不在您的 PATH 中，可能会出现此错误。如果您从笔记本代码单元格内调用 ee.Authenticate(auth_mode='gcloud')，也可能会出现此错误。请改用 ee.Authenticate()，它默认使用笔记本模式身份验证。如果您无法创建项目，请参阅上文中的解决方案。

如果我无法访问本地机器来安装 gcloud，该怎么办？

如果您在无法访问本地终端的纯 Web 环境中工作，但仍需要使用远程终端，则可以通过运行 earthengine authenticate --auth_mode=notebook 命令来触发笔记本模式，从而初始化命令行工具。

错误 400：redirect_uri_mismatch

如果您在无法访问网络浏览器的远程机器上进行身份验证，可能会遇到此错误。如果从命令行运行 earthengine authenticate，请尝试添加 --quiet；如果使用 Python 客户端，请尝试添加 ee.Authenticate(quiet=True)。这需要您从可访问 Web 浏览器的机器上使用 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 身份验证库”。
• notebook：我们会专门为您的工作创建一个新的身份验证客户端 - 您会在同意页面上看到自己的电子邮件地址。此客户端设置为“开发”模式，这是一种特殊情况，允许使用旧的粘贴模式令牌。我们需要使用您自己的项目，因为此类客户端无法与大量用户共享。