Связаться с намиПодключиться

Загрузка данных из Яндекс Директ в витрину Yandex Managed Service for ClickHouse® с использованием Yandex Cloud Functions, Yandex Object Storage и Yandex Data Transfer

Статья создана
Обновлена 2 декабря 2024 г.

Важно

Часть ресурсов, необходимых для прохождения практического руководства, доступны только в регионе Россия.

Вы можете перенести данные из Яндекс Директ в Managed Service for ClickHouse® с использованием сервисов Cloud Functions, Object Storage и Data Transfer. Для этого:

  1. Перенесите данные из Яндекс Директ в Object Storage с использованием Cloud Functions.
  2. Перенесите данные из Object Storage в Managed Service for ClickHouse® с использованием Data Transfer.

Если созданные ресурсы вам больше не нужны, удалите их.

Перед началом работы

  1. Подготовьте тестовые данные для выгрузки из Яндекс Директ:

    1. Зарегистрируйте тестовое приложение в сервисе Яндекс.OAuth.

      В качестве платформы выберите Веб-сервисы, а в поле Redirect URI вставьте URL для отладки: https://oauth.yandex.ru/verification_code.

    2. Получите отладочный токен для приложения.

    3. Создайте заявку на тестовый доступ приложения к Яндекс Директ и дождитесь ее одобрения.

    4. Включите песочницу в Яндекс Директ с ролью Клиент.

    5. (Опционально) Убедитесь, что все настроено верно, отправив запрос к API песочницы от имени приложения:

      Пример запроса
      curl \
  --header 'Authorization: Bearer <отладочный_токен>' \
  --header 'Accept-Language: en' \
  --data '
      {
        "method":"get",
        "params": {
          "SelectionCriteria": {},
          "FieldNames": [
            "Id",
            "Name"
          ]
        }
      }' \
  "https://api-sandbox.direct.yandex.com/json/v5/campaigns" | jq
      Пример ответа
      {
  "result": {
    "Campaigns": [
      {
          "Id": 463476,
          "Name": "Test API Sandbox campaign 1"
      },
      {
          "Id": 463477,
          "Name": "Test API Sandbox campaign 2"
      },
      {
          "Id": 463478,
          "Name": "Test API Sandbox campaign 3"
      }
    ]
  }
}

  2. Подготовьте инфраструктуру Yandex Cloud:

    1. Создайте сервисный аккаунт с именем storage-lockbox-sa и назначьте ему роли storage.uploader и lockbox.payloadViewer.

    2. Создайте статический ключ доступа для сервисного аккаунта storage-lockbox-sa.

    3. Создайте секрет в Yandex Lockbox с тремя парами ключ:значение:

      • access_key:<открытый_ключ>;
      • secret_key:<закрытый_ключ>;
      • app_token:<отладочный_токен_приложения>.

    4. В Object Storage создайте бакет.

    5. Создайте кластер Managed Service for ClickHouse® любой подходящей конфигурации с хостами в публичном доступе.

    6. Если вы используете группы безопасности в кластере Managed Service for ClickHouse®, убедитесь, что они настроены правильно и допускают подключение к нему.

    1. Если у вас еще нет Terraform, установите его.

    2. Получите данные для аутентификации. Вы можете добавить их в переменные окружения или указать далее в файле с настройками провайдера.

    3. Настройте и инициализируйте провайдер. Чтобы не создавать конфигурационный файл с настройками провайдера вручную, скачайте его.

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

    5. Скачайте в ту же рабочую директорию файл конфигурации ya-direct-to-mch.tf.

      В этом файле описаны:

      • сеть;
      • подсеть;
      • группа безопасности и правила, необходимые для подключения к кластеру Managed Service for ClickHouse®;
      • сервисный аккаунт с ролями storage.uploader и lockbox.payloadViewer.
      • статический ключ для сервисного аккаунта;
      • секрет Yandex Lockbox;
      • бакет Object Storage;
      • бессерверная функция Cloud Functions;
      • кластер-приемник Managed Service for ClickHouse®;
      • эндпоинт для приемника Managed Service for ClickHouse®;
      • трансфер.

    6. Укажите в файле ya-direct-to-mch.tf переменные:

      • folder_id — идентификатор облачного каталога, такой же как в настройках провайдера.
      • app_token — отладочный токен приложения.
      • bucket_name — имя бакета Object Storage. Имя должно быть уникальным в сервисе.
      • ch_password — пароль пользователя-администратора кластера Managed Service for ClickHouse®.

    7. Проверьте корректность файлов конфигурации Terraform с помощью команды:

      terraform validate

      Если в файлах конфигурации есть ошибки, Terraform на них укажет.

    8. Создайте необходимую инфраструктуру:

      1. Выполните команду для просмотра планируемых изменений:

        terraform plan

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

      2. Если вас устраивают планируемые изменения, внесите их:

        1. Выполните команду:

          terraform apply

        2. Подтвердите изменение ресурсов.

        3. Дождитесь завершения операции.

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

