Looker API 问题排查

注意： 从 Looker 22.4 开始，Looker API 4.0 已正式发布。在 Looker 23.18 中，移除了 Looker API 3.1。

本页介绍了针对您在使用 Looker API 时可能遇到的以下问题的问题排查步骤：

• API 端点无法访问
• API 结果是无意义的文本
• API 调用无响应
• 编码无效错误
• “找不到方法”错误
• 请求错误 (400)
• “未经授权”(401) 错误
• “禁止访问 (403)”错误
• “未找到”(404) 错误
• “不允许使用的方法 (405)”错误
• CONFLICT (409) 错误
• 验证 (422) 错误
• “请求过多 (429)”错误
• 内部服务器错误 (500)

API 端点无法访问

如果您无法访问 API 端点，请执行以下操作：

• 验证您的 API 凭据
• 验证 API 主机网址
• 验证 API 端口
• 验证 API 调用网址

验证您的 API 凭据

如果无法访问 Looker API 端点，请先验证您的 API 凭据是否正确。如需查看您的 API 凭据，请执行以下操作：

1. 在 Looker 中，选择左侧导航面板中的管理选项，即可访问管理面板。
2. 在管理页面的左侧面板中，向下滚动，然后点击用户。
3. 在用户列表中搜索您的用户名，然后点击该用户名以修改您的用户页面。
4. 点击修改 API 密钥。您可以看到客户端 ID，还可以点击眼睛图标查看您配置的每个 API 密钥的客户端密钥。验证您的 API 凭据是否与您在脚本中使用的凭据一致。

验证 API 网址

访问 API 端点时出现的另一个常见问题是 API 主机网址不正确。大多数 Looker 实例都使用 API 的默认网址。不过，使用备选 API 路径的 Looker 安装或位于负载平衡器（例如集群配置）或任何其他代理后面的 Looker 安装可能不会使用默认网址。如果是这种情况，API 主机网址必须指明面向用户的 API 主机名和端口。

Looker 管理员可以在 API 管理设置中查看 API 主机网址（详见 Admin settings - API 文档页面）。如需查看 API 主机网址，请执行以下操作：

1. 点击 Looker 的主菜单图标 ，然后选择管理以打开管理面板。
2. 点击管理面板中的 API。

3. 查看 API 主机网址。

   如果 API 主机网址字段为空，您的 Looker 实例将使用默认格式，即：

   https://<instance_name>.cloud.looker.com:<port>
   

如需测试 API 主机网址，请执行以下操作：

1. 打开浏览器，然后打开浏览器控制台。

2. 输入您的 API 主机网址，然后输入 /alive。例如，如果您的 API 主机网址为 https://company.cloud.looker.com，请输入：

   https://company.cloud.looker.com/alive
   

   如果您的 API 主机网址字段为空，请使用默认 API 网址。例如，对于 2020 年 7 月 7 日当天或之后创建的托管在 Google Cloud、Microsoft Azure 和 Amazon Web Services (AWS) 上的实例，默认 Looker API 路径使用端口 443：

   https://<instance_name>.cloud.looker.com:443/alive
   

   对于在 2020 年 7 月 7 日之前在 AWS 上创建的实例，默认 Looker API 路径使用端口 19999：

   https://<instance_name>.cloud.looker.com:19999/alive
   

如果 API 主机网址正确无误，则此网址会导致空白网页，而不是错误页面。

您还可以通过查看浏览器控制台中的网络响应来验证是否已访问该 API。网络响应应为 200。

如果这些检查失败，问题可能在于您调用 API 的方式不正确，或者您的代码中存在其他错误。检查您的 API 调用和脚本中的代码。如果这些信息正确无误，请参阅下一部分，了解如何验证端口。

验证 API 端口

如果之前的检查失败，并且您使用的是客户托管的 Looker 部署，则可能需要在网络基础架构上打开 API 端口。

API 端口应转发到 Looker 服务器。对于客户托管的 Looker 部署，请让您的网络管理员检查 API 端口设置。API 端口通常为 443 或 19999。API 端口应具有与 Looker 实例端口（默认为 9999）相同的配置设置。网络管理员应验证 API 端口的以下设置是否与 Looker 实例端口的设置相同：

• 代理
• 负载均衡器
• 防火墙

验证 API 调用网址

检查您使用的 API 调用网址是否正确无误。API 端点网址的格式为：

