Погодные клиенты: контракт 1.7
Нормативное дополнение к обзору API. База всех относительных URL в погодных JSON: https://games.oopssre.ru/assets/arcade/views/. Даже путь внутри вложенного прогноза разрешается от этой базы. Версия документа 1.7, версии схем JSON и непрозрачные версии содержимого — разные величины.
Документы и обязательные различия
| Документ | Назначение |
|---|---|
manifest-v3.json | Каталог коллекций, форматов и загрузок; schema: 3 |
weather/C/current.json | Снимок последнего обновления коллекции C; schema: 1, type: weather |
weather/C/forecast-D.json | Готовое расписание устройства D; schema: 1, document_type: weather-forecast |
weather/C/assets.json | Каталог подготовленных изображений; schema: 1 |
ZIP из downloads | Рисунки коллекции и устройства; не актуальный прогноз |
current.json не является часами: после границы его интервала следующий кадр выбирается по прогнозу. Верхний ready означает наличие хотя бы одного готового формата, поэтому выбранный формат проверяется отдельно.
Текущее состояние
| Поля | Значение |
|---|---|
collection_id, title | Идентичность и название оформления |
source_id, world_id, source | Источник real или game-world, мир либо null, описание источника либо null |
location, location_revision, timezone | Название, широта, долгота и часовой пояс; непрозрачная ревизия; IANA timezone |
formats, package_versions | Объявленные форматы и версии их пакетов |
status, reason | Общая готовность и причина либо null |
files | Готовые файлы по идентификаторам устройств |
format_status | Необязательные статус и причина каждого формата |
season, time_of_day, weather, weather_code | Состояние, если определено; погодная группа и код могут быть null |
state_id, state_title, moon_phase, world_date | Необязательные идентификатор, подпись, лунная фаза и дата мира |
valid_from, valid_until, forecast_valid_until | Необязательные границы готовности |
weather_fetched_at, refresh_after | Момент получения погоды либо null; рекомендация обновления |
refresh_error | Последняя ошибка {at, message} либо null |
preview, preview_format | Необязательное превью и его формат |
last_successful_image | Последний успешный кадр либо null |
delivery.direct_image.enabled | Доступность постоянных адресов изображения |
generated_at, document_type и contract_version не являются обязательными полями current.json. Температура, ветер и весь набор числовых измерений не входят в обещание этого API: для динамической композиции используются отдельные входы.
Файл содержит url, format: jpeg, rendition, width, height, aspect, bytes, sha256, cache_key. cache_key — ключ задачи подготовки, а sha256 — контрольная сумма байтов. Запись current.files[D] может дополнительно содержать state_id, state_title, постоянный image_url и превью. Необязательное превью содержит URL, формат, размеры, размер файла и SHA-256. Обычный thumbnail имеет длинную сторону до 640 px; плеерное превью готовится отдельно.
Прогноз и интервалы
Готовый прогноз содержит collection_id, format, source_id, world_id, contract_version, необязательную package_version, location, location_revision, timezone, generated_at, valid_until, refresh_after, weather_fetched_at, source, season_months, astronomy, intervals. Версии сравниваются на равенство; из них нельзя извлекать календарь или номер релиза клиента. Верхний status у готового документа может отсутствовать. Недоступный прогноз допускает сокращённую форму: status: unavailable, generated_at: null, valid_until: null, intervals: [].
Горизонт — 24 часа от generated_at, а не до местной полуночи. Выбор: valid_from <= now < valid_until, с точными абсолютными датами и смещениями. Соседние равные состояния могут объединяться; число интервалов не обязано быть 24. refresh_after — срок повторного запроса, не срок пригодности кадра.
Интервал содержит границы, world_date, season, time_of_day, weather, weather_code, state_id, moon_phase, status, image_url и file для готового изображения. image_url готового интервала совпадает с file.url, а не с постоянным адресом current. Возможны preview и player_preview. Неготовый интервал содержит причину, image_url: null и не имеет готового file.
astronomy содержит движок, days, солнечное погружение и лунную политику. День задаёт dawn, sunrise, sunset, dusk, moon_phase; в полярных условиях события могут быть null. Клиент использует готовые интервалы и не обязан пересчитывать Astral. Значение local в старом календаре обычных коллекций не заменяет часовой пояс погодного источника.
Коды состояния
Сезоны: spring, summer, autumn, winter. Части суток: dawn, day, dusk, night. Луна: none, new_moon, waxing_crescent, first_quarter, waxing_gibbous, full_moon, waning_gibbous, last_quarter, waning_crescent. none означает отсутствие лунного варианта, а не новолуние.
| Погодная группа | Исходные коды |
|---|---|
clear | 0 |
partly-cloudy | 1, 2 |
overcast | 3 |
fog | 45, 48 |
drizzle | 51, 53, 55 |
rain | 61, 63, 80, 81 |
heavy-rain | 65, 82 |
freezing-precipitation | 56, 57, 66, 67 |
snow | 71, 73, 77, 85 |
heavy-snow | 75, 86 |
thunderstorm | 95 |
severe-thunderstorm | 97 |
thunderstorm-hail | 96, 99 |
97 — поддержанное проектом отображение, а не обещание его выдачи Open-Meteo. Эта таблица из 13 групп относится к готовым погодным коллекциям; динамический контракт использует собственные 6 групп. state_id имеет вид <season>-<time_of_day>-<weather>; группа сама может содержать дефисы, поэтому разбиение ровно на три части неверно.
Готовность и ошибки
Статусы: ready, not_ready, unresolved_weather, unavailable, stale. Неизвестный статус не считается готовностью. Причины: weather_unavailable, forecast_expired, unknown_weather_code, state_not_in_collection, prototype_only, artwork_planned, prepared_variant_missing, prepared_file_missing, prepared_file_damaged. Новая неизвестная причина должна отображаться без аварии.
HTTP 200 не гарантирует готовое изображение. Ошибка HTTP, сети или разбора JSON — отдельная ошибка доставки. При недоступности допустимо сохранить предыдущую установленную картинку с честной подписью. Нельзя выдавать её за актуальную, незаметно менять источник или мир. В last_successful_image подпись выбранного устройства берётся из его файла; applied_at — серверная отметка, а не время установки клиентом.
ZIP, совместимость и кеш
Архив выбирается из каталога: нужные collection, format: zip, rendition: D. Запись содержит идентификатор, название, URL, байты, SHA-256 и версию. Читайте URL, а не конструируйте его из названия. ZIP общий для двух источников погоды, но принадлежит одному устройству.
В архиве: manifest.json со schema: 3, document_type: weather-wallpaper-package, type: weather, id, title, version, format, ready_states, total_states, variants; weather-package.json со schema: 1, типом и форматом; README и JPG. Вариант задаёт state_id, название, moon_phase и свойства файла; URL внутри ZIP разрешается относительно ZIP. Совпадают и состояние, и лунный вариант. Версия архива сравнивается с forecast.package_version своего устройства; версия контракта коллекции может измениться из-за другого формата.
assets.json содержит идентичность, версию, форматы, готовность и states. Состояние имеет id, title, status, moon_mode, variants[phase][device], возможные превью. Наличие состояния означает готовность хотя бы одного устройства, а не всех. ZIP содержит рисунки, а не бессрочный прогноз.
Клиент читает совместимую пару current/forecast, проверяет источник, мир, ревизию места, устройство и объявленные версии. При обновлении между запросами перечитывает пару. JSON публикуются атомарно по отдельности, но два HTTP-запроса не образуют транзакцию. Готовый файл скачивается временно, проверяются размер, SHA-256 и размеры JPEG; затем он заменяет локальную копию. Неизвестные необязательные поля можно игнорировать; несовместимую схему нельзя угадывать.
Совместимые расширения
Дополнительный astronomy.events содержит астрономический снимок. В current.json он может появляться независимо от готовности погоды. Неизвестные необязательные поля игнорируются; срок астрономии не продлевает прогноз погоды. Старые солнечные события и художественные фазы сохраняются. Подробнее: астрономия и совместимость.
Порядок чтения: Оглавление · Назад: Спецификация погодного API · Далее: Спецификация динамической темы
Необязательные PNG-мастер, независимая активность, календарь темы и облака/атмосфера: расширения 1.0.90.