Этот документ был автоматически переведён с английского языка с помощью Claude AI. Термины из области WMO/метеорологии должны быть проверены носителем языка перед использованием в производственной среде. Смотрите оригинал на английском для авторитетной версии.

1. Обзор

WIS2 Downloader предоставляет REST API для управления подписками и мониторинга системы.

2. Аутентификация

В настоящее время API не требует аутентификации. В производственной среде рекомендуется разместить его за обратным прокси-сервером с аутентификацией.

3. API подписок

3.1. Список подписок

Возвращает все активные подписки.

GET /subscriptions

3.1.1. Ответ

Статус Описание

200

Успех — возвращает карту тема → детали подписки

503

Redis недоступен

3.1.2. Пример

curl http://localhost:5002/subscriptions
{
  "cache/a/wis2/+/data/core/weather/surface-based-observations/#": {
    "topic": "cache/a/wis2/+/data/core/weather/surface-based-observations/#",
    "save_path": "surface-obs",
    "filters": {
      "accepted_media_types": ["application/bufr", "application/grib"]
    }
  }
}

3.2. Создание подписки

Создаёт новую подписку на тему WIS2.

POST /subscriptions
Content-Type: application/json

3.2.1. Тело запроса

Поле Тип Обязательно Описание

topic

string

Да

Шаблон темы MQTT WIS2. Поддерживает + (один уровень) и # (несколько уровней) как подстановочные знаки.

target

string

Нет

Подкаталог под /data для сохранения файлов.

filters

object

Нет

Конфигурация фильтра.

filters.accepted_media_types

array

Нет

Список разрешённых типов MIME. Поддерживает подстановочные знаки (например, application/x-grib*).

3.2.2. Ответ

Статус Описание

202

Принято — подписка поставлена в очередь на обработку

400

Неверный запрос — тема отсутствует или недействительна

503

Сервис недоступен — ошибка подключения к Redis

3.2.3. Заголовки ответа

Заголовок Описание

Location

URL для получения деталей подписки

3.2.4. Пример

curl -X POST http://localhost:5002/subscriptions \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "cache/a/wis2/+/data/core/weather/surface-based-observations/#",
    "target": "surface-obs",
    "filters": {
      "accepted_media_types": ["application/bufr", "application/grib"]
    }
  }'
{
  "status": "accepted",
  "topic": "cache/a/wis2/+/data/core/weather/surface-based-observations/#",
  "target": "surface-obs"
}

3.3. Получение подписки

Возвращает детали конкретной подписки.

GET /subscriptions/{topic}

3.3.1. Параметры пути

Параметр Тип Описание

topic

string