<API Host URL>/api/<API version>/<API call>

如果您使用的是默认 API 主机网址，API 端点网址的格式为：

https://<instance_name>:<port>/api/<API version>/<API call>

您可以从 API Explorer 或 API 参考文档中获取 API 端点的网址格式。

例如，API 4.0 参考文档为“获取所有正在运行的查询”端点提供了以下相对路径：

/api/4.0/running_queries

因此，docsexamples.dev.looker.com Looker 实例上“获取所有正在运行的查询”端点的完整 API 端点网址为：

https://docsexamples.dev.looker.com:443/api/4.0/running_queries

API 结果是无意义的文本

如果 API 返回乱码文本响应，则表示您看到的可能是 PDF、PNG 或 JPG 文件的二进制内容。某些 HTTP REST 库假定 API 响应将是文本文件，因此其他类型的文件会显示为二进制文本。

在这种情况下，您需要确保 HTTP REST 库将 API 响应作为二进制数据（而非文本）进行处理。在某些情况下，这可能意味着在 API 调用上设置一个标志，以告知 HTTP REST 库它是一个二进制结果，或者可能意味着以特殊方式处理结果（例如作为字节流或字节数组），而不是将结果分配给字符串变量。

API 调用无响应

如果您能够打开 API Explorer，但 API 调用无响应，请验证 Looker 实例的 API 主机网址设置是否正确。Looker 管理员可以在 Looker 的 API 管理员设置中查看 API 主机网址（详见管理设置 - API 文档页面）。

编码无效错误

如果您在尝试进行 API 调用时收到编码错误，则可能需要在请求期间在标头中设置正确的 Content-Type。HTTP 协议标准要求任何 POST、PUT 或 PATCH 请求都包含 Content-Type 标头。由于 Looker API 始终使用 JSON，因此 Content-Type 标头应设置为 application/json。

请注意，使用 Looker SDK 会自动为您处理此问题。

“找不到方法”错误

如果您收到“找不到方法”错误（例如 method not found: all_looks()），请先检查您的 API 版本。API 4.0 中新增了一些 API 调用，也移除了一些 API 调用。如需查看更新列表，请参阅 Looker API 4.0 正式发布公告。

错误请求 (400) 错误

400 Bad Request 错误表示 API 调用中提供的数据无法识别。罪魁祸首通常是损坏或无效的 JSON，可能是解析错误。在大多数情况下，400 错误已通过身份验证，因此错误响应消息会提供有关该错误的更具体信息。

未经授权 (401) 错误

API 调用出现 401 Unauthorized 错误表示 API 调用未正确进行身份验证。如需详细了解问题排查，请参阅如何排查 401 错误？社区文章。

禁止 (403) 错误

每次用户尝试访问无权访问的 LookML 对象或其他内容时，Looker API 并不会返回 403 错误。在某些情况下，如果所有者不希望他人知道特定探索、信息中心或 LookML 对象的存在，则返回 403 错误（而非 404 错误）可以验证该对象是否存在。为防止这种情况，Looker 会在这些情况下返回 404，并且 Looker 界面中随附的错误消息会显示为：“找不到您请求的网页。该文件夹不存在，或者您无权查看。”

可访问 API 的端口号和关联的网址可能会因 Looker 实例的托管环境和 Looker 实例的配置而异。如果使用端口号不正确，您可能会看到 403 错误。例如，如果您的 Looker 实例配置了默认的 API 端口 443，则连接到 https://mycompany.looker.com/api/4.0/login（而非 https://mycompany.looker.com:443/api/4.0/login）将返回 403 错误。对于客户托管的实例，您可以详细了解 Looker 启动选项，在其中定义 API 端口。

如果您使用的是过时版本的 Ruby SDK gem，也可能会出现此问题。请务必及时更新这些宝石。您可以查看 https://rubygems.org/gems/looker-sdk。

如果您未添加网址的 /api/<version number>/ 部分，也可能会发生这种情况。在这种情况下，如果用户尝试连接到 https://mycompany.looker.com:443/login，则会看到 403 响应。

“未找到 (404)”错误

如果出现任何问题（通常是权限方面的问题），404 Not Found 错误是默认错误。404 错误的响应消息提供的信息非常少（如果有）。这是有意为之，因为系统会向登录凭据不正确或权限不足的用户显示 404 错误。Looker 不希望在 404 响应消息中提供具体信息，因为这些信息可能会被用于绘制 Looker API 的“攻击面”。

