GridDB Cloud WebAPI 的 Basic Auth 与 API key 如何使用？

2026-11-04数据小许

应该使用哪种认证方式？

官方 GridDB Cloud 快速入门指南所描述的数据库 WebAPI 使用数据库用户的 Basic Auth。原代码中 Authorization: Basic <Base64(user:password)> 的构造方式没有明显错误；仅凭 401 Unauthorized，无法确定问题出在密码、用户名还是请求目标。

GridDB Cloud Quick Start Guide v2.1，第 5.1.6 节明确使用 Basic Authentication，没有给出该数据库接口使用 X-API-Key 或 Authorization: Bearer 的方法。因此，应先按 Basic Auth 排查。如果你的服务另有 API key 文档，需要确认它适用的具体 endpoint，不要直接套用到这个 WebAPI。

请求头格式为：

Authorization: Basic <Base64(username:password)>
Content-Type: application/json; charset=UTF-8

其中 <Base64(username:password)> 需要替换为编码结果，不能原样发送。

Free Plan 支持 WebAPI 吗？

支持。GridDB Cloud 官方产品页将 Web API access 列为 Free Plan 的访问能力，因此 Free Plan 不只提供 GUI 和 JDBC。v2.1 快速入门指南也区分了 Free Plan 的 WebAPI 访问和付费计划的客户端 API 访问。

连接地址应该从哪里获取？

从开通邮件或管理控制台复制分配给你的完整 WebAPI URL，不要根据集群名猜测 <clusterName>.griddb.net。

官方指南中的 Cloud URL 示例可能包含额外的路径前缀；Free Plan 提供的 URL 也可能已经包含集群名和数据库名。指南中的免费数据库使用分配的名称，不能直接假设为 public。参见快速入门指南第 5.1.2 至 5.1.4 节。

原代码中的三项都需要与实际分配信息逐一核对：

<cluster-host>：实际 WebAPI 主机及可能存在的路径前缀。
<cluster-name>：实际集群名。
public：实际数据库名，Free Plan 尤其需要检查。

自行部署 WebAPI 的 URL 示例可以帮助理解路径结构，但不能用来推导 Cloud 租户的完整地址。

先核对数据库用户和访问权限

在控制台的 GridDB Users 中检查用于访问数据库的用户，使用界面显示的完整用户名。不要直接把管理 GUI 登录账号或示例中的 admin 当作数据库凭据。

v2.1 指南说明，Free Plan 创建的数据库用户名会自动带上合同 ID 前缀。可以优先检查是否遗漏了前缀，但不能据此断定这就是当前 401 的原因。

还需要为该用户授予目标数据库的访问权限，并在 Network Access 中允许实际发起请求的公网出口 IP。官方 Cloud Starter Guide介绍了数据库用户、READ/ALL 权限及 IP 允许列表的设置；只读查询应按需选择权限。

Python 请求示例

可以让 requests 生成 Basic Auth 请求头，减少手工拼接。下面约定 GRIDDB_DATABASE_URL 是已经包含集群名和数据库名的完整地址，末尾形如 /dbs/<实际数据库名>，不包含 /containers。

import os
import requests
from requests.auth import HTTPBasicAuth

# 从管理控制台或开通邮件复制完整的数据库 WebAPI URL。
database_url = os.environ["GRIDDB_DATABASE_URL"].rstrip("/")
username = os.environ["GRIDDB_USERNAME"]
password = os.environ["GRIDDB_PASSWORD"]

with requests.Session() as session:
    session.auth = HTTPBasicAuth(username, password)
    session.headers.update({
        "Content-Type": "application/json; charset=UTF-8"
    })

    response = session.get(
        f"{database_url}/checkConnection",
        timeout=30,
        allow_redirects=False,
    )
    print(response.status_code, response.text)
    response.raise_for_status()

    if response.status_code == 200:
        response = session.get(
            f"{database_url}/containers",
            params={"limit": 100},
            timeout=30,
            allow_redirects=False,
        )
        print(response.status_code, response.text)
        response.raise_for_status()

示例先用 checkConnection 验证连接，再请求 /containers 获取容器列表。获取容器列表和查询容器内的数据是不同操作。官方 WebAPI Reference提供了这两个接口的请求示例。

示例关闭了自动重定向，以便发现地址是否指向登录页或其他入口；如果出现 3xx，应先核对 URL。示例没有连接你的实例，不能保证替换环境变量后一定成功。

仍然返回 401 时如何定位？

按以下顺序检查：

确认请求发往分配的 WebAPI URL，包含完整路径前缀、集群名和数据库名。
确认使用数据库用户及其当前密码，用户名包含控制台显示的全部前缀。
确认用户有目标数据库的访问权限，当前公网出口 IP 已加入允许列表。
查看响应正文及 WWW-Authenticate（若存在）、Location 等响应头，判断响应是否来自预期接口。

官方 Cloud Starter Guide建议遇到 401 时检查数据库用户凭据，遇到 403 时检查 IP 允许列表。可以从这里开始排查，具体原因仍需结合实际响应判断。

生产环境如何选择？

对于上述文档覆盖的 WebAPI，采用文档明确支持的 Basic Auth，并通过 HTTPS 访问。Base64 只是编码，无法代替传输加密。

建议使用专用数据库用户、按需授权，并通过密钥管理服务或受控配置注入凭据。不要把密码或 Authorization 值写入源码、公开日志或浏览器前端。

如果你的 Cloud 服务明确提供 API key，并说明了其适用接口和请求头格式，可以据此选择 API key。目前核对的资料不足以支持“该 endpoint 应改用 Bearer 或 X-API-Key”的结论。