انتقل إلى المحتوى
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 وGET /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