如何验证bing search api 的key

最快验证结论

验证 Bing Search API 的 key，最可靠的方法是用 HTTPS 向正确的 Bing Search API 端点发起一次最小搜索请求，并把密钥放在请求头 Ocp-Apim-Subscription-Key 中；如果返回 200 且响应里有搜索结果，说明 key、端点、订阅和权限基本可用；如果返回 401，通常是 key 缺失、key 错误或认证方式不对；如果返回 403，通常是有认证但无权限、订阅不可用、配额耗尽或产品状态不再支持。

需要特别注意：传统 Bing Search APIs 已于 2025 年 8 月 11 日退役。到 2026 年 5 月 6 日，如果你是新项目或普通 Azure 资源用户，可能已经无法再创建或继续使用传统 Bing Web Search API key。此时“如何验证bing search api 的key”的第一步不是直接写代码，而是先确认你验证的是传统 Bing Search API key，还是新的 Grounding with Bing Search 资源。

先确认 key 属于哪种资源

在验证前，先打开 Azure Portal，进入你保存 key 的资源页面，查看资源名称、类型、订阅状态、区域和“Keys and Endpoint”。可执行的判断方法是：如果资源页面明确显示 Bing Search、Bing Web Search、Bing Custom Search、Bing News Search 或 Bing Image Search，并且你还拥有可用合同或历史资源，那么可以继续用传统 REST 端点测试；如果显示的是 Grounding with Bing Search，它不等同于旧版 /v7.0/search 端点，不能简单用同一套 curl 请求验证。

判断标准很直接：资源状态必须是 Active 或可用，订阅没有欠费、禁用或删除；key 必须来自同一个资源的 Keys 页面，而不是其他 Azure AI 服务、Azure Cognitive Search、OpenAI 或 API Management 的 key。很多 401 错误并不是代码问题，而是把“搜索服务 key”和“别的 Azure 服务 key”混用了。

不同场景的处理也不同。测试 Web 搜索用 https://api.bing.microsoft.com/v7.0/search；测试图片搜索通常用 /v7.0/images/search；测试新闻搜索用 /v7.0/news/search；测试自定义搜索要用 /v7.0/custom/search 并带上 customconfig。注意事项是：端点和 key 必须匹配同一个产品能力，不能拿 Custom Search 的免费层 key 去调用普通 Web Search，也不能把 News Search 的错误端点写成 Web Search 端点。

用 curl 做最小验证

最小验证请求建议在本机终端或服务器上执行，不要在浏览器地址栏里拼接 key。把 YOUR_KEY 换成你的真实密钥，把查询词保持为简单英文或中文都可以。

curl -i "https://api.bing.microsoft.com/v7.0/search?q=test" \
  -H "Ocp-Apim-Subscription-Key: YOUR_KEY"

可执行判断标准如下：看到 HTTP/1.1 200 OK，并且响应 JSON 中出现 webPages、value、name、url、snippet 等字段，说明 key 至少可以完成一次 Web Search 请求；看到 401，优先检查 key 是否复制完整、请求头名称是否正确、是否误把 key 放进 URL 查询参数；看到 403，检查订阅权限、价格层、月度配额、产品是否已退役或资源是否被禁用；看到 429，说明请求频率超过 QPS 限制。

场景差异在于：如果你只是验证 key 是否能认证，用 q=test 即可；如果你验证中文市场结果，可以加 mkt=zh-CN；如果你在 CI/CD 或服务器脚本里验证，应该从环境变量读取 key，避免写入日志。注意事项是：旧资料里常见的 ?key=YOUR_KEY 或 &Ocp-Apim-Subscription-Key=YOUR_KEY 写法不推荐，标准方式是放在请求头。

用 Python 验证 key

如果你需要在应用里验证，可以写一个最小 Python 脚本。它的作用不是批量搜索，而是确认 key、端点和网络链路是否可用。

import os
import requests

key = os.environ.get("BING_SEARCH_KEY")
endpoint = "https://api.bing.microsoft.com/v7.0/search"

headers = {
    "Ocp-Apim-Subscription-Key": key
}

params = {
    "q": "test",
    "mkt": "zh-CN",
    "count": 1
}

resp = requests.get(endpoint, headers=headers, params=params, timeout=10)

print(resp.status_code)
print(resp.text[:800])

判断标准是：status_code == 200 且返回 JSON 能正常解析，说明 key 可用于该端点；如果抛出超时或连接错误，要检查网络、防火墙、代理、DNS 或公司出口策略；如果返回 400，通常是参数缺失或参数值不合法，例如没有 q；如果返回 410，检查是否用了 HTTP 而不是 HTTPS。

