跳至内容
ShopentlyLearn

获取列表 · 搜索查询 — 搜索分析与规则

读取“搜索分析与规则”的数据。结果取决于此操作的参数。

GET/api/v1/search/queries

身份验证
Bearer
最低套餐
STANDARD
所需权限
search.analytics:read

代码示例

请求示例

cURL

: "${SHOPENTLY_SHOP_URL:?}"

curl --disable --globoff --fail-with-body --silent --show-error \
  --proto '=https' --connect-timeout 5 --max-time 30 \
  --request GET \
  --header "Authorization: Bearer ${SHOPENTLY_ACCESS_TOKEN:?}" \
  --url "${SHOPENTLY_SHOP_URL%/}"'/api/v1/search/queries?limit=20'

PHP

<?php
declare(strict_types=1);

$baseUrl = rtrim(getenv('SHOPENTLY_SHOP_URL') ?: '', '/');
$origin = parse_url($baseUrl);
if (!$origin || ($origin['scheme'] ?? '') !== 'https' || empty($origin['host']) ||
    isset($origin['user'], $origin['pass']) || isset($origin['user']) || isset($origin['path']) ||
    isset($origin['query']) || isset($origin['fragment'])) {
    throw new RuntimeException('SHOPENTLY_SHOP_URL must be an HTTPS origin');
}
$credential = getenv('SHOPENTLY_ACCESS_TOKEN') ?: '';
if ($credential === '' || strpbrk($credential, "\r\n") !== false) {
    throw new RuntimeException('Invalid credential');
}
$headers = [];
$headers[] = 'Authorization: Bearer ' . $credential;
$responseHeaders = [];
$handle = curl_init($baseUrl . '/api/v1/search/queries?limit=20');
curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_PROTOCOLS => CURLPROTO_HTTPS,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_SSL_VERIFYHOST => 2,
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HEADERFUNCTION => static function ($handle, string $line) use (&$responseHeaders): int {
        if (str_contains($line, ':')) {
            [$name, $value] = explode(':', $line, 2);
            $responseHeaders[strtolower(trim($name))] = trim($value);
        }
        return strlen($line);
    },
]);
$raw = curl_exec($handle);
$status = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
$error = curl_error($handle);
curl_close($handle);
if ($raw === false) {
    throw new RuntimeException('Transport error: ' . $error);
}
if ($status < 200 || $status >= 300) {
    throw new RuntimeException('HTTP ' . $status . '; request_id=' .
        ($responseHeaders['x-request-id'] ?? '') . '; retry_after=' . ($responseHeaders['retry-after'] ?? ''));
}
$result = $raw === '' ? null : json_decode($raw, true, 512, JSON_THROW_ON_ERROR | JSON_BIGINT_AS_STRING);
echo json_encode($result, JSON_THROW_ON_ERROR | JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE), PHP_EOL;

Python

from contextlib import ExitStack
import json
import os
from urllib.parse import urlsplit

import requests  # python -m pip install requests

base_url = os.environ["SHOPENTLY_SHOP_URL"].rstrip("/")
origin = urlsplit(base_url)
if origin.scheme != "https" or not origin.hostname or origin.username or origin.password or origin.path or origin.query or origin.fragment:
    raise ValueError("SHOPENTLY_SHOP_URL must be an HTTPS origin")
credential = os.environ['SHOPENTLY_ACCESS_TOKEN']
if not credential or "\r" in credential or "\n" in credential:
    raise ValueError("Invalid credential")
headers = {}
headers["Authorization"] = 'Bearer' + " " + credential
body = None
if body is not None:
    headers["Content-Type"] = "application/json"

with ExitStack() as stack:
    session = stack.enter_context(requests.Session())
    files = None
    if False:
        image = stack.enter_context(open(os.environ["SHOPENTLY_IMAGE_FILE"], "rb"))
        if os.fstat(image.fileno()).st_size > 5242880:
            raise ValueError("Image exceeds 5 MiB")
        files = {"file": ("article.png", image, "image/png")}
    response = session.request(
        'GET', base_url + '/api/v1/search/queries?limit=20', headers=headers,
        data=body.encode("utf-8") if body is not None else None, files=files,
        timeout=(5, 30), allow_redirects=False,
    )
    if not 200 <= response.status_code < 300:
        raise RuntimeError(f"HTTP {response.status_code}; request_id={response.headers.get('X-Request-ID', '')}; retry_after={response.headers.get('Retry-After', '')}")
    if False:
        if response.headers.get("Content-Type") != "image/webp" or len(response.content) > 5242880:
            raise ValueError("Unexpected image response")
        with open(os.environ["SHOPENTLY_OUTPUT_FILE"], "xb") as output:
            output.write(response.content)
    else:
        result = response.json() if response.content else None
        print(json.dumps(result, ensure_ascii=False, indent=2))

