Загрузка с помощью 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 в левой боковой панели.

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

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

Используйте фильтры в режиме Catalogue View, чтобы найти 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, начиная с корня иерархии и углубляясь. Это контрастирует с Catalogue View, который сразу направляет вас к отдельным записям наборов данных и лучше подходит, если вы уже знаете, что ищете.

Перейдите в Tree View в левой боковой панели.

WIS2 Downloader Tree View

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

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

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

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

Подпишитесь на набор данных через Tree View

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

Разверните дерево, начиная с узла 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. В отличие от режимов Catalogue View и Tree View, которые оба получают свои темы из 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, необходимо добавить подписчика в файл конфигурации 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.
Введите токен доступа (bearer token), сгенерированный на Шаге 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
применять фильтры для управления загрузкой файлов из подписки
использовать аутентификацию для загрузки из наборов данных с контролируемым доступом

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

Введение

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

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

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

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

Использование режима Manual Subscribe

Загрузка из защищённого набора данных

Упражнение: подписка на защищённый набор данных на вашем wis2box

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

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

Заключение