Тема WIS2 (только # требует кодирования как %23)

3.3.2. Кодирование URL

Только символ # требует URL-кодирования:

Символ Закодированный Причина

#

%23

Иначе интерпретируется как фрагмент URL
Слэши (/) и + не требуют кодирования в пути.

3.3.3. Ответ

Статус Описание

200

Успех

400

Недействительная тема

404

Подписка не найдена

503

Redis недоступен

3.3.4. Пример

curl "http://localhost:5002/subscriptions/cache/a/wis2/+/data/core/weather/surface-based-observations/%23"
{
  "topic": "cache/a/wis2/+/data/core/weather/surface-based-observations/#",
  "save_path": "surface-obs",
  "filters": {
    "accepted_media_types": ["application/bufr", "application/grib"]
  }
}

3.4. Удаление подписки

Удаляет подписку.

DELETE /subscriptions/{topic}

3.4.1. Параметры пути

Параметр Тип Описание

topic

string

URL-кодированная тема WIS2

3.4.2. Ответ

Статус Описание

200

Успешно удалено

400

Недействительная тема

503

Redis недоступен

3.4.3. Пример

curl -X DELETE "http://localhost:5002/subscriptions/cache/a/wis2/+/data/core/weather/surface-based-observations/%23"
{
  "status": "deleted",
  "topic": "cache/a/wis2/+/data/core/weather/surface-based-observations/#"
}

4. API мониторинга

4.1. Проверка работоспособности

Возвращает состояние работоспособности сервиса.

GET /health

4.1.1. Ответ

Всегда возвращает 200. Проверьте поле status для фактического состояния.

Поле Значения

status

healthy или unhealthy

4.1.2. Пример

curl http://localhost:5002/health
{"status": "healthy"}

4.2. Метрики Prometheus

Возвращает метрики в текстовом формате Prometheus.

GET /metrics

4.2.1. Ответ

Статус Описание

200

Метрики в текстовом формате Prometheus

500

Ошибка генерации метрик

4.2.2. Доступные метрики

Метрика Тип Метки Описание

wis2downloader_notifications_total

Counter

status

Всего обработанных уведомлений

wis2downloader_downloads_total

Counter

cache, media_type

Успешно загруженные файлы

wis2downloader_downloads_bytes_total

Counter

cache, media_type

Всего загруженных байт

wis2downloader_skipped_total

Counter

reason

Пропущенные уведомления по причине

wis2downloader_failed_total

Counter

cache, reason

Неудачные загрузки

wis2downloader_celery_queue_length

Gauge

queue_name

Текущее количество задач в очереди Celery

4.2.3. Пример

curl http://localhost:5002/metrics
# HELP wis2downloader_downloads_total Total number of files downloaded.
# TYPE wis2downloader_downloads_total counter
wis2downloader_downloads_total{cache="example.cache.com",media_type="application/bufr"} 42.0

# HELP wis2downloader_notifications_total Total notifications processed.
# TYPE wis2downloader_notifications_total counter
wis2downloader_notifications_total{status="success"} 42.0
wis2downloader_notifications_total{status="skipped"} 5.0

4.3. Спецификация OpenAPI

Возвращает спецификацию OpenAPI 3.0 в формате JSON.

GET /openapi

4.4. Swagger UI

Интерактивная документация API.

GET /
GET /swagger

5. Ответы с ошибками

Все ответы с ошибками следуют этому формату:

{
  "error": "Error message describing the problem"
}

5.1. Распространённые сообщения об ошибках

Статус Ошибка Причина

400

"No topic provided"

POST /subscriptions без поля topic

400

"No topic passed"

GET/DELETE с пустой темой

404

"Subscription for topic X not found"

Тема не подписана

503

"Failed to connect to Redis: …​"

Redis недоступен

503

"Failed to queue subscription command…​"

Ошибка Redis pub/sub

503

"Failed to persist subscription…​"

Ошибка записи Redis

6. Схемы данных

6.1. Подписка

{
  "topic": "string (required) - WIS2 MQTT topic pattern",
  "save_path": "string | null - Subdirectory for downloads",
  "filters": {
    "accepted_media_types": ["array of MIME type strings"]
  }
}

6.2. Фильтры

{
  "accepted_media_types": [
    "application/bufr",
    "application/grib",
    "application/x-netcdf*"
  ]
}

6.2.1. Принимаемые типы медиа по умолчанию

Если фильтр не указан, принимаются следующие типы:

[
  "image/gif", "image/jpeg", "image/png", "image/tiff",
  "application/pdf", "application/postscript",
  "application/bufr", "application/grib",
  "application/x-hdf", "application/x-hdf5",
  "application/x-netcdf", "application/x-netcdf4",
  "text/plain", "text/html", "text/xml", "text/csv",
  "text/tab-separated-values"
]

7. Справочник по шаблонам тем

7.1. Структура темы WIS2

{origin|cache}/a/wis2/{centre-id}/data/{data-policy}/{earth-system-domain}/{category}/...

  • origin - Исходные данные от поставщика данных

  • cache - Кэшированная копия из глобального кэша (рекомендуется для надёжности)

  • {centre-id} - Код страны/организации, с префиксом ISO2C кода страны (например, de-dwd)

  • {data-policy} - Единая политика данных WMO: core или recommended

  • {earth-system-domain} - Область системы Земли из Единой политики данных WMO

7.2. Подстановочные знаки

Шаблон Символ Описание

Один уровень

+

Соответствует ровно одному уровню

Несколько уровней

#

Соответствует нулю или более уровней (должен быть в конце)

7.3. Примеры

Шаблон Соответствует

cache/a/wis2/de-dwd/data/#

Все данные от Deutscher Wetterdienst

cache/a/wis2/+/data/core/weather/surface-based-observations/#

Приземные наблюдения со всех центров

cache/a/wis2/+/data/core/#

Все основные данные из любого центра

cache/a/wis2//data//weather/#

Все метеорологические данные (любая политика) из любого центра