Правила качества

GET /api/v1/quality/rules

Возвращает правила доступных сайтов и общие правила платформы.

Доступ

Bearer API-ключ активного пространства и право runs.read. Для записи нужны ключ с записью и sites.write на выбранном сайте. Общие определения изменяет только оператор платформы с settings.manage, не внешний ключ. Сайты и история ограничены текущей командой. На агенте POST/PATCH/DELETE запрещены: определения меняются в облаке.

Параметры

Тело не требуется. locale=ru|en выбирает язык подписей и пояснений; без явного параметра используется cookie akmelo_locale, затем русский. Код вида и имена полей не переводятся.

Ответ 200

Пример сокращён. Числовые ID условны; полные поля описаны ниже и в скачиваемой схеме OpenAPI.

{
  "data": [
    {
      "id": 1,
      "name": "Падение числа товаров",
      "kind": "row_count_drop",
      "params": {
        "drop_percent": 30,
        "min_previous": 100
      },
      "action": "warn",
      "is_active": true,
      "site": {
        "id": 1,
        "code": "parts"
      },
      "preset_id": "catalog-drop",
      "last_check": null,
      "created_at": "2026-10-21T12:00:00+00:00",
      "updated_at": "2026-10-21T12:00:00+00:00"
    }
  ],
  "kinds": [],
  "actions": []
}

last_check.status: passed означает выполнение условий, breached нарушение, skipped невозможность сделать вывод. last_check=null не означает успех. Исторический снимок details.params может отличаться от текущего params после редактирования. Для общих правил последняя проверка выбирается только среди доступных пользователю сайтов. Нельзя показывать результат чужой команды как результат общего правила.

Поведение и ограничения

Общие правила видны, но менять их внешним ключом нельзя. last_check ограничен доступными сайтами даже у общего правила. null означает, что записанного результата ещё нет. Фильтра site_id у этого метода нет.

Правила действуют на следующие успешные полные сборы. Они не меняют старые данные и не исправляют сценарий. Проверки полей используют до 5 000 записей текущего сбора, с явной отметкой ограниченной выборки; пустые значения кроме проверки заполненности пропускаются. passed, breached, skipped различаются, а отсутствие находки не доказывает успех.

Числовые примеры сохраняют прежний контракт v1. Для публичных UUID используйте X-Identifier-Format: uuid либо тот же метод /api/v2. Это относится и к вложенным ссылкам на сайты, правила и сборы; preset_id, category_id и field остаются строковыми кодами. Форматы идентификаторов.

Если budget_truncated=true, результат пропущен с частичными измерениями. Превышение общего бюджета не считается успешно выполненной проверкой.

Покрытие и пропущенные проверки

До json_decode проверяются сложность и глубина JSON: общий предел 200000узлов и 16 МиБ оценённой распакованной структуры, не больше 4 МиБ на строку и 24уровней. Строковые скобки не считаются узлами. Дополнительно перед PDO-порцией и распаковкой проверяется свободная память PHP с резервом 8 МиБ. Новые причины пропуска: sample_structure_exceeded, sample_depth_exceeded, sample_decode_error, sample_memory_exceeded. Даже если первая строка слишком сложная, это пропуск по пределу, а не no_records. Все измерения до остановки частичные.

Проверяются только успешные полные обычные сборы. Пробные, частичные, неуспешные и отменённые сборы не проверяются. Продолжение или повтор прерванного сбора имеет skipped / continued_run. Сравнение объёма требует более раннего успешного полного сбора того же сайта и сценария, не помеченного для проверки; без него будет no_baseline, при слишком малом прошлом объёме baseline_too_small.

