Earth Engine 推出了非商业配额层级，以保护共享计算资源并确保为所有人提供可靠的性能。非商业项目默认使用 Community 层级，但您可以随时更改项目的层级。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

身份验证和初始化

您必须先进行身份验证并使用生成的凭据初始化 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 虚拟机、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 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 或在同一台机器上使用浏览器，请执行以下操作：
- （再次）与管理员讨论创建项目的事宜。例如：
  - 请让管理员为您配置项目（作为 Owner、Editor 或 OAuth Config Editor）
  - 或者，请让管理员授予您创建项目的权限。

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

	本地还是远程？	需要项目	可设置的范围	需要本地 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 模式的分步说明（本地和远程情况）

验证本地机器上是否安装了 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() 的项目不一定非要与此匹配，您可以在不同的笔记本中处理不同的项目，同时保留相同的项目进行身份验证。建议您将项目明确传递给 ee.Initialize()，但默认情况下会使用身份验证项目。

笔记本模式的分步说明

浏览器：笔记本
1. 在笔记本代码单元中，运行以下代码以使用“笔记本”模式启动身份验证流程。
```
import ee
ee.Authenticate()
```
  点击单元格输出中的链接，在新标签页中打开 Notebook 身份验证器页面。
浏览器：笔记本身份验证器
1. 验证列出的用户账号是否正确。
2. 选择要用于身份验证的 Google Cloud 项目。如果您需要创建新项目，我们建议您使用命名惯例“ee-xyz”，其中 xyz 是您常用的 Earth Engine 用户名。（如果您无法选择或创建云项目，请参阅下文的问题排查部分。）
3. 点击“生成令牌”。
浏览器：账号选择
- 系统会显示账号选择页面。点击您要从笔记本授予访问权限的用户账号。
浏览器：警告页面
- 系统会显示一个警告页面，指明该应用（即笔记本中的代码）并非由 Google 创建。点击“继续”以确认。
浏览器：权限请求页面
- 指明您是否愿意授予请求的范围，然后点击继续。
浏览器：授权代码屏幕
- 复制授权验证码
浏览器：笔记本
- 切换回笔记本标签页，然后将验证码粘贴到笔记本单元输出中。
- 单元格输出应指示“已成功保存授权令牌”。
继续初始化。

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

身份验证项目

您需要是笔记本模式下使用的身份验证项目的 Owner、Editor 或 OAuth Config Editor。在许多情况下，尤其是在较小的团队中，您在 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 存储桶时，例如加载 Cloud Optimized 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 云端硬盘或将数据导出到 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 Authenticator 页面上收到错误消息，可以尝试以下几种方法：

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

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

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

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

云项目只能有一个 OAuth2 客户端配置。您可以通过查看“凭据”页面上的 OAuth 2.0 客户端 ID，检查云项目是否设置了 OAuth2 客户端配置。您需要选择另一个已由 Notebook Authenticator 设置兼容配置的云项目，或者选择或创建一个没有 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)。这需要您从有权访问网络浏览器的机器上使用 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：我们会专门为您的工作创建一个新的身份验证客户端，您会在同意页面上看到自己的邮箱。此客户端设置为“开发”模式，这是一种特殊情况，允许使用旧版粘贴模式令牌。我们需要为此使用您自己的项目，因为此类客户端无法与大量用户共享。