Looker API 问题排查

注意： 自 Looker 22.4 起，Looker API 4.0 已正式推出。在 Looker 23.18 中，Looker API 3.1 已被移除。

本页提供了以下 Looker API 问题的排查程序：

• API 端点无法访问
• API 结果是无意义的文本
• API 调用无响应
• “编码无效”错误
• “找不到方法”错误
• “Bad Request (400)”错误
• “未经授权”(401) 错误
• “禁止访问 (403)”错误
• “未找到 (404)”错误
• “不允许使用的方法 (405)”错误
• 冲突 (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 主机网址（如需了解详情，请参阅管理员设置 - 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 网址。例如，对于托管在 Google Cloud、Microsoft Azure 上的实例以及在 2020 年 7 月 7 日或之后创建的托管在 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 浏览器，但 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 调用是 API 4.0 中的新调用，或已在 API 4.0 中移除。如需查看更新列表，请参阅 Looker API 4.0 正式版发布公告。

“错误请求 (400)”错误

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

“未经授权 (401)”错误

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

“禁止”(403) 错误

Looker API 不会在用户每次尝试访问其无权访问的 LookML 对象或其他内容时都返回 403 错误。在某些情况下，返回 403 错误而不是 404 错误可能会验证特定探索、信息中心或 LookML 对象是否存在，而所有者可能不希望其他人知道这一点。为防止出现这种情况，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，也可能会出现此问题。请务必及时更新这些 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 代码生成 API 或 Looker SDK，请确保您的 base_url 值正确无误：

• 对于 Swagger 代码生成客户端，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 命令。

“Method Not Allowed (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) 错误

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

• 缺少字段：缺少必需的参数（错误响应会指明缺少哪个字段）。
• 无效：提供的值与现有值不匹配，或者值的格式不正确。例如，如果您尝试创建 Look，但 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 互动时一直看到此错误，建议您提交支持请求。