Счётчики объёма относятся ко всему сбору. Поля проверяются по первым 5000 действующим записям текущего сбора, по внутреннему ID. Это ограниченная выборка, не случайная оценка всего каталога. Общий предел: 32 различных поля, 100000 ячеек и 8 МиБ сырых данных; отдельное значение свыше 8 КиБ не читается в память. sample_limited, sample_size, sample_limit, budget_truncated, budget_bytes, byte_limit, cell_limit, field_limit, oversized_skipped раскрывают покрытие. При достижении общего бюджета результат skipped, причина sample_budget_exceeded, частичное измерение в observed_status не является итоговым успехом или находкой. Поля сверх лимита получают field_budget_exceeded.

Пустыми считаются null, пустая строка, строка только из пробельных символов Unicode и пустой массив. 0 и false заполнены. Только field_fill_rate считает пустоту нарушением. Другие виды исключают её из знаменателя и при отсутствии заполненных значений возвращают no_filled_values. Иные причины пропуска: no_records, field_missing, values_too_large, too_few_records, unsupported_kind, check_error. Ошибка проверки не превращает уже сохранённый успешный сбор в неуспешный.

Доли нарушают правило строго выше допуска: ровно 7 из 100 при допуске 7% проходят. Падение и рост объёма включают порог: 100 → 90 при пороге 10% вызывает находку. Сравнения точные, округляется только показанный процент. Свежесть измеряется относительно run.finished_at; дата без часового пояса считается UTC.

Подробные примеры всех 24 шаблонов и работа с интерфейсом: Качество данных. Схема параметров: справочник.

Как отправить запрос

В серверном окружении задайте BASE (адрес установки без завершающего слеша) и API_KEY. Секрет не вставляется в исходник. Подготовка клиентов и браузерный JavaScript.

curl

curl --fail-with-body -X GET "$BASE/api/v1/quality/rules?locale=ru" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json"

Node.js · сервер

// Node.js, сервер. Сохраните как request.mjs.
const response = await fetch(process.env.BASE + "/api/v1/quality/rules?locale=ru", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    Accept: "application/json"
  },
  signal: AbortSignal.timeout(120000)
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
console.log(await response.json());

Python

import json
import os
import urllib.request
import urllib.error

request = urllib.request.Request(
    os.environ["BASE"] + "/api/v1/quality/rules?locale=ru",
    method="GET",
    headers={"Authorization": "Bearer " + os.environ["API_KEY"],
             "Accept": "application/json"},
)
try:
    with urllib.request.urlopen(request, timeout=120) as response:
        print(json.load(response))
except urllib.error.HTTPError as error:
    print(error.code, error.read().decode("utf-8", errors="replace"))
    raise

PHP · внешний клиент

<?php
$handle = curl_init(getenv("BASE") . "/api/v1/quality/rules?locale=ru");
curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 120,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("API_KEY"),
        "Accept: application/json",
    ],
]);
$content = curl_exec($handle);
$status = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
if ($content === false) {
    throw new RuntimeException(curl_error($handle));
}
curl_close($handle);
if ($status < 200 || $status >= 300) {
    throw new RuntimeException("HTTP $status: $content");
}
print_r(json_decode($content, true, 512, JSON_THROW_ON_ERROR));

Go

package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
    "time"
)

func main() {
    request, err := http.NewRequest("GET", os.Getenv("BASE") + "/api/v1/quality/rules?locale=ru", nil)
    if err != nil { panic(err) }
    request.Header.Set("Authorization", "Bearer " + os.Getenv("API_KEY"))
    request.Header.Set("Accept", "application/json")
    client := &http.Client{Timeout: 120 * time.Second}
    response, err := client.Do(request)
    if err != nil { panic(err) }
    defer response.Body.Close()
    content, err := io.ReadAll(response.Body)
    if err != nil { panic(err) }
    if response.StatusCode < 200 || response.StatusCode >= 300 {
        panic(fmt.Sprintf("HTTP %d: %s", response.StatusCode, content))
    }
    fmt.Println(string(content))
}

Если запрос не выполнен

401: проверьте ключ и срок. 403: права, режим чтения/записи и 2FA. 404: идентификатор и пространство. 422: поля запроса или состояние объекта. 429: подождите Retry-After. Подробно об ошибках и повторах.