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

Вы можете перенести данные из Яндекс Директ в 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:

   Вручную

   Terraform

   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Перенесите данные из Яндекс Директ в Object Storage с использованием Cloud Functions

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

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

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

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

   Совет

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

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

   Вручную

   Terraform

   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Перенесите данные из Object Storage в Managed Service for ClickHouse® с использованием Data Transfer

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

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

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

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

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

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

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

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

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

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

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

     • Id : Int64;
     • Name : String.

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

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

   Вручную

   Terraform

   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. Удалите эндпоинт для источника.

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

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