请注意，您正在查看 Looker 文档。如需查看 Looker Studio 文档，请访问 https://support.google.com/looker-studio。

Looker API 问题排查

本页面针对在使用 Looker API 时可能会遇到的以下问题提供了问题排查步骤：

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

无法访问 API 端点

如果您无法访问 API 端点，请按以下步骤操作：

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

验证您的 API 凭据

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

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

验证 API 网址

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

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

选择左侧导航面板中的管理选项，即可访问管理面板。
点击管理面板中的 API。
查看 API 主机网址。

如果 API 主机网址字段为空，您的 Looker 实例将使用默认格式，即：
```
https://<instance_name>.cloud.looker.com:<port>
```

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

打开浏览器，然后打开浏览器控制台。（如果您需要了解如何为浏览器打开控制台，请参阅 ConcreteCMS.org 上的这篇文章。）
输入您的 API 主机网址，后跟 /alive。例如，如果您的 API 主机网址为 https://company.cloud.looker.com，请输入：
```
https://company.cloud.looker.com/alive
```
如果您的 API 主机网址字段为空，请使用默认 API 网址。例如，对于在 Google Cloud、Microsoft Azure 上托管的实例以及在 Amazon Web Services (AWS) 上托管的实例（于 2020 年 7 月 7 日或之后创建），默认 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、Looker 的开发者门户或 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 4.0 中已移除这些 API 调用。如需查看更新列表，请参阅 Looker API 4.0 正式版公告。

错误请求 (400) 错误

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

禁止访问 (403) 错误

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

根据托管 Looker 实例的环境以及 Looker 实例的配置，可访问 API 的端口号和关联网址可能会有所不同。如果使用的是错误的端口号，您可能会看到 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 版本，API 登录 REST 端点可以是以下其中一项：

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

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

对于 Swagger 代码生成客户端，base_url 应为下列之一，具体取决于所使用的 API 版本：
- https://<your-looker-hostname>:<port>/api/4.0/
- https://<your-looker-hostname>:<port>/api/3.1/
对于使用 looker.ini 的 Looker SDK 实现，api_version 的值应为 4.0 或 3.1，base_url 的值应与 Looker 实例 API 的网址相同（格式为 https://<your-looker-hostname>:<port>）。looker.ini 文件示例如下：
```
# api_version should be either 4.0 or 3.1
api_version=4.0
base_url=https://<your-looker-hostname>:<port>
```

登录后，您也会收到 404 错误。如果您已登录，但收到 404 错误，则表示您无权处理刚刚调用的 API 命令。

方法遭拒 (405) 错误

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

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

例如，如果您在 Looker 中遇到这种情况，一种可能的方法是尝试使用 update_dashboard() 端点更新 LookML 信息中心的元数据。Looker API 不支持更改 LookML 信息中心的 id 参数，因此会发生 405 错误。

冲突 (409) 错误

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

为响应 PUT 请求而很可能会出现政策冲突的情况。如果上传的文件比服务器上的现有文件更早，则会导致版本冲突，此时就出现了常见的非 Looker 示例。

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

验证 (422) 错误

如果请求中的某些内容未能执行数据检查，就会出现验证错误。请求存在以下一种或多种错误（错误响应将指定确切错误）：

缺少字段：未提供某个必需参数（错误响应会指明缺少哪个字段）。
无效：提供的值与现有值不匹配，或格式不正确。例如，如果您尝试创建 Look，但您在 API 调用中提供的查询 ID 与现有查询不匹配，您会收到验证错误。
已存在：API 调用试图创建的对象具有您的 Looker 实例中已存在的 ID 或名称。例如，数据库连接名称必须是唯一的。如果您尝试创建使用现有连接的名称的新数据库连接，您会收到代码 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 交互时总是遇到此错误，我们建议您与 Looker 支持团队联系。