不同使用场景要有不同处理。后端服务可以在启动时做一次健康检查，但不建议每次用户搜索前都验证 key，因为这会额外消耗调用量；管理后台可以提供“测试连接”按钮，让管理员主动触发；生产服务应记录状态码和错误码，但不要记录完整 key。注意事项是：不要把 key 写进前端 JavaScript、App 安装包、公开 GitHub 仓库或网页源码中。

状态码怎么判断问题

验证 Bing Search API key 时，不要只看“能不能返回结果”，要结合 HTTP 状态码和错误体判断。下面是常见结果的处理方式。

状态码	含义	处理动作
`200`	请求成功	确认 JSON 中有预期字段，再记录验证通过时间。
`400`	参数缺失或参数错误	检查 `q`、`count`、`mkt`、`responseFilter` 等参数。
`401`	key 缺失或无效	重新复制 key，确认请求头名为 `Ocp-Apim-Subscription-Key`，必要时重新生成 key。
`403`	已认证但没有权限，或配额、订阅、产品状态异常	检查价格层、资源状态、月度配额、API 类型和产品是否仍可用。
`429`	超过每秒请求限制	增加限流、退避重试和缓存，不要用高并发脚本反复验证。

场景差异是：开发环境常见 401，因为复制错 key 或使用了错误 header；生产环境常见 403 或 429，因为配额、订阅、价格层和并发更容易触发限制；迁移期项目可能遇到传统 Bing Search API 已不可用的问题。注意事项是：不要把所有非 200 都归因于“key 错了”，否则会误判网络、端点和产品权限问题。

Postman 验证方法

使用 Postman 验证时，新建一个 GET 请求，URL 填写 https://api.bing.microsoft.com/v7.0/search?q=test，然后在 Headers 中添加一行：Key 为 Ocp-Apim-Subscription-Key，Value 为你的 Bing Search API key。点击 Send 后查看 Status、Body 和响应头。

判断标准是：Status 显示 200 OK 且 Body 是 JSON 搜索结果，验证通过；Status 显示 401 Unauthorized，先确认 Header 没有拼写错误，尤其不要写成 Ocp-Apim-Subscription-key 后又被工具覆盖为空；Status 显示 403 Forbidden，检查该 key 是否支持当前 API 类型。

场景差异是：Postman 适合人工排查；curl 适合命令行和服务器；Python 或 Node.js 脚本适合集成到应用的诊断功能。注意事项是：Postman Collection、环境变量和截图都可能泄露 key，分享排错截图前要遮挡完整密钥。

常见错误修正

如果你看到 Access denied due to invalid subscription key or wrong API endpoint，先按四步排查：第一，确认 key 来自当前 Bing 资源的 Keys and Endpoint 页面；第二，确认 key 放在请求头而不是查询参数；第三，确认调用的端点路径和 API 类型匹配；第四，确认传统 Bing Search APIs 是否仍在你的账户和合同范围内可用。

如果你确认 key 没错但仍然 401，可以在 Azure Portal 重新生成 Key 2，用 Key 2 测试；如果 Key 2 成功，再轮换 Key 1。判断标准是：新 key 成功、旧 key 失败，说明旧 key 可能已泄露、禁用或复制错误；两个 key 都失败，说明更可能是资源、订阅、端点或产品状态问题。

如果只有某一种接口失败，例如 Web Search 成功但 Custom Search 失败，应检查 customconfig 是否正确、资源是否为 Custom Search 类型、价格层是否支持该操作。注意事项是：不要为了排错把 key 发给第三方论坛、工单截图或公开日志；需要求助时只提供状态码、错误码、端点路径和资源类型，不提供完整 key。

生产环境验证建议

生产环境不应把“验证 key”做成频繁调用。建议在部署后、密钥轮换后、服务报警后执行一次轻量验证，并把结果记录为：验证时间、端点、状态码、错误码、资源名和环境名。这样既能判断 key 是否可用，也能避免验证请求本身消耗太多配额。

判断标准是：一次轻量请求成功即可证明认证链路可用，不需要连续请求几十次；出现 429 时说明你的验证方式已经影响速率限制，需要加退避；出现 403 时要把配额和订阅状态放在 key 错误之前排查。不同场景下，内部工具可以显示更详细错误，用户侧产品只应显示“搜索服务暂不可用”，避免暴露供应商、端点和认证细节。

注意事项是：密钥应放在服务端环境变量、密钥管理系统或云平台 Secret 中；前端只调用你自己的后端接口；后端再转发到 Bing。这样即使用户打开浏览器开发者工具，也不会看到真实 Bing Search API key。