获取 Google Extended Reviews 已完成任务列表

接口说明

Tasks Ready 接口用于返回已执行完成、但尚未被获取结果的任务列表。

如果你没有 postback_url，可以通过本接口获取所有已完成任务的 id，再使用对应的 Task GET 接口拉取任务结果。

接口地址：

GET https://api.seermartech.cn/v3/business_data/google/extended_reviews/tasks_ready

容路径说明：

• 获取指定搜索引擎的已完成任务列表：GET /v3/business_data/$se/tasks_ready
• 获取 Business Data API部已完成任务列表：GET /v3/business_data/tasks_ready

，$se 需替换为搜索引擎名称。

使用说明

由于平台架构特性，已完成任务队列的更新会有轻微延迟。对于高并发场景，如果你的系统需要每分钟拉取 1000 个任务，建议优使用 pingback / postback 机制；Tasks Ready 更适合用于补偿拉取，例如获取 postback 投递失败的任务 ID。

注意事项：

• 每个任务在被成功拉取前，会一直保留在列表中
• 每分钟最多可调用 20 次
• 每次调用最多返回 过去 3 天完成的 1000 个任务
• 列表中不会：
• 已经被拉取过结果的任务
• 完成后 3 天未拉取 的任务
• 如果任务设置了 postback_url，通常不会出现在已完成任务列表中
• 只有当回调请求发送失败，或你的服务端返回的 HTTP 状态码小于 200 或大于 300 时，该任务才可能出现在列表中

计费说明

获取已完成任务列表不额外收费。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

响应结构

接口返回 JSON 数据，顶层 tasks 数组本次返回的任务信息。

顶层字段

字段	类型	说明
version	string	当前 API 版本
status_code	integer	接口整体状态码，可参考 /v3/appendix/errors
status_message	string	接口整体状态信息，可参考 /v3/appendix/errors
time	string	执行耗时，单位秒
cost	float	本次请求总费用，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	tasks 数组中返回错误的任务数量
tasks	array	任务数组

tasks[] 字段

字段	类型	说明
id	string	本平台任务 ID，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000，可参考 /v3/appendix/errors
status_message	string	任务状态说明
time	string	任务执行耗时，单位秒
cost	float	单任务费用，单位 USD
result_count	integer	result 数组中的数量
path	array	URL 路径
data	object	请求 URL 中传的参数
result	array	结果数组

tasks[].result[] 字段

字段	类型	说明
id	string	已完成任务的任务 ID，UUID 格式
se	string	创建任务时指定的搜索引擎；当前为 google
se_type	string	搜索引擎类型
date_posted	string	任务提交时间，UTC 格式
tag	string	自定义任务标识
endpoint	string	用于拉取该任务结果的接口地址

请求示例

cURL

curl --location --request GET "https://api.seermartech.cn/v3/business_data/google/extended_reviews/tasks_ready" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json"

Python

import requests

url = "https://api.seermartech.cn/v3/business_data/google/extended_reviews/tasks_ready"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json)

TypeScript

import axios from "axios";

axios({
 method: "get",
 url: "https://api.seermartech.cn/v3/business_data/google/extended_reviews/tasks_ready",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
})
 .then((response) => {
 // 输出返回结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例

{
 "version": "0.1.20241028",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1096 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "se_type": "extended_reviews",
 "se": "google",
 "api": "business_data",
 "function": "extended_reviews"
 },
 "result": []
 }
 ]
}

状态码与错误处理

请重点处理以下两类状态信息：

• 顶层 status_code / status_message：表示整个请求是否成功
• tasks[].status_code / tasks[].status_message：表示单个任务是否成功返回

建议在业务系统中实现完善的异常处理逻辑，：

• 接口调用频率限
• 任务尚未完成队列
• 单个任务结果拉取失败
• 回调失败后的补偿拉取场景

完整错误码可参考：/v3/appendix/errors

结果拉取流程建议

型流程如下：

1. 提交 Extended Reviews 采集任务
2. 通过 postback_url 接收异步完成通知，或定期调用 tasks_ready
3. 获取已完成任务的 id
4. 使用返回的 endpoint 或对应 Task GET 接口拉取最终结果
5. 对已获取结果做去重、库和失败补偿

实用场景

• 补偿拉取回调失败任务：当 postback_url 投递失败时，使用本接口找回遗漏任务 ID，评论数据丢失。
• 批量轮询已完成采集任务：定时获取过去 3 天已完成的 Google Extended Reviews 任务，提高任务处理自动化程度。
• 串联异步采集与库流程：拿到完成任务列表，再逐个调用结果接口，将评论数据写数据库或数据仓库。
• 监控任务完成与消费状态：识别哪些任务已完成但尚未被结果处理，帮助优化采集管道稳定性。
• 构建失败恢复机制：在高并发采集场景下，将本接口作为回调机制的底方案，提升任务结果交付成功率。