ProveRank

Как создать пользовательский API-воркфлоу для многоязычных SEO-аудитов

Техническое руководство по созданию автоматизированных API-пайплайнов, которые проверяют теги hreflang, анализируют данные SERP для конкретных локалей и масштабируются на многоязычные сайты.

Автор
АвторBlogTend
Опубликовано
Время чтения
9 мин · 1 928 слов
Как создать пользовательский API-воркфлоу для многоязычных SEO-аудитов
На этой странице · 6 разделов

Пользовательский рабочий процесс API для многоязычных SEO-аудитов объединяет API поисковых систем, конечные точки сканирования и данные локализации в автоматизированный конвейер. Эта система проверяет теги hreflang, анализирует канонизацию по локалям и агрегирует данные о производительности по странам и языкам. В руководстве подробно описано, как спроектировать и написать этот конвейер — от аутентификации до вывода данных на дашборд.

Почему многоязычный SEO-аудит не работает без автоматизации

Ручной аудит крупных многоязычных сайтов не справляется с масштабом. Взаимность hreflang требует, чтобы каждая альтернативная страница ссылалась обратно на все остальные альтернативные страницы.

Руководство Google по локализованным версиям различает страницы, основной контент которых остается непереведенным, и переведенные локализованные версии.

Данные о производительности, отфильтрованные только по URL, упускают географические и лингвистические аспекты, определяющие реальную видимость.

Ручной аудит против автоматизации на основе API
ФакторРучной аудитПользовательский рабочий процесс API
Проверка взаимности hreflangЧасы на пару локалей; подвержено ошибкам при масштабированииМинуты для всех локалей; программная верификация
Данные о производительности по стране/языкуТребует ручной фильтрации и агрегации в таблицахАвтоматическое извлечение через Search Console API с фильтрами по измерениям
Обнаружение новых или удаленных страниц локалейРеактивный подход, во время запланированных аудитовНепрерывный мониторинг через запланированный опрос API
Выявление конфликтов канонических URLПоштучная проверка страницМассовое сканирование с флажками на основе правил
Предел масштабируемостиОграничен пропускной способностью человекаОграничен квотами API

Сравнить тарифы

Необходимые API для сбора данных международного SEO

Три категории API составляют основу конвейера многоязычного аудита: API поисковой эффективности, API сканирования и API управления локализацией.

Google Search Console API

Для многоязычных аудитов критически важна фильтрация по измерениям. Метод searchanalytics.query() принимает параметр dimensions, включающий country и query, что позволяет изолировать эффективность для конкретной локали. В документации Google по Search Analytics указано, что результаты, превышающие 25 000 строк, должны быть получены пакетами путем увеличения начальной строки для последующих запросов.

Google рекомендует выполнять запрос каждый день за один день данных, чтобы не превышать дневные квоты.

API сканирования и извлечения

Проверьте документацию каждого поставщика услуг сканирования, чтобы узнать, поддерживает ли он параметры локали в одной задаче или требует отдельные задачи для каждого языка. Независимого сравнения точности извлечения hreflang между поставщиками, не зависящего от вендора, не было доступно в исследованиях для этой статьи.

Для проверки с открытым исходным кодом инструмент CrawlCove hreflang checker предоставляет CLI-утилиту, которая проверяет теги head HTML, HTTP-заголовки Link и XML-карты сайта на наличие самоссылок, x-default, обратных тегов, noindex и конфликтов канонических URL. Он лицензирован под MIT, хотя статус долгосрочной поддержки и готовность к использованию в продакшене не были установлены в доступных исследованиях.

API управления локализацией

Платформы управления переводом предоставляют API, которые сопоставляют коды локалей с шаблонами URL, отмечают устаревшие переводы и идентифицируют страницы, поставленные в очередь на локализацию.

Проектирование пользовательского рабочего процесса API

Конвейер разделяет ответственность на четыре уровня: обработка входных данных, оркестрация, обработка и хранение. Эта архитектура соответствует паттернам, описанным в технических руководствах по интеграции API для автоматизации рабочих процессов SEO.

Обработка входных данных: списки URL по локалям

Ваш конвейер начинается с канонического списка URL, сгруппированных по локалям. Получите его из вашей CMS, платформы перевода или индекса карт сайта, а не только из сканирования.

