Загрузка с помощью WIS2 Downloader

Результаты обучения!

К концу этого практического занятия вы сможете:

находить и подписываться на наборы данных
использовать фильтрацию для управления загружаемыми файлами
использовать аутентификацию для загрузки наборов данных с ограниченным доступом
изменять настройки WIS2 Downloader для более сложных сценариев использования

Введение

В WIS2 все наборы данных имеют файл метаданных, который можно найти в Global Discovery Catalogues. Таким образом, предполагается, что пользователи всегда будут обращаться к этим сервисам, чтобы найти данные, распространяемые через WIS2.

WIS2 Downloader использует этот принцип, находя все записи, доступные в этих GDC, и объединяя их внутри системы, чтобы пользователь мог ориентироваться в доступных данных WIS2. Поскольку количество записей велико, важно предоставить пользователю возможность фильтровать их и находить нужную запись. Даже после нахождения и подписки на нужную запись могут быть наборы данных, где количество файлов превышает текущие потребности пользователя. Поэтому требуется второй уровень фильтрации — тот, который работает при принятии решения о загрузке файла.

Использование в режиме просмотра каталога

Catalogue View — один из двух способов найти и подписаться на наборы данных в WIS2 Downloader. Он объединяет записи из Global Discovery Catalogues и представляет их в интерфейсе с возможностью поиска и фильтрации — аналогично просмотру портала GDC напрямую.

Перейдите в Catalogue View через левую боковую панель.

WIS2 Downloader Catalogue View

В верхней части страницы вы найдете строку поиска и набор фильтров. Вы можете использовать их, чтобы сузить список доступных записей по ключевым словам, Centre ID или политике данных (core vs. recommended).

Вы также можете фильтровать пространственно, задавая bounding box с помощью четырех координат — North, West, South и East — выраженных в десятичных значениях широты и долготы. При задании bounding box можно выбрать один из двух режимов сопоставления:

Intersects — возвращает записи, пространственный охват которых пересекается с bounding box любым образом.
Within — возвращает только записи, пространственный охват которых полностью находится внутри bounding box.

Обновление каталога

Каталог загружается из GDC при запуске WIS2 Downloader. Если вы считаете, что список устарел, вы можете принудительно обновить его в разделе Settings в левой боковой панели.

Упражнение: найти и подписаться на набор данных

Найти набор данных наблюдений за поверхностью

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

Введите surface в строку поиска и посмотрите, как фильтруется список записей.
Установите фильтр политики данных на core.
Установите ключевые слова, включающие temperature, precipitation, и посмотрите, как изменяются результаты.
Выберите запись из результатов, чтобы развернуть ее детали.
Просмотрите показанные метаданные — обратите внимание на тему, исходный центр и политику данных.
Установите папку назначения в surface-obs.
Нажмите Subscribe, чтобы создать подписку.

После подписки перейдите в Manage Subscriptions, чтобы подтвердить, что новая подписка появилась в списке.

Нажмите, чтобы увидеть ответ

Любая запись, тема которой содержит surface-based-observations, а политика данных — core, является допустимым выбором. Применение фильтра ключевых слов для temperature, precipitation дополнительно сузит результаты до наборов данных, относящихся к этим переменным.

После подписки в режиме Manage Subscriptions будет отображаться активная подписка с ее темой и целевой папкой. Файлы начнут загружаться по мере поступления новых уведомлений на брокер.

Отписка и удаление загруженных файлов

Перейдите в режим Manage Subscriptions и выберите Unsubscribe для темы, выбранной в предыдущем упражнении.

После этого очистите папку загрузок:

rm -fr /home/<username>/wis2-downloads/surface-obs

Использование режима просмотра дерева

Tree View представляет иерархию тем WIS2 в виде сворачиваемого дерева, позволяя вам просматривать доступные темы уровень за уровнем — аналогично навигации по темам в MQTT Explorer. Он предназначен для более высокого уровня, сверху вниз, исследования доступных данных WIS2, начиная с корня иерархии и углубляясь. Это контрастирует с режимом просмотра каталога, который сразу переходит к отдельным записям наборов данных и лучше подходит, когда вы уже знаете, что ищете.

Перейдите в Tree View через левую боковую панель.

WIS2 Downloader Tree View

