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

Обзор

За три года работы в команде 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. Уровень задания предоставит вам только метаданные одного задания, давая лишь небольшой снимок части проекта.
• Административный (Admin) API
  • Обзор — Этот REST API позволяет вам оркестрировать запуски заданий dbt Cloud и помогает вам администрировать аккаунт dbt Cloud. Для получения метаданных мы рекомендуем интегрироваться с Discovery API.
• Вебхуки
  • Обзор — Исходящие вебхуки могут отправлять уведомления о ваших заданиях dbt Cloud в другие системы. Эти вебхуки позволяют вам получать последнюю информацию о ваших заданиях dbt в реальном времени.
• Семантические слои/Метрики
  • Обзор — Наш семантический слой состоит из двух частей: определения метрик и возможность интерактивного запроса метрик dbt. Для получения более подробной информации, вот основной обзор и наши лучшие практики.
  • Определения метрик могут быть получены из Discovery API (ссылка выше) или из драйвера семантического слоя/GraphQL API. Ключевое отличие в том, что Discovery API не может получить семантический граф, который предоставляет список доступных измерений, которые можно запросить для каждой метрики. Это доступно только с драйвером SL/API. Компромисс в том, что драйвер SL/API не имеет доступа к родословной всего проекта dbt (то есть, как метрики dbt зависят от моделей dbt).
  • Для API семантического слоя доступны три точки интеграции.

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

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

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

Для аутентификации мы настоятельно рекомендуем, чтобы ваша интеграция использовала токены сервисных аккаунтов. Вы можете прочитать больше о том, как создать сервисный токен и какие наборы разрешений ему предоставить. Обратите внимание, что в зависимости от их типа плана, у них будет доступ к различным наборам разрешений. Мы не рекомендуем пользователям предоставлять свои токены доступа для аутентификации. Это может вызвать проблемы, если пользователь покинет организацию и предоставит вам доступ ко всем аккаунтам 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, и их использование регулируется нашими руководствами по бренду, которые довольно специфичны для коммерческого использования. Если у вас есть вопросы о правильном использовании наших знаков, пожалуйста, спросите вашего менеджера по партнерам.
• Как я могу взаимодействовать с командой по партнерствам?
  • Напишите на partnerships@dbtlabs.com.