异步请求

异步请求由 Web Unlocker API 和 SERP API 两款产品支持

异步请求 VS 同步请求

处理 Web Unlocker API 和 SERP API 请求有两种方式：

default 同步请求 - 发送请求并立即获得实时响应
异步请求 - 发送请求（无需等待立即响应），稍后通过指定 API 端点获取结果。回调时间通常为 5 分钟内，但高峰期可能长达 8 小时。响应自请求发送之时起最多存储 48 小时。

异步请求推荐用于高流量请求，且不需要立即或实时响应，可以等待几分钟一次性获取所有响应。

为什么要使用异步请求？

成功率 99.99%
稳定性
灵活性 - 可以在自己选择的时间获取请求结果（无需在发送请求后立即等待响应）

工作原理

使用异步模式发送请求和接收响应是一个两步流程：

发送请求 - 请求包含搜索参数，返回 response_ID，并作为直接请求（即该请求将计费）。
收集响应 - 请求包含 response_ID，且不收费（即该请求不会计费）。如果调用仍在处理中的 response_ID，将收到 102 状态码。

我们自请求发送之时起最多存储 48 小时的响应。

开始使用

启用 "异步请求"

在你的 Web Unlocker API 或 SERP API zone 中，进入“高级设置”，启用“异步请求”开关。

[可选] 设置 webhook（POST 或 GET）

你将在此处收到未来请求状态的通知

webhook 也可按单个请求设置（参见下方“初始请求参数”）

发送异步请求

请求语法与同步请求略有不同，需要使用 API key 进行认证。基本示例如下（更多请求参数见下方）：

curl -i --silent --compressed "https://api.brightdata.com/unblocker/req?customer=[ACCOUNT_ID]&zone=[zone_name]" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer [API_KEY]" \
  -d '{"country":"us","query":{"q":"pizza","num":"100","hl":"en","gl":"au"}}'

上述请求返回的响应中包含 x-response-id 头部，该 ID 为此请求的 RESPONSE_ID，将在下一步收集结果时使用。

你可以在脚本中初始化请求时轻松保存 RESPONSE_ID，方法如下：

RESPONSE_ID=$(
	curl -i --silent --compressed "[https://api.brightdata.com/unblocker/req?customer=[ACCOUNT_ID]&zone=[zone_name]](https://api.brightdata.com/unblocker/req?customer=%5BACCOUNT_ID%5D&zone=%5BZONE_NAME%5D)" -H "Content-Type: application/json" -H "Authorization: Bearer API_KEY" -d '{"country":"us","query":{"q":"pizza","num":"100","hl":"en","gl":"au"}}' | sed -En 's/^x-response-id: (.*)/\1/p' | tr -d '\r'
)

Webhook 通知

如果已设置 webhook，当请求准备就绪时你将立即收到通知，参数包括：status、response_id、request_url 和 hook_data（可选 - 如果请求中使用了 webhook_data 参数）。

允许我们的 webhook IP

异步 webhook 通知来自一对稳定 IP，请确保允许这些 IP：

100.27.150.189
18.214.10.85

收集结果

使用步骤 3 获取的 RESPONSE_ID，发送如下请求：

curl -i --silent --compressed "https://api.brightdata.com/unblocker/get_result?customer=[ACCOUNT_ID]&zone=[zone_name]&response_id=${[RESPONSE_ID]}" \
   -H "Authorization: Bearer [API_KEY]"

API - 创建请求 - `POST /{unblocker|serp}/req`

Example

curl -i --silent --compressed "https://api.brightdata.com/unblocker/req?customer=[ACCOUNT_ID]&zone=[zone_name]" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer [API_KEY]" \
  -d '{"url":"https://example.com?foo=bar","country":"us"}'

参数

(*) 必填参数

参数	类型	描述
url (*)	String	请求的 URL
method	String	请求使用的 HTTP 方法
headers	Object	请求使用的头部信息
body	String or Object	请求体。如果为对象，则序列化为 JSON，并将 Content-Type 设置为 application/json
country	String	请求使用的国家（2 位字母代码）
webhook_url	String	接收任务状态通知的 URL。如果不想设置默认 webhook 或希望每个请求 URL 不同，请使用此参数
webhook_method	String	webhook_url 使用的 HTTP 方法（GET 或 POST）
webhook_data	Any	随任务状态通知发送的数据

SERP 特定参数

参数	类型	描述
query (*)	Object
brd_json	1 or “html”	响应格式

SERP Example

curl -i --silent --compressed "https://api.brightdata.com/unblocker/req?customer=[ACCOUNT_ID]&zone=[zone_name]" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer [API_KEY]" \
  -d '{"country":"us","query":{"q":"pizza","num":"100","hl":"en","gl":"au"},"brd_json":"1"}'

API - 收集响应 - `GET /{unblocker|serp}/get_result`

注意：response_id 来源于请求创建响应的 x-response-id 头部

Example

curl -k -v --compressed "https://api.brightdata.com/unblocker/get_result?customer={ACCOUNT_ID&zone={ASYNC_ZONE}&response_id={response_id}" \
  -H "Authorization: Bearer {API_Key}" \
  -o {Your_result_ouput_file}

参数

(*) 必填参数

参数	描述
response_id (*)	任务 ID，在初始异步请求的响应头中获得

单个请求中的多查询

仅 SERP API

异步请求支持在单个 API 请求中使用 multi 参数发送 2 个并行查询请求，而非 query。这些并行请求使用相同的 peer IP 和会话，可用于收集额外数据、对比测试等，例如使用不同参数/值发送一对请求。它们使用相同 IP 和会话。 条件：

仅支持启用异步的 zone（如上所示）
仅支持 Google 搜索
限制为 2 个请求
按 2 个请求计费

参数使用示例：

multi: [
  {"keyword":"pizza","num":20},
  {"keyword":"pizza","num":100}
]

multi: [
  {"keyword":"pizza"},
  {"keyword":"burger"}
]

请求示例：

Sample Request

curl -v --compressed "https://api.brightdata.com/unblocker/req" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {API_KEY}" \
  -d "{\"zone\":\"\$ZONE\",\"country\":\"us\",\"multi\":[{\"keyword\":\"pizza\",\"num\":20},{\"keyword\":\"pizza\",\"num\":100}]}"

介绍

产品指南

异步请求 VS 同步请求

为什么要使用异步请求？

工作原理

开始使用

允许我们的 webhook IP

API - 创建请求 - `POST /{unblocker|serp}/req`

参数

SERP 特定参数

API - 收集响应 - `GET /{unblocker|serp}/get_result`

参数

单个请求中的多查询

​异步请求 VS 同步请求

​为什么要使用异步请求？

​工作原理

​开始使用

​允许我们的 webhook IP

​API - 创建请求 - POST /{unblocker|serp}/req

​参数

​SERP 特定参数

​API - 收集响应 - GET /{unblocker|serp}/get_result

​参数

​单个请求中的多查询

异步请求 VS 同步请求

为什么要使用异步请求？

工作原理

开始使用

允许我们的 webhook IP

API - 创建请求 - `POST /{unblocker|serp}/req`

参数

SERP 特定参数

API - 收集响应 - `GET /{unblocker|serp}/get_result`

参数

单个请求中的多查询