Перенесите данные из Яндекс Директ в Object Storage с использованием Cloud Functions

  1. Скачайте архив example-py.zip с кодом функции на Python.

    Функция запрашивает идентификаторы и имена рекламных кампаний из песочницы, используя токен приложения, затем конвертирует эти данные в формат Parquet и помещает в бакет Object Storage.

    Функция принимает на вход:

    • ключ сервисного аккаунта;
    • токен приложения;
    • имя бакета.

    Совет

    Вы можете использовать эту функцию для получения данных из реальных рекламных кампаний или выполнения запросов от имени рекламного агентства. Для этого распакуйте архив и раскомментируйте необходимые параметры в файле example.py. Подробности см. в комментариях к коду.

  2. Создайте и настройте функцию в сервисе Cloud Functions:

    1. Создайте функцию.

    2. В открывшемся редакторе выберите среду выполнения Python и нажмите Продолжить.

    3. Укажите необходимые настройки:

      • ZIP-архив — ZIP-архив.

      • Файл — выберите скачанный ранее архив example-py.zip.

      • Точка входа — example.foo.

      • Сервисный аккаунт — выберите из списка storage-lockbox-sa.

      • Переменные окружения — передайте имя бакета в формате ключ=значение:

        • Ключ — BUCKET.
        • Значение — имя созданного ранее бакета (без префикса s3://).

      • Секреты Lockbox — укажите путь к трем ранее созданным секретам Yandex Lockbox в переменных окружения:

        • AWS_ACCESS_KEY_ID — access_key;
        • AWS_SECRET_ACCESS_KEY — secret_key;
        • TOKEN — app_token.

      Остальные настройки можно оставить по умолчанию.

    4. Нажмите Сохранить изменения и дождитесь завершения сборки.

    1. Укажите в файле ya-direct-to-mch.tf переменные:

      • path_to_zip_cf — путь к скачанному ZIP-архиву с кодом функции;
      • create_function — значение 1 для создания функции.

    2. Проверьте корректность файлов конфигурации Terraform с помощью команды:

      terraform validate

      Если в файлах конфигурации есть ошибки, Terraform на них укажет.

    3. Создайте необходимую инфраструктуру:

      1. Выполните команду для просмотра планируемых изменений:

        terraform plan

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

      2. Если вас устраивают планируемые изменения, внесите их:

        1. Выполните команду:

          terraform apply

        2. Подтвердите изменение ресурсов.

        3. Дождитесь завершения операции.

  3. Откройте созданную функцию в консоли управления и выберите Функции на панели слева.

  4. Нажмите Запустить тест и дождитесь выполнения функции.

В бакете появится файл в формате Parquet.

Перенесите данные из Object Storage в Managed Service for ClickHouse® с использованием Data Transfer

  1. Создайте эндпоинт для источника со следующими параметрами:

    • Тип базы данных — Object Storage.

    • Бакет — имя бакета в Object Storage.

    • Идентификатор ключа доступа AWS — открытая часть статического ключа сервисного аккаунта. Можно скопировать из секрета Yandex Lockbox.

    • Секретный ключ доступа AWS — закрытая часть статического ключа сервисного аккаунта. Можно скопировать из секрета Yandex Lockbox.

    • Эндпоинт — https://storage.yandexcloud.kz.

    • Регион — ru-central1.

    • Формат данных — Parquet.

    • Схема — {"Id": "int64", "Name": "string"}.

    • Таблица — имя Parquet-файла в бакете, например: ac05e4fe818e463f88a8a299d290734d.snappy.parquet.

    • Схема результирующей таблицы — выберите Вручную и укажите имена полей и тип данных:

      • Id : Int64;
      • Name : String.

    Остальные параметры оставьте по умолчанию.

  2. Создайте эндпоинт для приемника и трансфер:

    1. Создайте эндпоинт для приемника Managed Service for ClickHouse®, указав параметры созданного ранее кластера.

    2. Создайте трансфер, использующий созданные эндпоинты.

    1. Укажите в файле ya-direct-to-mch.tf переменные:

      • source_endpoint_id — идентификатор эндпоинта-источника;
      • transfer_enabled — значение 1 для создания трансфера.

    2. Проверьте корректность файлов конфигурации Terraform с помощью команды:

      terraform validate

      Если в файлах конфигурации есть ошибки, Terraform на них укажет.

    3. Создайте необходимую инфраструктуру:

      1. Выполните команду для просмотра планируемых изменений:

        terraform plan

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

      2. Если вас устраивают планируемые изменения, внесите их:

        1. Выполните команду:

          terraform apply

        2. Подтвердите изменение ресурсов.

        3. Дождитесь завершения операции.

  3. Активируйте трансфер и дождитесь его перехода в статус Завершен.

  4. Убедитесь, что в базу данных Managed Service for ClickHouse® перенесены данные из источника Object Storage:

    1. Подключитесь к кластеру с помощью clickhouse-client.

    2. Выполните запрос:

      SELECT * FROM ac05e4fe818e463f88a8a299d290734d_snappy_parquet;

      Где ac05e4fe818e463f88a8a299d290734d — имя Parquet-файла.

      Пример ответа
      ┌─────Id─┬─Name────────────────────────┬─__file_name─────────────────────────────────────┬─__row_index─┐
│ 463476 │ Test API Sandbox campaign 1 │ ac05e4fe818e463f88a8a299d290734d.snappy.parquet │           1 │
│ 463477 │ Test API Sandbox campaign 2 │ ac05e4fe818e463f88a8a299d290734d.snappy.parquet │           2 │
│ 463478 │ Test API Sandbox campaign 3 │ ac05e4fe818e463f88a8a299d290734d.snappy.parquet │           3 │
└────────┴─────────────────────────────┴─────────────────────────────────────────────────┴─────────────┘

Удалите созданные ресурсы

Некоторые ресурсы платные. Чтобы за них не списывалась плата, удалите ресурсы, которые вы больше не будете использовать:

  1. Удалите трансфер.
  2. Удалите эндпоинт для источника.
  3. Удалите объекты из бакета.

Остальные ресурсы удалите в зависимости от способа их создания:

  1. В терминале перейдите в директорию с планом инфраструктуры.

    Важно

    Убедитесь, что в директории нет Terraform-манифестов с ресурсами, которые вы хотите сохранить. Terraform удаляет все ресурсы, которые были созданы с помощью манифестов в текущей директории.

  2. Удалите ресурсы:

    1. Выполните команду:

      terraform destroy

    2. Подтвердите удаление ресурсов и дождитесь завершения операции.

    Все ресурсы, которые были описаны в Terraform-манифестах, будут удалены.

ClickHouse® является зарегистрированным товарным знаком ClickHouse, Inc.

Предыдущая
Хранение статического ключа доступа в секрете Yandex Lockbox
Следующая
Развертывание отказоустойчивой архитектуры с прерываемыми ВМ