(Версии dbt: v2.0 и новее) # Подключение BigQuery к dbt v2 Локальная разработка Вы можете настроить адаптер BigQuery, выполнив `dbt init` в CLI или вручную создав файл `profiles.yml` с полями, настроенными для выбранного типа аутентификации. Адаптер BigQuery для dbt v2 поддерживает следующие [методы аутентификации](#supported-authentication-types): * Сервисный аккаунт (JSON-файл) * gcloud OAuth * Workload Identity Federation (Microsoft Entra) ## Разрешения для хранилища данных Удостоверение Google Cloud (сервисный аккаунт или пользователь), которое использует dbt v2, должно иметь разрешения IAM для запуска заданий, чтения и записи данных таблиц, а также чтения метаданных, которые dbt v2 использует для интроспекции и проверки актуальности источников. ### Необходимые объекты Google Cloud Перед подключением следующие объекты должны существовать или быть доступны: | Объект | Термин BigQuery | Назначение | | -------------------------------------- | ----------------- | -------------------------------------------------------- | | **Проект** | Проект GCP | Идентификатор вашего проекта Google Cloud | | **Набор данных** | Набор данных | Целевой набор данных (эквивалент схемы) | | **Сервисный аккаунт или пользователь** | Удостоверение IAM | Удостоверение для аутентификации | | **Местоположение или регион** | Местоположение | Местоположение данных (например, `US`, `EU`, `us-east1`) | ### Разрешения IAM Для основных функций dbt необходимы следующие разрешения: | Разрешение | Назначение | | ---------------------------- | -------------------------------------------- | | `bigquery.datasets.get` | Доступ к метаданным набора данных | | `bigquery.tables.create` | Создание таблиц | | `bigquery.tables.delete` | Удаление или замена таблиц | | `bigquery.tables.get` | Чтение метаданных таблиц | | `bigquery.tables.getData` | Чтение данных таблиц | | `bigquery.tables.list` | Получение списка таблиц в наборе данных | | `bigquery.tables.update` | Обновление схемы таблицы | | `bigquery.tables.updateData` | Вставка, обновление или удаление строк | | `bigquery.routines.get` | Чтение метаданных подпрограмм | | `bigquery.routines.list` | Получение списка подпрограмм в наборе данных | | `bigquery.jobs.create` | Выполнение запросов | Следующие разрешения необязательны и нужны для дополнительных функций dbt: | Разрешение | Когда требуется | | -------------------------- | -------------------------------------------- | | `bigquery.datasets.create` | Автоматическое создание наборов данных | | `bigquery.routines.create` | Создание UDF или хранимых процедур | | `bigquery.jobs.get` | Отслеживание статуса заданий | | `storage.objects.create` | Модели Python (промежуточное хранение в GCS) | | `dataproc.*` | Модели Python в Dataproc | #### Предопределённые роли IAM Следующие роли обычно служат отправной точкой при настройке доступа для dbt: | Роль | Описание | Сценарий использования | | --------------------------- | --------------------------------------- | ----------------------------------------- | | `roles/bigquery.dataEditor` | Чтение и запись таблиц в наборах данных | Стандартные операции dbt | | `roles/bigquery.user` | Запуск заданий, создание наборов данных | Выполнение заданий | | `roles/bigquery.jobUser` | Только запуск заданий | Минимальные права для выполнения запросов | Для доступа к Storage Read API с помощью dbt v2 также предоставьте роль **BigQuery Read Session User** (`roles/bigquery.readSessionUser`) на уровне проекта, как указано в разделе [Подключение BigQuery](https://docs.getdbt.tech/docs/platform/connect-data-platform/connect-bigquery.md#required-permissions). ### Операции с метаданными Для основных функций dbt необходимы следующие операции: | Тип запроса | Используемый SQL или API | Необходимое разрешение | | -------------------------------- | -------------------------------- | ------------------------------------------------ | | Получение схемы таблицы | API `get_table_schema` | `bigquery.tables.get` | | Получение списка отношений | Запрос к набору данных | `bigquery.tables.list`, `bigquery.routines.list` | | Проверка актуальности источников | Запрос к метаданным `__TABLES__` | `bigquery.tables.get` | | Получение статистики таблицы | Запрос к `INFORMATION_SCHEMA` | `bigquery.tables.get` | | Создание набора данных | `CREATE SCHEMA` | `bigquery.datasets.create` | ### INFORMATION\_SCHEMA и представления метаданных dbt v2 выполняет запросы к следующим системным представлениям BigQuery: | Представление | Назначение | Область действия | | ------------------------------- | ------------------------- | ----------------------- | | `INFORMATION_SCHEMA.TABLES` | Получение списка таблиц | Набор данных или регион | | `INFORMATION_SCHEMA.COLUMNS` | Метаданные столбцов | Набор данных или регион | | `INFORMATION_SCHEMA.VIEWS` | Определения представлений | Набор данных или регион | | `INFORMATION_SCHEMA.PARTITIONS` | Информация о секциях | Только набор данных | | `__TABLES__` (устарело) | Время изменения таблиц | Набор данных | ### BigQuery DataFrames (необязательно) Для рабочих процессов BigQuery DataFrames пользователям обычно требуются дополнительные роли, такие как `BigQuery Job User`, `BigQuery Read Session User`, `Notebook Runtime User`, `Code Creator` и `colabEnterpriseUser`. Точные названия ролей в вашей организации уточните у администратора Google Cloud. ## Настройка dbt v2 При выполнении `dbt init` в CLI вам будет предложено заполнить следующие поля: * **Project ID:** Идентификатор проекта BigQuery в GCP * **Dataset:** Имя схемы * **Location:** Расположение вашей среды GCP (например, us-east1) Кроме того, вы можете вручную создать файл `profiles.yml` и настроить его поля. Примеры форматирования приведены в разделе [аутентификации](#supported-authentication-types). Если файл `profiles.yml` уже существует, вы можете сохранить существующие поля или перезаписать их. Затем выберите метод аутентификации. Следуйте инструкциям на экране, чтобы указать необходимые сведения. ## Поддерживаемые типы аутентификации ### Service account (JSON file) При выборе типа аутентификации **Service account (JSON file)** вам будет предложено указать путь к JSON-файлу. Вы также можете вручную задать этот путь в файле `profiles.yml`. #### Пример настройки сервисного аккаунта с использованием JSON-файла profiles.yml ```yml default: target: dev outputs: dev: type: bigquery threads: 16 database: ABC123 schema: JAFFLE_SHOP method: service-account keyfile: /Users/youruser/Downloads/CustomRoleDefinition.json location: us-east1 dataproc_batch: null ``` ### gcloud OAuth Перед выбором этого метода аутентификации необходимо настроить локальную аутентификацию OAuth для gcloud: #### Настройка локальной аутентификации OAuth для gcloud 1. Убедитесь, что команда `gcloud` [установлена на вашем компьютере](https://cloud.google.com/sdk/downloads). 2. Активируйте учётную запись для учётных данных приложения по умолчанию: ```shell gcloud auth application-default login \ --scopes=https://www.googleapis.com/auth/bigquery,\ https://www.googleapis.com/auth/drive.readonly,\ https://www.googleapis.com/auth/iam.test,\ https://www.googleapis.com/auth/cloud-platform # Эта команда использует флаг `--scopes` для запроса доступа к Google Sheets. Это позволяет преобразовывать данные в Google Sheets с помощью dbt. Если ваш проект dbt не преобразует данные в Google Sheets, флаг `--scopes` можно опустить. ``` Должно открыться окно браузера с предложением войти в ваш аккаунт Google. После входа dbt будет использовать ваши учётные данные OAuth для подключения к BigQuery. #### Пример настройки gcloud profiles.yml ```yml default: target: dev outputs: dev: type: bigquery threads: 16 database: ABC123 schema: JAFFLE_SHOP method: oauth location: us-east1 dataproc_batch: null ``` ### Workload Identity Federation (Microsoft Entra) Workload Identity Federation (WIF) позволяет проходить аутентификацию в BigQuery с помощью учётных данных, выданных внешним поставщиком удостоверений OAuth — в настоящее время Microsoft Entra — без необходимости управлять файлом ключа сервисного аккаунта Google. dbt v2 обменивает токен, выданный Entra, на краткосрочные учётные данные Google через [пул удостоверений рабочих нагрузок](https://docs.cloud.google.com/iam/docs/workload-identity-federation#pools) Google Cloud. Перед выбором этого метода администратор должен настроить в GCP пул удостоверений рабочих нагрузок и поставщика, который доверяет вашему тенанту Entra. Вам потребуется полученный путь к поставщику пула удостоверений рабочих нагрузок. #### Поля конфигурации Ниже приведены обязательные и необязательные поля для настройки WIF в файле `profiles.yml`: | Поле | Обязательное | Описание | | ----------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `method` | Да | Укажите `external-oauth-wif`. | | `workload_pool_provider_path` | Да | Полный путь к ресурсу поставщика пула удостоверений рабочих нагрузок GCP, который доверяет вашему тенанту Entra. | | `token_endpoint.type` | Да | Тип внешнего поставщика удостоверений. В настоящее время поддерживается только `entra`. | | `token_endpoint.request_url` | Да | Конечная точка OAuth в Entra для получения токена. | | `token_endpoint.request_data` | Да | Тело запроса в формате URL-кодирования, используемое для получения токена Entra (например, `grant_type`, `client_id`, `client_secret` и `scope`). | | `service_account_impersonation_url` | Нет | URL `generateAccessToken` сервисного аккаунта, от имени которого нужно действовать после федерации, если требуется ограничить доступ к BigQuery разрешениями этого сервисного аккаунта. | #### Пример настройки WIF в `profiles.yml` В следующем фрагменте кода приведён пример настройки WIF в файле `profiles.yml`. Обязательно замените значения на свои: profiles.yml ```yaml default: target: dev outputs: dev: type: bigquery threads: 16 database: ABC123 schema: JAFFLE_SHOP method: external-oauth-wif location: us-east1 workload_pool_provider_path: //iam.googleapis.com/projects/123/locations/global/workloadIdentityPools/my-pool/providers/my-provider token_endpoint: type: entra request_url: https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/token request_data: "grant_type=client_credentials&client_id={{ env_var('ENTRA_CLIENT_ID') }}&client_secret={{ env_var('ENTRA_CLIENT_SECRET') }}&scope=SCOPE/.default" # Необязательно: добавляйте только в том случае, если ваш пул удостоверений рабочих нагрузок не имеет прямого доступа к ресурсам и должен действовать от имени сервисного аккаунта. # service_account_impersonation_url: https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/sa@project.iam.gserviceaccount.com:generateAccessToken ``` ## Дополнительная информация Сведения о настройках, специфичных для BigQuery, приведены в [справочном руководстве по адаптеру BigQuery](https://docs.getdbt.tech/reference/resource-configs/bigquery-configs.md).