Дерево организовано в соответствии с иерархией тем WIS2. Разверните каждый уровень, щелкнув узел, чтобы увидеть его дочерние элементы. На любом уровне вы можете подписаться, выбрав узел и нажав Subscribe — используя подстановочный знак (#), чтобы захватить все темы ниже этого узла.

Подписка на разных уровнях

Подписка на более высоком уровне дерева (например, на уровне Centre ID) захватит все наборы данных, опубликованные этим центром. Подписка на более низком уровне дает более детальный контроль. Используйте суффикс подстановочного знака #, который автоматически добавляется WIS2 Downloader при подписке из режима просмотра дерева.

Упражнение: найти и подписаться через режим просмотра дерева

Подписаться на набор данных через режим просмотра дерева

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

Разверните дерево, начиная с узла cache, затем перейдите через a → wis2.
Выберите Centre ID по вашему выбору и продолжайте разворачивать, пока не дойдете до темы, связанной с surface-based-observations.
Просмотрите полный путь темы — подтвердите, что он соответствует нужному набору данных.
Установите папку назначения в surface-obs-tree.
Нажмите Subscribe, чтобы создать подписку.

Перейдите в Manage Subscriptions, чтобы подтвердить, что подписка активна.

Нажмите, чтобы увидеть ответ

Любой путь темы, соответствующий шаблону cache/a/wis2/<centre-id>/data/core/weather/surface-based-observations/#, является допустимым выбором. Сегмент Centre ID будет варьироваться в зависимости от выбранного вами центра.

В режиме Manage Subscriptions будет отображаться новая подписка наряду с ранее созданными.

Отписка и удаление загруженных файлов

Перейдите в режим Manage Subscriptions и выберите Unsubscribe для темы, выбранной в предыдущем упражнении.

После этого очистите папку загрузок:

rm -fr /home/<username>/wis2-downloads/surface-obs-tree

Использование режима ручной подписки

Manual Subscribe позволяет создавать подписку, вводя тему напрямую, без использования Global Discovery Catalogues. В отличие от режима просмотра каталога и дерева — которые оба получают свои темы из GDC — Manual Subscribe полезен, когда вы уже знаете точную тему, на которую хотите подписаться, и хотите настроить ее без просмотра каталога с большей свободой в выборе WTH.

Перейдите в Manual Subscribe через левую боковую панель.

WIS2 Downloader Manual Subscribe

Форма позволяет указать:

Topic — полный MQTT-топик для подписки, включая любые подстановочные знаки (например, # и +).
Destination folder — локальный подкаталог, в котором будут сохраняться загруженные файлы.
Filter — необязательный объект фильтра в текстовом виде для управления уведомлениями, которые загружаются.
Priority queue — управляет приоритетом загрузки, назначенным уведомлениям от этой подписки.
Authentication — учетные данные, необходимые для наборов данных с ограниченным доступом.

Когда использовать Manual Subscribe

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

Загрузка из набора данных с ограниченным доступом

Некоторые наборы данных в WIS2 имеют ограниченный доступ, что означает, что для загрузки файлов требуются действительные учетные данные. WIS2 Downloader поддерживает два метода аутентификации в режиме Manual Subscribe:

Basic HTTP authentication — предоставьте имя пользователя и пароль, связанные с вашими учетными данными.
Bearer token — предоставьте токен, выданный издателем данных, вместо имени пользователя и пароля.

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

Упражнение: подписаться на набор данных с ограниченным доступом на вашем wis2box

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

Настроить и подписаться на набор данных с ограниченным доступом

Шаг 1 — Создать набор данных с ограниченным доступом на wis2box

На вашем экземпляре wis2box создайте набор данных с включенным ограничением доступа и запишите тему и токен, сгенерированный для него. Если вы еще этого не сделали, обратитесь к практическому занятию Datasets with access control для полного описания шагов настройки.

Шаг 2 — Настройка WIS2 Downloader для прослушивания брокера wis2box

По умолчанию WIS2 Downloader прослушивает Global Broker. Чтобы получать уведомления непосредственно от вашей инстанции wis2box, необходимо добавить подписчика в compose-файл WIS2 Downloader, который указывает на внутренний MQTT брокер wis2box.

Откройте файл docker-compose.yml в директории WIS2 Downloader и добавьте следующую конфигурацию подписчика, заменив WIS2BOX_URL на URL вашей инстанции wis2box:

  subscriber-test:
container_name: subscriber-test
restart: always
build:
  context: .
  dockerfile: ./containers/subscriber/Dockerfile
  args:
    WIS2DOWNLOADER_UID: ${WIS2DOWNLOADER_UID:-10001}
    WIS2DOWNLOADER_GID: ${WIS2DOWNLOADER_GID:-988}
env_file: *default-env
environment:
  GLOBAL_BROKER_HOST: WIS2BOX_URL
  GLOBAL_BROKER_PORT: 443
  GLOBAL_BROKER_USERNAME: everyone
  GLOBAL_BROKER_PASSWORD: everyone
  MQTT_PROTOCOL: websockets
depends_on:
  - redis
networks:
  - redis-net
logging: *loki-logging
healthcheck:
  test: ["CMD", "pgrep", "-f", "subscriber_start"]
  interval: 30s
  timeout: 5s
  retries: 3

Перезапустите стек, чтобы применить изменения:

docker compose down
docker compose up -d

Шаг 3 — Подписка на набор данных в WIS2 Downloader

Перейдите в Manual Subscribe в интерфейсе WIS2 Downloader.
Установите тему, настроенную для вашего набора данных с ограниченным доступом в wis2box.
Укажите папку назначения как restricted-data.
Введите токен доступа, созданный на шаге 1, в поле Authentication.
Нажмите Subscribe, чтобы создать подписку.

Шаг 4 — Отправка данных в набор данных на wis2box

На вашей инстанции wis2box опубликуйте файл в набор данных с ограниченным доступом. Ознакомьтесь с практическим занятием Ingesting data for publication для получения инструкций по загрузке данных.

Шаг 5 — Проверка загрузки

Убедитесь, что файл был загружен WIS2 Downloader:

ls /home/<username>/wis2-downloads/restricted-data

Нажмите, чтобы раскрыть ответ

С действительным токеном доступа WIS2 Downloader выполнит аутентификацию при загрузке файлов для темы с ограниченным доступом. Файл, опубликованный на шаге 4, должен появиться в папке restricted-data вскоре после загрузки в wis2box.

Если аутентификация не удалась, файлы не будут загружены, даже если подписка отображается как активная в представлении Manage Subscriptions. Убедитесь, что токен доступа соответствует тому, который настроен для набора данных в wis2box.

Отписка и удаление загруженных файлов

Перейдите в представление Manage Subscriptions и нажмите Unsubscribe для темы, затем очистите папку загрузок:

rm -fr /home/<username>/wis2-downloads/restricted-data

Фильтрация загрузок

Фильтры позволяют контролировать, какие файлы загружаются из подписки на уровне уведомлений — это второй уровень фильтрации, упомянутый во введении. Вместо загрузки каждого файла, опубликованного в теме, вы можете определить фильтр, чтобы только уведомления, соответствующие определенным критериям, инициировали загрузку.

После выбора набора данных в Catalogue View или Tree View панель фильтров появляется на правой стороне экрана перед подпиской. Здесь вы можете заполнить значения фильтров, которые хотите применить. WIS2 Downloader автоматически создаст объект фильтра на основе ваших вводов.

В представлении Manual Subscribe вы можете вручную ввести этот объект фильтра, заполнив поле Filter (JSON) в форме.

Доступные параметры фильтров

Media type — ограничение загрузки определенными типами контента (например, application/bufr).
Dataset — ограничение загрузки определенным набором данных по его идентификатору метаданных.
Bounding box — ограничение загрузки уведомлений, данные которых находятся в пределах пространственной области, определенной значениями north, south, east и west.
Date & time range — ограничение загрузки уведомлений, опубликованных в определенном временном диапазоне.
Custom filters — фильтрация по любому другому свойству уведомления, определенному в записи метаданных, путем указания значения свойства (например, фильтрация по wigos_station_identifier, чтобы загружать данные только с определенной станции).

Пример объекта фильтра, созданного на основе этих вводов:

{
  "rules": [
    {
      "id": "accept",
      "order": 1,
      "match": {
        "all": [
          {
            "any": [
              { "media_type": { "exists": false } },
              { "media_type": { "in": ["application/bufr", "application/x-bufr"] } }
            ]
          },
          { "metadata_id": { "in": ["urn:wmo:md:ir-irimo:core.surface-based-observations.temp"] } },
          { "bbox": { "north": 23.0, "south": 27.0, "east": 25.0, "west": 28.0 } },
          {
            "property": "pubtime",
            "type": "datetime",
            "between": ["2026-06-08T20:00:00+00:00", "2026-06-09T05:00:59+00:00"]
          },
          {
            "property": "wigos_station_identifier",
            "type": "string",
            "in": ["0-20000-0-78338"]
          }
        ]
      },
      "action": "accept"
    },
    {
      "id": "default",
      "order": 999,
      "match": { "always": true },
      "action": "reject",
      "reason": "No filter criteria matched"
    }
  ]
}

Упражнение: Подписка с фильтром

Используйте Catalogue View, чтобы найти набор данных наблюдений за поверхностью и применить пространственный фильтр перед подпиской.

Перейдите в Catalogue View и найдите набор данных наблюдений за поверхностью по вашему выбору.
Выберите набор данных, чтобы развернуть его детали в правой панели.
В параметрах фильтра установите bounding box для региона по вашему выбору.
При необходимости установите фильтр media type, чтобы ограничить загрузку файлами BUFR.
Укажите папку назначения как filtered-obs.
Нажмите Subscribe, чтобы создать подписку.

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

Нажмите, чтобы раскрыть ответ

Только уведомления, соответствующие всем заданным условиям, будут приняты и загружены. Все остальные будут отклонены правилом по умолчанию.

Отписка и удаление загруженных файлов

Перейдите в представление Manage Subscriptions и нажмите Unsubscribe для темы, затем очистите папку загрузок:

rm -fr /home/<username>/wis2-downloads/filtered-obs

Заключение

Поздравляем!

В этом практическом занятии вы узнали, как:

находить и подписываться на наборы данных с использованием Catalogue View и Tree View
подписываться на темы напрямую с использованием представления Manual Subscribe
применять фильтры для контроля загрузки файлов из подписки
использовать аутентификацию для загрузки из наборов данных с ограниченным доступом