获取 Google 评论已完成任务列表

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

GET https://api.seermartech.cn/v3/merchant/google/reviews/tasks_ready

用于获取已完成但尚未被收取的 Google 评论任务。使用标准任务提交方式且未设置 postback_url 时，可通过本接口获取已完成任务的 id，再调用对应的任务结果接口收取数据。

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

请求路径

获取指定搜索引擎的已完成任务：

http

GET https://api.seermartech.cn/v3/merchant/{se}/tasks_ready

获取 Merchant API 下所有已完成任务：

http

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

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

计费与限制

获取已完成任务列表不产生额外费用。
每个任务在被成功收取前都会保留在列表中。
每分钟最多调用 20 次。
每次调用最多返回过去 3 天完成的 1000 个任务。
已被收取的任务不会再次出现在列表中。
完成后 3 天仍未收取的任务不会出现在列表中。
如果任务提交时设置了 postback_url，任务通常不会出现在本列表中。
当向回调地址发送请求失败，且目标服务器返回的 HTTP 状态码小于 200 或大于 300 时，该任务才可能出现在本列表中。

请求参数

本接口不需要请求参数。

响应结构

接口返回 JSON 数据 tasks 为任务信息数组。

顶层字段

字段	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	请求级状态码，完整错误码请参考 `/v3/appendix/errors`
`status_message`	string	请求级说明信息，完整说明请参考 `/v3/appendix/errors`
`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`，完整错误码请参考 `/v3/appendix/errors`
`status_message`	string	任务状态说明
`time`	string	任务执行耗时，单位为秒
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量
`path`	array	用于收取任务结果的 URL 路径
`data`	object	创建任务时提交到请求 URL 中的参数
`result`	array	已完成任务的详细信息

`result` 数组字段

字段	类型	说明
`id`	string	已完成任务的唯一标识，UUID 格式
`se`	string	创建任务时指定的搜索引擎
`se_type`	string	搜索引擎类型，可取值：`shopping_specifications`
`date_posted`	string	任务提交时间，UTC 格式
`tag`	string	用户自定义任务标识
`endpoint_advanced`	string	用于收取 Google Shopping Product Specifications Advanced 任务结果的 URL
`endpoint_html`	string	用于收取 Google Shopping Product Specifications HTML 任务结果的 URL；本接口不提供 HTML 结果，因此该字段值为 `null`

> 建议在业务系统中针对请求级和任务级状态码分别设计异常处理机制。

请求示例

curl

bash

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

Python

python

import requests

url = "https://api.seermartech.cn/v3/merchant/google/reviews/tasks_ready"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

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

if response_data.get("status_code") == 20000:
    print(response_data)
    # 在此处理已完成任务列表
else:
    print(
        "请求失败，状态码：{}，说明：{}".format(
            response_data.get("status_code"),
            response_data.get("status_message"),
        )
    )

TypeScript

typescript

import axios from "axios";

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

    const result = response.data;

    if (result.status_code === 20000) {
      console.log(result);
      // 在此处理已完成任务列表
    } else {
      console.error(
        `请求失败，状态码：${result.status_code}，说明：${result.status_message}`
      );
    }
  } catch (error) {
    console.error("网络请求失败：", error);
  }
}

getGoogleReviewsTasksReady();

响应示例

json

{
  "version": "0.1.20231117",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1399 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": " найти-task-uuid",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1200 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "merchant",
        "google",
        "reviews"
      ],
      "data": {
        "se_type": "reviews",
        "api": "merchant",
        "function": "reviews",
        "se": "google"
      },
      "result": [
        {
          "id": "найти-task-uuid",
          "se": "google",
          "se_type": "reviews",
          "date_posted": "2024-01-15 10:30:00 +00:00",
          "tag": "reviews_batch_001",
          "endpoint_advanced": "/v3/merchant/google/reviews/task_get/найти-task-uuid",
          "endpoint_html": null
        }
      ]
    }
  ]
}

> 实响应中的任务 ID 为 UUID 字符串。上例中的占位值用于展示字段结构。

实用场景

轮询已完成任务：定时获取尚未收取的 Google 评论任务 ID，适用于未回调地址的批量采集流程。
补偿回调失败任务：定期检查因目标服务器异常而重新任务队列的任务，降低评论数据遗漏风险。
构建任务状态看板：统计收取任务数量、错误任务数量和任务完成时间，帮助运营人员监控采集链路。
批量收取历史评论数据：获取任务结果地址后批量调用任务结果接口，为门店评价分析和竞品口碑研究提供数据。
控制高频采集流程：结合每分钟 20 次的调用限制设计轮询间隔，因请求过于频繁导致任务收取失败。

获取 Google 评论已完成任务列表 ​

请求路径 ​

计费与限制 ​

请求参数 ​

响应结构 ​

顶层字段 ​

tasks 数组字段 ​

result 数组字段 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应示例 ​

实用场景 ​