{
  "locales": {
    "en-us": {
      "urls": ["https://example.com/page-a", "https://example.com/page-b"],
      "sitemap": "https://example.com/sitemap-en-us.xml"
    },
    "fr-fr": {
      "urls": ["https://example.com/fr/page-a", "https://example.com/fr/page-b"],
      "sitemap": "https://example.com/sitemap-fr-fr.xml"
    }
  }
}

Уровень оркестрации

Оркестратор планирует вызовы API, управляет зависимостями между этапами и обрабатывает сбои без прерывания всего конвейера.

Используйте структуру направленного ациклического графа (DAG).

Обработка ошибок при лимитах запросов

Лимиты запросов к API во время массового международного сканирования требуют проактивного управления.

  • Механизмы ограничения частоты запросов по алгоритму «ведро с токенами» или «протекающее ведро» для каждого поставщика API, настроенные согласно их документированным лимитам с запасом безопасности.
  • Экспоненциальная задержка с джиттером для ответов 429 и 503, с максимальным количеством повторных попыток для предотвращения бесконечных циклов на постоянно недоступных конечных точках.
  • Предохранители, которые приостанавливают запросы к неисправному API на период охлаждения, затем проверяют его одним запросом перед возобновлением полной нагрузки.
  • Пакетная обработка запросов там, где это поддерживается API, что снижает накладные расходы на сетевые обмены и часто позволяет получить более выгодные условия по лимитам запросов.

Логируйте каждое достижение лимита запросов с указанием времени, конечной точки и результата повторной попытки.

Нормализация данных

Каждый API возвращает данные в разных схемах.

{
  "url": "string",
  "locale": "string (BCP 47 tag)",
  "hreflangs": [
    {
      "href": "string",
      "hreflang": "string",
      "source": "html|http_header|sitemap"
    }
  ],
  "canonical": "string|null",
  "noindex": "boolean",
  "performance": {
    "country": "string (ISO 3166-1 alpha-3)",
    "clicks": "number",
    "impressions": "number",
    "ctr": "number",
    "position": "number"
  }
}

Эта схема отделяет результаты аудита от метаданных источника, поэтому ваш слой отчетности может отследить происхождение любого значения.

Пошаговое руководство по внедрению

В этом разделе описывается программирование основных компонентов пользовательского рабочего процесса API на Python.

Настройка аутентификации

Для доступа к API Google Search Console требуются действительные учетные данные. Храните учетные данные в переменных окружения или в менеджере секретов, никогда не помещайте их в код репозитория.

  1. Создание сервисного аккаунтаВ консоли Google Cloud создайте сервисный аккаунт и скачайте файл ключа JSON.
  2. Предоставление доступа к Search ConsoleДобавьте адрес электронной почты сервисного аккаунта как ограниченного пользователя для каждого ресурса, который вы будете аудировать.
  3. Инициализация клиентаИспользуйте клиентскую библиотеку Google API для создания сервиса webmasters с учетными данными из файла ключа.

Получение локализованных метаданных с фильтрами по стране и языку

Запрашивайте данные эффективности из Search Console с явными фильтрами по измерениям для анализа по странам и языкам.

request_body = {
    'startDate': '2026-10-01',
    'endDate': '2026-10-07',
    'dimensions': ['query', 'page', 'country', 'device'],
    'dimensionFilterGroups': [{
        'filters': [{
            'dimension': 'country',
            'operator': 'equals',
            'expression': 'FRA'
        }]
    }],
    'rowLimit': 25000,
    'startRow': 0
}

Программная проверка тегов hreflang

Логика проверки hreflang в контексте API требует трех проверок: полноты, взаимности и согласованности.

Полнота: каждая локализованная страница должна иметь самоссылающийся тег hreflang.

Взаимность: для каждого объявления hreflang на странице A, указывающего на страницу B, страница B должна объявлять страницу A как альтернативную. Документация Google рекомендует проверять взаимные связи альтернативных страниц, отмечая, что отсутствие обратных ссылок может привести к игнорированию аннотаций или их неверной интерпретации.

Согласованность: один и тот же URL не должен появляться как альтернативный для нескольких значений hreflang, если только региональные варианты не дублируются намеренно. Проверьте конфликты между объявлениями hreflang и тегами canonical, директивами noindex или исключениями в robots.txt.

