理解 appcfg.py download_data 工具
appcfg.py download_data 是 google app engine sdk 提供的一个命令行工具，用于从 gae 应用的数据存储中批量下载数据。它通过 _ah/remote_api 端点与应用进行交互，允许开发者在本地对生产环境的数据进行操作，例如备份、迁移或分析。正确使用此工具需要注意认证、应用id以及数据存储索引等多个方面。
解决认证失败问题 (Authentication Failed)
在使用 appcfg.py download_data 时，最常见的初期障碍是认证失败。这通常表现为命令行输出 [INFO ] Authentication Failed 而没有提示输入密码。
1. 正确指定应用ID (--application 参数)
对于较新的 Google Cloud 项目或使用特定项目ID格式的应用，仅仅提供项目名称可能不足以进行认证。您可能需要使用带有 s~ 前缀的完整应用ID。这个 s~ 前缀表示服务ID，是 App Engine 内部用来区分不同应用实例的。
示例命令：
appcfg.py download_data --application='s~your-project-id' --url=http://your-project-id.appspot.com/_ah/remote_api --filename=backup.csv --kind=MyKind .
请将 your-project-id 替换为您的实际项目ID。通过 gcloud projects list 或 Google Cloud 控制台可以找到您的项目ID。
2. remote_api 的 app.yaml 配置
_ah/remote_api 是 download_data 工具与您的应用进行通信的关键端点。确保您的 app.yaml 文件正确配置了 remote_api 内置服务，并且没有被其他请求处理程序意外拦截。
app.yaml 配置要点：
-
启用 remote_api： 确保 builtins 部分包含 remote_api: on。
builtins: - remote_api: on
-
避免拦截 _ah/remote_api： remote_api 端点应由 App Engine 内部处理。如果您的 app.yaml 中有一个通用的 handler 规则（例如 url: /.*），并且它位于 remote_api 之前或没有正确排除 _ah/remote_api 路径，则可能会导致问题。App Engine 会自动处理 /_ah/remote_api 请求，因此无需为其定义自定义处理程序。确保没有规则将其重定向或错误地处理。
例如，如果您的应用有一个catch-all路由，请确保它不会干扰 _ah/remote_api。通常，App Engine 的内置服务路径具有更高的优先级。如果遇到问题，请检查日志以确认 _ah/remote_api 请求是否被您的应用代码处理。
3. 认证凭据与密码提示
如果 appcfg.py 没有提示输入密码，这通常是因为它正在尝试使用缓存的凭据或 gcloud CLI 已经为您配置的认证信息。确保您用于 gcloud 登录的账户拥有访问该 App Engine 项目的权限（例如，Project Owner 或 App Engine Admin）。如果需要强制重新认证，可以尝试清除本地的 ~/.appcfg_oauth2_tokens 文件（或类似路径），或使用 gcloud auth login 重新登录。
解决 NEED_INDEX 错误
在认证成功后，您可能会遇到 API error 4 (datastore_v3: NEED_INDEX): no matching index found 错误，尤其是在使用 --kind 参数指定要下载的数据类型时。
1. 理解 NEED_INDEX 错误
NEED_INDEX 错误表示您尝试执行的数据存储查询（在本例中由 download_data 工具在后台执行）需要一个自定义索引，但该索引尚未在您的 index.yaml 文件中定义或尚未完全构建。当查询涉及多个属性的过滤、排序或祖先路径时，通常需要自定义索引。
当 download_data 工具指定 kind 参数时，它可能会执行类似 SELECT * FROM MyKind 的查询，或者在内部为了分页和效率，可能会执行更复杂的查询。如果 MyKind 实体存在大量数据，或其内部结构导致了需要复合索引的查询模式，就会触发此错误。
2. 识别并定义缺失的索引
要解决此问题，您需要识别 download_data 工具所需的特定索引，并将其添加到您的 index.yaml 文件中。
- 查看日志： 仔细检查 bulkloader-log-*.log 文件（在 download_data 命令的输出中指定）和 Google Cloud 控制台的 App Engine 日志。这些日志可能会提供更详细的查询信息，从而帮助您确定需要哪些索引。
- 推断索引： 如果日志不够明确，可以根据您应用的实体结构和 download_data 的使用方式进行推断。例如，如果 download_data 需要按某个属性进行排序，那么该属性就需要一个索引。
示例 index.yaml 结构：
假设 download_data 在下载 Article 类型的实体时，需要对 creationDate 属性进行升序排序。您可能需要添加如下索引：
indexes:
- kind: Article
properties:
- name: creationDate
direction: asc或者，如果 download_data 在内部使用了某个过滤器和排序组合，例如 WHERE category = 'tech' ORDER BY publishDate，您可能需要：
indexes:
- kind: Article
properties:
- name: category
- name: publishDate
direction: asc3. 部署并等待索引构建
在 index.yaml 中定义了所需的索引后，您需要将其部署到 App Engine，并等待索引构建完成。
部署命令：
gcloud datastore indexes create index.yaml
或者，如果您使用的是旧版 SDK：
appcfg.py update_indexes .
注意事项：
- 索引构建可能需要一些时间，具体取决于数据量和索引的复杂性。在索引构建完成之前，相关的查询仍然会失败。
- 您可以在 Google Cloud 控制台的 "Datastore" -> "Indexes" 页面监控索引的构建状态。确保所有相关索引都显示为 "Serving" 状态。
4. 重试 download_data 命令
在确认所有必要的索引都已成功部署并处于 "Serving" 状态后，您可以重新尝试运行 appcfg.py download_data 命令。
总结与最佳实践
- 仔细检查应用ID： 确保 --application='s~your-project-id' 使用了正确的格式。
- 验证 app.yaml： 确认 builtins: - remote_api: on 已启用，且没有其他处理程序干扰 _ah/remote_api。
- 利用日志： bulkloader-log-*.log 和 App Engine 应用日志是诊断问题的宝贵资源。
- 管理 index.yaml： 积极地为您的数据存储查询（包括 download_data 可能触发的查询）定义和部署必要的索引。在开发和测试阶段就应考虑索引需求。
- 等待索引构建： 部署新索引后，务必等待其完全构建完成，否则错误可能依然存在。
通过遵循这些步骤，您将能够有效地解决 Google App Engine download_data 工具在认证和数据存储索引方面遇到的常见问题，从而确保数据备份和迁移过程的顺利进行。
