Перейти к основному содержимому

Как интегрироваться с dbt

· 8 мин. чтения
Amy Chen
Product Manager at dbt Labs

Обзор​

За три года работы в команде Partner Engineering в dbt Labs, самый частый вопрос, который мне задавали, это: как мы можем интегрироваться с dbt? Поскольку эти разговоры часто начинаются с одного и того же, я решил создать это руководство, чтобы больше не быть препятствием для получения основной информации. Это также позволяет нам пропустить вводную часть и быстрее перейти к интересным обсуждениям, например, как может выглядеть совместное решение для наших клиентов.

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

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

Здесь я расскажу, как начать, какие потенциальные случаи использования вы хотите решить и точки интеграции для этого.

Впервые в dbt Cloud?​

Если вы новичок в dbt и dbt Cloud, мы рекомендуем вам и вашим разработчикам программного обеспечения попробовать наши Быстрые старты после прочтения Что такое dbt. Документация поможет вам ознакомиться с тем, как наши пользователи взаимодействуют с dbt. Пройдя через это, вы также создадите пример проекта dbt для тестирования вашей интеграции.

Если вам нужен партнерский аккаунт dbt Cloud для тестирования, мы можем обновить существующий аккаунт или пробный аккаунт. Этот аккаунт может использоваться только для разработки, обучения и демонстрационных целей. Пожалуйста, свяжитесь с вашим менеджером по партнерам, если вы заинтересованы, и предоставьте идентификатор аккаунта (указан в URL). Наш партнерский аккаунт включает все функции уровня предприятия и может быть предоставлен с подписанным соглашением о партнерстве.

Точки интеграции​

  • Discovery API (ранее назывался Metadata API)
    • Обзор — Этот GraphQL API позволяет запрашивать метаданные, которые dbt Cloud генерирует при каждом запуске проекта dbt. Доступны две схемы: на уровне среды и на уровне задания. По умолчанию мы всегда рекомендуем интегрироваться со схемой уровня среды, поскольку она содержит актуальное состояние и историю результатов выполнения всех заданий проекта dbt Cloud. Схема уровня задания предоставляет метаданные только одного задания, то есть лишь небольшой снимок части проекта.
  • Административный API (Admin API)
    • Обзор — Этот REST API позволяет управлять запусками заданий dbt Cloud и администрировать учетную запись dbt Cloud. Для получения метаданных рекомендуем вместо него использовать интеграцию с Discovery API.
  • Вебхуки
    • Обзор — Исходящие вебхуки могут отправлять уведомления о ваших заданиях dbt Cloud в другие системы. Эти вебхуки позволяют получать актуальную информацию о заданиях dbt в реальном времени.
  • Семантические слои и метрики
    • Обзор — Наш Semantic Layer состоит из двух частей: определений метрик и возможности интерактивно запрашивать метрики dbt. Подробнее см. краткий обзор и наши рекомендации.
    • Определения метрик можно получить через Discovery API (ссылка выше) или драйвер Semantic Layer / GraphQL API. Ключевое отличие заключается в том, что Discovery API не позволяет получить семантический граф, который предоставляет список доступных измерений для запросов по каждой метрике. Эта возможность доступна только через драйвер/API Semantic Layer (SL). При этом драйвер/API SL не имеет доступа к графу зависимостей всего проекта dbt (то есть к информации о том, как метрики dbt зависят от моделей dbt).
    • Для API Semantic Layer доступны три варианта интеграции.

Хостинг и аутентификация dbt Cloud​

Для использования API dbt Cloud вам понадобятся URL-адреса доступа клиента. URL-адрес доступа зависит от конфигурации dbt Cloud клиента. Подробнее обо всех возможных конфигурациях см. в разделе Регионы и IP-адреса. Рекомендую дать клиенту возможность указать собственный URL-адрес, чтобы упростить поддержку.

Если клиент находится на экземпляре Azure с одним арендатором, у них в настоящее время нет доступа к Discovery API или API семантического слоя.

Для аутентификации мы настоятельно рекомендуем использовать в вашей интеграции сервисные токены аккаунта. Подробнее о том, как создать сервисный токен и какие наборы разрешений ему предоставить, можно прочитать в документации. Обратите внимание, что доступные наборы разрешений зависят от тарифного плана. Мы не рекомендуем пользователям предоставлять свои пользовательские bearer-токены для аутентификации. Это может вызвать проблемы, если пользователь покинет организацию, а также предоставит вашей интеграции доступ ко всем аккаунтам dbt Cloud, связанным с этим пользователем, а не только к тому аккаунту (и связанным с ним проектам), с которым пользователь хочет настроить интеграцию.