def validate_reciprocity(url_index):
    """
    url_index: dict mapping URL -> list of hreflang dicts with 'href' and 'hreflang'
    Returns: list of error dicts with 'source_url', 'target_url', 'expected_hreflang'
    """
    errors = []
    for source_url, hreflangs in url_index.items():
        for hreflang in hreflangs:
            target_url = hreflang['href']
            expected_lang = hreflang['hreflang']
            
            if target_url not in url_index:
                errors.append({
                    'source_url': source_url,
                    'target_url': target_url,
                    'error': 'target_not_found_in_index'
                })
                continue
                
            target_hreflangs = url_index[target_url]
            return_links = [h for h in target_hreflangs 
                          if h['href'] == source_url]
            
            if not return_links:
                errors.append({
                    'source_url': source_url,
                    'target_url': target_url,
                    'error': 'missing_return_link'
                })
            elif not any(r['hreflang'] == expected_lang for r in return_links):
                errors.append({
                    'source_url': source_url,
                    'target_url': target_url,
                    'expected_hreflang': expected_lang,
                    'error': 'mismatched_return_link_language'
                })
    return errors

Выполните эту проверку относительно вашего нормализованного индекса hreflang, который агрегирует объявления из HTML, HTTP-заголовков и карт сайта. Ваш рабочий процесс должен проверять все три источника, чтобы избежать ложных отрицательных результатов.

Агрегация результатов в формат, готовый для панели мониторинга

Преобразуйте ошибки проверки и метрики эффективности в структуру, оптимизированную для вашего инструмента отчетности.

  • Одна таблица на каждую локаль со статусом прохождения/непроведения на уровне URL для каждого типа проверки.
  • Одна таблица для проблем между локалями (сбои взаимности, конфликты canonical).
  • Данные эффективности временных рядов, объединенные с измерениями URL и локали.

Храните необработанные ответы API в объектном хранилище (S3, GCS, Azure Blob) с политиками хранения.

Начать бесплатно

Пример случая: автоматизация проверки hreflang в десяти локалях

Рассмотрим компанию SaaS с локализованными маркетинговыми сайтами по путям /en-us/, /en-gb/, /de-de/, /fr-fr/, /es-es/, /it-it/, /pt-br/, /ja-jp/, /ko-kr/ и /zh-cn/. Ручной процесс аудита требовал от специалистов выборочной проверки страниц, занимал несколько дней и охватывал лишь часть сайта. Ошибки взаимности между en-us и en-gb были упущены, потому что проверка рассматривала каждую локаль изолированно.

  1. Загрузка карт сайтаЗагрузите и разберите все десять карт сайтов, построив индекс соответствия URL и локали.
  2. Параллельное сканированиеПоставьте все URL в очередь для извлечения hreflang, применяя ограничение частоты запросов для каждой локали, чтобы соблюдать ограничения API сканирования.
  3. Перекрестная проверкаПостройте граф hreflang и выполните проверки взаимности. Отсутствие обратных ссылок из en-gb в en-us было выявлено после обновления шаблона.
  4. Корреляция с эффективностьюЗапросите последние данные через API Search Console, отфильтрованные по стране. Страницы с ошибками hreflang показали более низкий CTR для брендовых запросов в затронутых странах по сравнению с чистыми страницами.
  5. Генерация оповещенийСоздавайте задачи в системе управления проектами команды с указанием конкретных URL, типов ошибок и предлагаемых исправлений.

Конвейер данных выполняется ежедневно. Корреляция между ошибками hreflang и снижением CTR была получена путем автоматического объединения результатов проверки с данными Search Console — комбинация, которую ручные процессы не могут воспроизвести с такой частотой.

Масштабирование и поддержка вашей системы аудита

Построение конвейера данных — это только начало. Долгосрочная ценность зависит от операционных практик, которые обеспечивают его точность и контроль затрат.

Мониторинг состояния API

Отслеживайте успешность запросов к каждому API, перцентили задержки (p50, p95, p99) и расход квот. Настраивайте оповещения при устойчивом превышении пороговых значений ошибок или значительном увеличении задержек. Корректируйте их на основе ваших требований SLA и критичности каждого источника данных.

Версионируйте код клиента API и фиксируйте протестированные версии SDK провайдеров. Когда Google выпускает новую версию API Search Console, выполняйте параллельные запросы к обеим версиям в течение периода валидации перед переключением продуктивного трафика.

Обновление конечных точек и правил валидации

Поведение поисковых систем меняется. Подпишитесь на официальные журналы изменений и поддерживайте набор регрессионных тестов, который запускается на известных «хороших» и «плохих» наборах URL. Когда лучшие практики SEO-аудита эволюционируют, обновляйте свои правила валидации и проверяйте, что они выявляют новые типы проблем без увеличения количества ложных срабатываний.

