身份验证和初始化

您必须先进行身份验证，然后使用生成的凭据初始化 Earth Engine 客户端，然后才能通过客户端库向 Earth Engine 发出请求。

Earth Engine 代码编辑器和 JavaScript

身份验证和初始化会在代码编辑器中自动处理。您可以选择通过 Code Editor 右上角的登录信息，将请求路由到 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 客户端库。您需要提供一个您拥有或有权使用的项目。请参阅 Cloud 项目设置，注册项目并启用 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 笔记本中运行代码，更确切地说，是在运行 Web 浏览器的机器上运行代码。这包括 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 模式的分步说明（本地和远程用例）

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

记事本模式有一个鲜少使用的 quiet 参数：如果设置了该参数，则会以“非交互式”方式运行，不会提示您输入身份验证码，也不会等待您输入身份验证码。而是会提供一个用于保存代码的运行命令。

身份验证项目

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

出于安全考虑，身份验证项目上的“OAuth 客户端配置”是一次性设置。如果您或其他用户出于其他原因在项目中设置了 OAuth 客户端，则无法将其移除，并且您会看到一条内容为“OAuth2 客户端配置不兼容”的错误消息。您需要使用其他项目进行身份验证，或使用上述 colab、localhost 或 gcloud 模式。

问题排查

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

某些组织会控制哪些人可以创建 Cloud 项目。如果您在尝试创建项目时在“Notebook Authenticator”页面上收到错误消息，可以尝试以下几种方法：

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

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

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

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

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

错误：“gcloud 失败。Please check for any errors above and install gcloud if needed."

如果未安装 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。

技术说明

对于对技术感兴趣的用户：需要这些不同的凭据创建机制，是因为需要将凭据传递到已知且受信任的环境。下面简要介绍了上述不同情况。

  • 以前有一种 paste 模式，可让您获得一个可粘贴到任何位置的令牌，但此模式被认为风险太高，因此已不再提供。
  • colab：auth.authenticate_user() 会提示您与“Colab”身份验证客户端（即笔记本环境本身）共享凭据。然后，这些数据可通过 google.auth.default() 获取，并由 ee.Initialize() 使用。
  • localhost：凭据会从浏览器传递到本地机器上的端口。在这种情况下，端到端安全性取决于您的本地机器是否未遭到入侵。您将看到的身份验证客户端是“Earth Engine 身份验证器”。
  • gcloud：这使用 gcloud 参考文档中所述的 --launch-browser 流程，如果是在远程机器上，则使用 --no-launch-browser。使用的身份验证客户端是“Google Auth 库”。
  • notebook：我们会专门为您的工作创建一个新的身份验证客户端，您会在意见征求页面上看到您的电子邮件地址。此客户端设置为“开发”模式，这是一种特殊情况，允许使用旧的粘贴模式令牌。我们需要使用您自己的项目来实现此目的，因为此类客户端无法与大量用户共享。