获取 Google 商家更新已完成任务

GET /v3/business_data/google/my_business_updates/tasks_ready

本接口使用 GET 方法，请求路径为：

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

本接口用于获取已经完成但尚未被收取的 Google 商家更新任务列表。未使用 postback_url 时，可以通过本接口获取所有已完成任务的 id，再调用对应的任务结果接口获取详细结果。

如果系统了 postback_url，任务通常不会出现在本接口的结果列表中。只有当本平台向您的服务器发送回调失败，且服务器返回的 HTTP 状态码小于 200 或大于 300 时，该任务才可能重新出现在已完成任务列表中。

> 注意：已完成任务队列存在少量更新延迟。若系统每分钟需要收集 1000 个任务，建议优使用回调机制；本接口可用于补偿收集回调失败的任务。

请求地址

获取 Google 商家更新任务：

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

通用搜索引擎任务路径：

GET https://api.seermartech.cn/v3/business_data/$se/tasks_ready

$se 为搜索引擎名称，例如 google。

获取所有 Business Data API 已完成任务：

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

原始文档中还以下容路径：

/v3/business_data/wp/my_business_updates/tasks_ready

该路径不作为本平台调用路径，请使用上方的 Google 专用路径。

认证方式

请求头使用 Bearer Token：

Authorization: Bearer smt_live_YOUR_KEY

计费与调用限制

• 获取已完成任务列表不产生费用。
• 每个任务在被成功收取前会持续保留在列表中。
• 每分钟最多调用 20 次。
• 每次调用最多返回过去 3 天完成的 1000 个任务。
• 已经收取过的任务不会再次返回。
• 完成 3 天仍未收取的任务不会继续保留在列表中。
• 本接口不返回已通过 postback_url 成功推送的任务。
• 本接口本身不计费；如接口产生费用，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

响应说明

接口返回 JSON 数据 tasks 数组。

顶层字段

字段	类型	说明
version	string	当前 API 版本
status_code	integer	请求级状态码，完整错误码请参考 /v3/appendix/errors
status_message	string	请求级状态信息
time	string	请求执行耗时，单位为秒
cost	float	平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	tasks 数组中返回错误的任务数量
tasks	array	已完成任务列表

tasks 数组字段

字段	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，通常位于 10000 至 60000 范围
status_message	string	任务状态信息
time	string	任务处理耗时，单位为秒
cost	float	平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_count	integer	result 数组中的数量
path	array	任务请求路径
data	object	创建任务时提交的请求参数
result	array	已完成任务的摘要信息

result 数组字段

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

如需根据任务 ID 获取完整结果，请调用响应中 endpoint 指定的任务结果接口。

请求示例

cURL

curl --location \
  --request GET "https://api.seermartech.cn/v3/business_data/google/my_business_updates/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/my_business_updates/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:
    for task in data.get("tasks", []):
        print("已完成任务 ID：", task.get("id"))
        print("任务状态：", task.get("status_message"))
else:
    print(
        "请求失败，状态码：",
        data.get("status_code"),
        "信息：",
        data.get("status_message"),
    )

TypeScript

import axios from "axios";

async function getReadyTasks(): Promise<void> {
  const response = await axios.get(
    "https://api.seermartech.cn/v3/business_data/google/my_business_updates/tasks_ready",
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  );

  const data = response.data;

  if (data.status_code === 20000) {
    for (const task of data.tasks ?? []) {
      console.log("已完成任务 ID：", task.id);
      console.log("任务状态：", task.status_message);
    }
  } else {
    console.error(
      `请求失败，状态码：${data.status_code}，信息：${data.status_message}`
    );
  }
}

getReadyTasks().catch((error) => {
  console.error("网络或接口调用失败：", error.message);
});

响应示例

{
  "version": "0.1.20200909",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1237 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": " task-uuid ",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0450 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "business_data",
        "google",
        "my_business_updates",
        "tasks_ready"
      ],
      "data": {
        "se_type": "business_updates",
        "se": "google",
        "api": "business_data",
        "function": "my_business_updates"
      },
      "result": [
        {
          "id": " task-uuid ",
          "se": "google",
          "se_type": "business_updates",
          "date_posted": "2024-01-15 10:30:00 +00:00",
          "tag": "monthly-location-update",
          "endpoint": "/v3/business_data/google/my_business_updates/task_get"
        }
      ]
    }
  ]
}

错误处理

请根据以下字段判断请求和任务是否成功：

• 顶层 status_code：表示本次列表请求的处理结果。
• tasks_error：表示返回列表中错误的任务数量。
• 任务级 status_code：表示单个任务的处理结果。
• status_message：提供对应的状态说明。

完整状态码和错误信息请参考：

/v3/appendix/errors

建议在业务系统中实现以下处理逻辑：

1. 检查 HTTP 响应状态。
2. 检查顶层 status_code 是否为 20000。
3. 遍历 tasks 数组并检查每个任务的 status_code。
4. 根据 endpoint 收取任务详细结果。
5. 对暂时失败或回调失败的任务执行重试和记录。

实用场景

• 轮询收取已完成的 Google 商家更新任务：在未回调地址时批量获取任务 ID，逐个查询任务状态。
• 补偿回调失败的任务：定期检查已完成任务列表，找出未成功推送到业务服务器的任务，降低数据遗漏风险。
• 构建任务收集队列：将 tasks 中的任务 ID 和 endpoint 写消息队列，异步获取详细结果并提升处理吞吐量。
• 监控任务处理异常：根据 tasks_error、任务级 status_code 和 status_message 统计失败任务，及时定位数据采集问题。
• 按自定义标签同步业务数据：结合 tag 和 date_posted 筛选任务，将商家更新结果到门店、区域或同步批次。