如果 API 登录尝试返回 404 错误，则很可能是由于您的 API 客户端 ID 或客户端密钥无效（请参阅本页面上文中的验证您的 API 凭据）。API 登录 REST 端点如下所示：

• https://<your-looker-hostname>:<port>/api/4.0/login

如果您使用的是 Swagger codegen API 或 Looker SDK，请确保 base_url 值正确无误：

• 对于 Swagger codegen 客户端，base_url 应如下所示：

  • https://<your-looker-hostname>:<port>/api/4.0/

• 对于使用 looker.ini 的 Looker SDK 实现，api_version 的值应为 4.0，base_url 的值应与 Looker 实例 API 的网址相同，格式为 https://<your-looker-hostname>:<port>。示例 looker.ini 文件如下所示：

  # api_version should be 4.0
  api_version=4.0
  base_url=https://<your-looker-hostname>:<port>
  

您在登录后也可能会收到 404 错误。如果您已登录，但收到 404 错误，则表示您没有对刚调用的 API 命令的权限。

不允许使用的方法 (405) 错误

405 Method Not Allowed 错误表示服务器知道请求方法，但目标资源不支持此方法。

服务器必须在 405 状态代码响应中生成 Allow 标头字段。该字段必须包含目标资源支持的方法列表。

例如，如果您尝试使用 update_dashboard() 端点更新 LookML 信息中心的元数据，就可能会在 Looker 中遇到此问题。Looker API 不支持更改 LookML 信息中心的 id 参数，因此会出现 405 错误。

冲突 (409) 错误

409 Conflict 响应状态代码表示请求与目标资源的当前状态存在冲突。

在响应 PUT 请求时，最有可能发生冲突。在非 Looker 环境中，如果上传的文件版本低于服务器上现有文件的版本，就会导致版本控制冲突，从而导致此错误。

在尝试使用 API 检出新的 Git 分支或使用 create_group() 或 create_dashboard() 等端点时，您可能会在 Looker 中遇到此错误。在这种情况下，请检查您尝试创建的对象是否已存在。

验证 (422) 错误

如果请求中的某项未通过执行的数据检查，就会出现验证错误。请求存在以下一种或多种类型的错误（错误响应将指明确切错误）：

• 缺少字段：未提供必需的参数（错误响应中会说明缺少哪个字段）。
• 无效：所提供的值与现有值不匹配，或者值的格式不正确。例如，如果您尝试创建外观，但您在 API 调用中提供的查询 ID 与现有查询不匹配，则会收到验证错误。
• 已存在：API 调用尝试创建的对象的 ID 或名称已存在于您的 Looker 实例中。例如，数据库连接名称必须是唯一的。如果您尝试创建使用现有连接名称的新数据库连接，则会收到代码为 already_exists 的验证错误。

请参阅错误响应消息，详细了解哪些字段可能缺失或必需，或者哪些字段可能包含无效值。响应消息将同时提供所有验证错误。因此，如果您缺少字段和字段不正确，错误响应将列出 API 调用存在的所有问题。

以下是示例响应：

{
  "message": "Validation Failed",
  "errors": [
    {
    "field": "dialect",
    "code": "missing_field",
    "message": "This field is required.",
    "documentation_url": "http://docs.looker.com/"
    },
    {
    "field": "db_timezone",
    "code": "invalid",
    "message": "Must specify a database timezone when user timezones are activated.",
    "documentation_url": "http://docs.looker.com/"
    }
  ],
    ...

在本例中，API 调用缺少必需的 dialect 字段，并且 db_timezone 中给出的值无效。

请求过多 (429) 错误

429 Too Many Requests 响应状态代码表示用户在给定时间内发送的请求过多（“速率限制”）。如需详细了解 Looker 的速率限制政策，请参阅 Looker 社区帖子您一次可以发送的 API 请求数是否有上限？

内部服务器错误 (500)

500 Internal Server Error 响应代码表示服务器遇到了意外情况，无法执行请求。

此错误响应是一种通用的“万能”响应。通常，这表示服务器找不到更具体的 5xx 错误代码以在响应中返回。Looker 返回的任何 500 响应都是意外的，因此，如果您在尝试与 Looker 互动时一直看到此错误，我们建议您提交支持请求。