响应示例 200

JSON
{
  "data": [
    {
      "clicks": 1,
      "last_seen_at": "2026-01-01T12:00:00Z",
      "query_display": "example",
      "query_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "searches": 1,
      "zero_results": 1
    }
  ],
  "meta": {
    "pagination": {
      "has_more": false,
      "limit": 20,
      "next_cursor": null
    },
    "period": {
      "as_of": "2026-01-02T00:00:00Z",
      "days": 1,
      "started_at": "2026-01-01T00:00:00Z"
    },
    "request_id": "example"
  }
}

工作原理

  • GET /api/v1/search/overview 和 /api/v1/search/queries 提供汇总统计与分组查询。
  • 使用查询的 query_hash 获取其发生记录。
  • 报告期支持 7、30 或 90 天,各端点列出可用筛选条件。
  • 搜索规则将短语与所选产品和分类关联,支持创建、读取、更新和删除。
  • 规则与分析具有独立权限;读取搜索统计不会授予配置权限。

参数

查询参数

limit整数可选

此页记录数上限。

minimum: 1maximum: 100
默认值: 50示例: 20
cursor字符串 null可选

上一页返回的不透明续页值。

字符串:minLength: 1maxLength: 1024
days整数可选

报告期天数。

约束
enum
[7, 30, 90]
默认值: 30
locale字符串 null可选

本次请求选择的语言。

字符串:minLength: 2maxLength: 20
约束 · 字符串 1
pattern
"^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"
source字符串 null可选

记录活动的来源。

约束 · 字符串 1
enum
["results", "autocomplete"]
market_id字符串 null可选

上下文端点返回的市场标识符。

约束 · 字符串 1
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
query字符串可选

搜索文本或搜索文本筛选条件。

maxLength: 255
默认值: ""
searches_min整数 null可选

最小搜索次数筛选。

整数:minimum: 0maximum: 9223372036854775807
searches_max整数 null可选

最大搜索次数筛选。

整数:minimum: 0maximum: 9223372036854775807
clicks_min整数 null可选

最小点击次数筛选。

整数:minimum: 0maximum: 9223372036854775807
clicks_max整数 null可选

最大点击次数筛选。

整数:minimum: 0maximum: 9223372036854775807
zero_results_min整数 null可选

最小无结果搜索次数筛选。

整数:minimum: 0maximum: 9223372036854775807
zero_results_max整数 null可选

最大无结果搜索次数筛选。

整数:minimum: 0maximum: 9223372036854775807
zero_result_scopeZeroResultScope 可选

按是否存在零结果记录筛选搜索。

默认值: "all"
sortQueryMetricSort 可选

为结果选择的排序方式。

默认值: "last_seen_desc"

此操作不接受 JSON 请求体。

响应

响应 200

data数组 <MetricData > 必填

成功响应的数据。

字段 · data

MetricData

clicks整数必填

点击次数。

last_seen_at字符串必填

最近一次出现的时间。

format: "date-time"
query_display字符串必填

向管理员显示的搜索短语。

query_hash字符串必填

分组搜索短语的稳定标识符。

searches整数必填

搜索次数。

zero_results整数必填

无结果搜索次数。

metaAnalyticsPageMeta AnalyticsMeta 必填

响应元数据。

字段 · meta

AnalyticsPageMeta

paginationPagination 必填

游标分页元数据。

periodAnalyticsPeriodData 必填

报告期及其边界。

request_id字符串必填

申请标识符;在响应元数据中表示 HTTP 请求标识符。

minLength: 1maxLength: 100

AnalyticsMeta

periodAnalyticsPeriodData 必填

报告期及其边界。

request_id字符串必填

申请标识符;在响应元数据中表示 HTTP 请求标识符。

minLength: 1maxLength: 100
响应示例

HTTP 状态

200
请求成功 架构
400
无效请求
401
需要身份验证
403
权限不足
404
未找到资源
409
版本冲突
422
验证失败
429
超出请求限制
其他 HTTP 状态 (7)
405
不允许的方法
413
请求过大
415
不支持的格式
500
服务器错误
502
API 网关错误
503
服务不可用
504
网关超时

错误目录: ErrorResponse

请求头与响应头

401

WWW-Authenticate字符串可选

服务器要求的身份验证方案。

405

Allow字符串可选

此资源支持的 HTTP 方法。

429, 503

Retry-After整数可选

重试前最少等待的秒数。

minimum: 0