Что касается конкретно hreflang, следите за документацией Google Search Central по локализованным версиям на предмет изменений в поддерживаемых методах или рекомендуемых практиках. Исследование для этой статьи не проверяло актуальность путей конечных точек или значений квот именно на 2026 год. Уточняйте эти данные по официальной документации, прежде чем описывать их как текущие стандарты во внутренней документации.

Управление затратами при объемном сканировании

Затраты на API сканирования масштабируются в зависимости от количества страниц и глубины обхода.

  • Инкрементальное сканирование: поддерживайте хеш контента или временную метку последнего изменения для каждого URL. Повторно сканируйте только тогда, когда источник указывает на изменение.
  • Приоритетные уровни: сканируйте страницы с высоким трафиком и высокой конверсией ежедневно. Сканируйте «длинный хвост» еженедельно или ежемесячно.
  • Выборочная валидация: для очень больших сайтов проверяйте взаимность hreflang на стратифицированной выборке, включающей все главные страницы локалей, все страницы категорий товаров и случайную выборку контентных страниц. Полная валидация выполняется ежемесячно. Выборочная валидация — ежедневно.

Отслеживайте стоимость одной проверенной URL и стоимость одного найденного дефекта. Эти метрики показывают, эффективна ли ваша стратегия сканирования или вы тратите непропорционально много ресурсов на страницы с низким уровнем ошибок.

Схема данных для результатов локализованного аудита

CREATE TABLE audit_runs (
    run_id UUID PRIMARY KEY,
    started_at TIMESTAMP,
    completed_at TIMESTAMP,
    config_hash TEXT  -- hash of pipeline configuration for reproducibility
);

CREATE TABLE url_audits (
    audit_id UUID PRIMARY KEY,
    run_id UUID REFERENCES audit_runs(run_id),
    url TEXT NOT NULL,
    locale TEXT NOT NULL,
    crawled_at TIMESTAMP,
    status_code INT,
    canonical_url TEXT,
    noindex_present BOOLEAN
);

CREATE TABLE hreflang_declarations (
    declaration_id UUID PRIMARY KEY,
    audit_id UUID REFERENCES url_audits(audit_id),
    href TEXT NOT NULL,
    hreflang TEXT NOT NULL,
    source TEXT CHECK (source IN ('html', 'http_header', 'sitemap'))
);

CREATE TABLE hreflang_errors (
    error_id UUID PRIMARY KEY,
    run_id UUID REFERENCES audit_runs(run_id),
    source_url TEXT,
    target_url TEXT,
    error_type TEXT CHECK (error_type IN (
        'missing_self_reference',
        'missing_return_link',
        'mismatched_language',
        'canonical_conflict',
        'noindex_conflict'
    )),
    severity TEXT CHECK (severity IN ('critical', 'warning', 'info'))
);

CREATE TABLE performance_metrics (
    metric_id UUID PRIMARY KEY,
    run_id UUID REFERENCES audit_runs(run_id),
    url TEXT,
    country TEXT,
    query TEXT,
    clicks INT,
    impressions INT,
    ctr DECIMAL(5,4),
    position DECIMAL(5,2)
);

Разделяйте таблицы performance_metrics и hreflang_errors по run_id или дате для обеспечения производительности запросов при большом объеме данных. Индексируйте поля url, locale и error_type под наиболее часто используемые паттерны фильтрации в вашем дашборде.

С чего начать внедрение

  • Сначала создайте манифест URL с группировкой по локалям, прежде чем писать какой-либо код для работы с API.
  • Внедрите проверку взаимности hreflang как самый ценный автоматизированный контроль.
  • Добавьте фильтры по странам и языкам через API Search Console, чтобы коррелировать технические ошибки с влиянием на производительность.
  • Проектируйте схему хранения данных для запросов временных рядов с самого начала, а не как последующую доработку.
  • Настройте мониторинг и отслеживание затрат перед масштабированием до полного охвата сайта.

Для команд, желающих расширить эти паттерны, интеграция SEO API с AI-агентами открывает пути к автоматической классификации проблем и генерации предложений по их исправлению.

Внедряйте автоматизированный многоязычный аудит без разработки с нуля

ProveRank предоставляет инфраструктуру API и локализованные метрики, позволяющие вашей команде сосредоточиться на анализе, а не на поддержке конвейера данных. Начните с бесплатного аккаунта и выполните первый кросс-локальный аудит уже сегодня.

Начать бесплатно

ПоделитьсяОпубликовать в XLinkedIn
Все статьи →