获取 Google 商家问答已完成任务列表

接口说明

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

如果你没有 postback_url，可以通过本接口获取所有已完成任务的 id，然后再调用 Task GET 接口逐个获取结果。

注意： 由于平台 API 的任务队列存在短暂刷新延迟，高并发场景下可能无法实时返回最新完成任务。 如果你的系统需要每分钟拉取 1000 个任务，建议优使用 pingback/postback 机制；Tasks Ready 更适合用于补偿获取那些回调失败的任务 ID。

---

请求地址

获取 Google 商家问答已完成任务列表：

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

你也可以使用通用路径：

• 按搜索引擎获取已完成任务： GET https://api.seermartech.cn/v3/business_data/$se/tasks_ready
• 获取 Business Data API部已完成任务： GET https://api.seermartech.cn/v3/business_data/tasks_ready

---

计费与限制

• 获取已完成任务列表不收费
• 每次请求最多返回过去 3 天完成的 1000 个任务
• 已经被拉取过结果的任务，不会继续出现在列表中
• 完成后 3 天未拉取 的任务，也不会再出现在列表中
• 最多支持 20 次请求/分钟

如果任务在创建时设置了 postback_url，通常不会出现在已完成任务列表中。只有当回调请求失败时，该任务才可能重新出现在列表里，例如：

• 你的服务端返回的 HTTP 状态码 小于 200
• 或返回的 HTTP 状态码 大于 300

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

---

请求方式

GET /v3/business_data/google/questions_and_answers/tasks_ready

请求头

请求头	类型	填	说明
Authorization	string	是	认证方式：Bearer smt_live_YOUR_KEY
Content-Type	string	否	建议使用 application/json

说明：本接口为 GET 请求，无需请求体。

---

响应结构

接口返回 JSON 对象，核心在 tasks 数组中。

顶层字段

字段	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码，完整列表见 /v3/appendix/errors
status_message	string	通用状态信息，完整列表见 /v3/appendix/errors
time	string	接口执行时间，单位秒
cost	float	本次请求总成本，USD；本接口通常为 0
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	tasks 数组中返回错误的任务数量
tasks	array	任务数组

tasks[] 字段

字段	类型	说明
id	string	当前请求任务 ID，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000
status_message	string	任务状态信息
time	string	任务执行时间，单位秒
cost	float	当前任务成本，USD
result_count	integer	result 数组数量
path	array	请求路径
data	object	当前 URL 中传的参数信息
result	array	已完成任务列表

tasks[].result[] 字段

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

---

调用流程建议

1. 调用 /v3/business_data/google/questions_and_answers/tasks_ready
2. 从返回结果的 result[] 中取出每个任务的 id 或 endpoint
3. 调用对应的 Task GET 接口获取详细结果，例如：

• /v3/business_data/google/questions_and_answers/task_get/{id}

---

请求示例

cURL

curl --location --request GET "https://api.seermartech.cn/v3/business_data/google/questions_and_answers/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/questions_and_answers/tasks_ready"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

# 获取已完成但尚未获取结果的任务列表
response = requests.get(url, headers=headers)
data = response.json

if data.get("status_code") == 20000:
 print(data)
else:
 print(f"error. Code: {data.get('status_code')} Message: {data.get('status_message')}")

TypeScript

const url = 'https://api.seermartech.cn/v3/business_data/google/questions_and_answers/tasks_ready';

async function getTasksReady {
 const response = await fetch(url, {
 method: 'GET',
 headers: {
 'Authorization': 'Bearer smt_live_YOUR_KEY',
 'Content-Type': 'application/json'
 }
 });

 const data = await response.json;

 if (data.status_code === 20000) {
 console.log(data);
 } else {
 console.error(`error. Code: ${data.status_code} Message: ${data.status_message}`);
 }
}

getTasksReady;

---

响应示例

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

说明：上方示例展示文档中提供的响应结构片段。返回中通常还会任务级别的 id、status_code、status_message、time、cost、result_count、path 等字段。

---

状态码说明

状态码	说明
20000	请求成功
10000-60000	任务级状态码范围，含义见 /v3/appendix/errors

建议在接时对通用错误、任务级错误、空结果、时重试等做完整处理。

---

结果拉取示例

如果 tasks_ready 返回如下任务结果项：

{
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "se_type": "questions_and_answers",
 "se": "google",
 "date_posted": "2024-04-22 10:00:00 +00:00",
 "tag": "store_001",
 "endpoint": "/v3/business_data/google/questions_and_answers/task_get/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

则你可以继续请求：

curl --location --request GET "https://api.seermartech.cn/v3/business_data/google/questions_and_answers/task_get/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json"

---

使用注意事项

• 本接口只返回已完成且未被拉取的任务
• 使用 postback_url 的任务，默认不会该列表
• 当回调失败时，任务才可能出现在返回列表中
• 建议将本接口作为补偿拉取机制，而不是高吞吐主通道
• 对于批量任务系统，建议保存任务 id、tag 与业务侧主键的映射，便于后续补拉和对账

实用场景

• 补拉失败回调任务：当商家问答任务的 postback 回调失败时，定时调用本接口找回遗漏任务，结果丢失。
• 轮询获取异步任务结果：未启用回调机制时，通过本接口获取已完成任务 ID，再批量调用 task_get 拉取。
• 构建任务补偿队列：将返回的 id 或 endpoint 写重试队列，提升大规模异步采集链路的稳定性。
• 核对近 3 天任务完成：定期扫描最近完成但尚未领取的任务，出保留期后无法获取结果。
• 按业务标签追踪结果回收：结合 tag 字段识别门店、区域或项目维度任务，提升本地 SEO 数据回收与对账效率。