Потенциальные случаи использования​

  • Оркестрация на основе событий
    • Желаемое действие — Вы хотите получать информацию о завершении запланированного задания dbt Cloud или запускать задание dbt Cloud. Вы можете согласовать расписание своего продукта с расписанием запусков dbt Cloud.
    • Примеры — Запуск задания dbt после завершения задания ETL по извлечению и загрузке данных. Или получение вебхука после завершения задания для запуска задания обратного ETL.
    • Точки интеграции — Вебхуки и/или Admin API
  • Происхождение данных в dbt
    • Желаемое действие — Вы хотите встроить метаданные о происхождении данных dbt в свой инструмент.
    • Пример — Вы хотите добавить DAG dbt в диаграмму происхождения данных в своём инструменте. Подробнее о том, какие данные можно получить и как это сделать, см. в разделе Сценарии использования и примеры для Discovery API.
    • Точки интеграции — Discovery API
  • Метаданные сред и заданий dbt
    • Желаемое действие — Вы хотите встроить в свой инструмент информацию о заданиях dbt Cloud, включая статус заданий, статус таблиц, обработанных в ходе запуска, сведения об успешно пройденных тестах и т. д.
    • Пример — В вашем инструменте бизнес-аналитики заинтересованные пользователи выбирают данные из таблиц, созданных моделью dbt. Вы показываете время последнего успешного прохождения тестов модели и её последнего запуска, чтобы продемонстрировать, что таблицы актуальны и им можно доверять. Подробнее о том, какие данные можно получить и как это сделать, см. в разделе Каково последнее состояние каждой модели.
    • Точки интеграции — Discovery API
  • Документация моделей dbt
    • Желаемое действие — Вы хотите встроить информацию о проекте dbt, включая описания моделей, описания столбцов и т. д.
    • Пример — Вы хотите извлечь описание модели dbt, чтобы отобразить его и помочь заинтересованным пользователям понять, из каких данных они делают выборку. Таким образом, авторы могут легко передавать информацию, не обновляя её в другой системе. Подробнее о том, какие данные можно получить и как это сделать, см. в разделе Что означают этот набор данных и его столбцы.
    • Точки интеграции — Discovery API

Пользователи только dbt Core не будут иметь доступа к вышеуказанным точкам интеграции. Для метаданных dbt наши партнеры часто создают интеграцию dbt Core, используя артефакты dbt, создаваемые при каждом запуске и предоставляемые пользователем. С Discovery API мы предоставляем динамический способ получения последней информации, разобранной для вас.

Планы и разрешения dbt Cloud​

Тип плана dbt Cloud изменит, к чему пользователь имеет доступ. Существует четыре различных типа планов:

  • Разработчик — Это бесплатно и доступно для одного пользователя с ограниченным количеством успешно построенных моделей. Этот план не может получить доступ к API, вебхукам или семантическому слою и ограничен только одним проектом.
  • Команда — Этот план предоставляет доступ к API, вебхукам и семантическому слою. Вы можете иметь до восьми пользователей в аккаунте и один проект dbt Cloud. Это ограничено 15,000 успешно построенных моделей.
  • Предприятие (мультиарендатор/мультиклетка) — Этот план предоставляет доступ к API, вебхукам и семантическому слою. Вы можете иметь более одного проекта dbt Cloud в зависимости от того, сколько проектов/доменов dbt они используют. Большинство наших корпоративных клиентов находятся на мультиарендаторских экземплярах dbt Cloud.
  • Предприятие (одинарный арендатор): Этот план может иметь доступ к API, вебхукам и семантическому слою. Если вы работаете с конкретным клиентом, дайте нам знать, и мы можем подтвердить, есть ли у их экземпляра доступ.

Часто задаваемые вопросы​

  • Что такое проект dbt Cloud?
    • Проект dbt Cloud состоит из двух подключений: одно к репозиторию Git и одно к хранилищу данных/платформе. Большинство клиентов будут иметь только один проект dbt Cloud в своем аккаунте, но есть корпоративные клиенты, у которых может быть больше в зависимости от их случаев использования. Проект также включает два типа окружений как минимум: среду разработки и среду развертывания.
    • Люди часто называют проект dbt кодом, размещенным в их репозитории Git.
  • Что такое окружение dbt Cloud?
    • Для обзора ознакомьтесь с О окружениях. Минимум, проект будет иметь одну среду типа развертывания, на которой они будут выполнять задания. Среда разработки поддерживает IDE dbt Cloud и Cloud CLI.
  • Можем ли мы записывать обратно в проект dbt?
    • На данный момент у нас нет Write API. Проект dbt размещен в репозитории Git, поэтому, если у вас есть интеграция с провайдером Git, вы можете вручную открыть pull request (PR) в проекте для поддержания процесса контроля версий.
  • Можете ли вы предоставить информацию на уровне столбцов в родословной?
    • Родословная на уровне столбцов в настоящее время находится в бета-версии, и будет предоставлена дополнительная информация.
  • Как я могу получить партнерский аккаунт?
    • Свяжитесь с вашим менеджером по партнерам с вашим идентификатором аккаунта (в вашем URL).
  • Почему я не должен использовать Admin API для извлечения артефактов dbt для метаданных?
    • Мы рекомендуем не интегрироваться с Admin API для извлечения документации артефактов dbt. Это связано с тем, что Discovery API предоставляет более обширную информацию, удобную структуру и более надежную точку интеграции.
  • Как я могу получить доступ к брендовым активам dbt?
    • Ознакомьтесь с нашей страницей Руководство по бренду. Пожалуйста, убедитесь, что вы не используете наш старый логотип (подсказка: в логотипе должна быть только одна дырка). Также обратите внимание, что название dbt и логотип dbt являются товарными знаками dbt Labs, и их использование регулируется нашими руководствами по бренду, которые довольно специфичны для коммерческого использования. Если у вас есть вопросы о правильном использовании наших знаков, пожалуйста, спросите вашего менеджера по партнерам.
  • Как я могу взаимодействовать с командой по партнерствам?