# Файл dbt\_cloud.yml

Платформа dbt

Файл `dbt_cloud.yml` хранит учётные данные, которые инструменты dbt — такие как [dbt platform CLI](https://docs.getdbt.tech/docs/platform/dbt-cli-installation.md), [расширение dbt для VS Code](https://docs.getdbt.tech/docs/about-dbt-extension.md) и другие — используют для аутентификации в dbt platform. Вы можете скачать его из dbt platform и сохранить локально в каталоге `.dbt`.

На этой странице описаны:

* [Скачивание файла и настройка каталога `.dbt`](#download-dbt_cloudyml) для dbt platform CLI или расширения для VS Code
* [Обновление или переключение проектов](#update-or-switch-projects)
* [Структура файла](#file-structure) и справочник полей
* [Сопутствующий блок `dbt-cloud`](#the-dbt-cloud-block-in-dbt_projectyml) в `dbt_project.yml`

Храните этот файл в безопасности

Файл `dbt_cloud.yml` содержит ключи API. Храните его в безопасном месте и убедитесь, что вы *не добавляете* его в систему контроля версий.

## Скачивание dbt\_cloud.yml

Способ скачивания файла зависит от того, настраиваете ли вы [dbt platform CLI](https://docs.getdbt.tech/docs/platform/dbt-cli-installation.md) или [расширение dbt для VS Code](https://docs.getdbt.tech/docs/about-dbt-extension.md). Скачанный файл `dbt_cloud.yml` содержит ваш [персональный токен доступа (PAT)](https://docs.getdbt.tech/docs/dbt-apis/user-tokens.md).

1. В dbt platform выберите проект, с которым хотите работать. Для проекта уже должна быть настроена [среда разработки](https://docs.getdbt.tech/docs/dbt-platform-environments.md#create-a-development-environment).
2. Перейдите в **Account settings** → **Your profile**, затем выполните действия для своего инструмента:

* dbt platform CLI: перейдите в **CLI** → **Configure Cloud authentication** и нажмите **Download CLI configuration file**.
* Расширение dbt для VS Code: перейдите в **VS Code Extension** → **Set up your credentials** и нажмите **Download credentials**.

3. Переместите файл в каталог `.dbt`. Если у вас ещё нет такого каталога, воспользуйтесь одним из следующих вариантов быстрой настройки (одной командой):

   ### Mac / Linux

   ```bash
   mkdir -p ~/.dbt && mv ~/Downloads/dbt_cloud.yml ~/.dbt/dbt_cloud.yml
   ```

   ### Windows

   ```powershell
   mkdir %USERPROFILE%\.dbt 2>nul & move %USERPROFILE%\Downloads\dbt_cloud.yml %USERPROFILE%\.dbt\dbt_cloud.yml
   ```

    Создание и перемещение каталога .dbt вручную

   Если у вас ещё нет директории `.dbt`, рекомендуется выполнить следующие шаги, чтобы создать её. Если директория `.dbt` у вас уже есть, переместите файл `dbt_cloud.yml` внутрь неё. Ниже приведена справочная информация о директории `.dbt`:

   * Директория `.dbt` — это скрытая папка в корне вашей файловой системы. Она используется для хранения конфигурационных файлов dbt. Префикс `.` делает папку скрытой, поэтому по умолчанию она не отображается в Finder или File Explorer.
   * Чтобы увидеть скрытые файлы и папки, нажмите Command + Shift + G на macOS или Ctrl + Shift + G на Windows. Это откроет диалог «Go to Folder», в котором можно перейти к директории `.dbt`.

   ### Создать каталог .dbt

   1. Клонируйте репозиторий вашего проекта dbt на локальный компьютер.
   2. Используйте команду `mkdir`, указав после неё имя папки, которую хотите создать.

   * Если вы используете macOS, добавьте префикс `~`, чтобы создать папку `.dbt` в корне вашей файловой системы:

     * macOS: `mkdir ~/.dbt`
     * Windows: `mkdir %USERPROFILE%\.dbt`

   ### Переместить файл dbt\_cloud.yml

   Вы можете переместить файл `dbt_cloud.yml` в директорию `.dbt`, используя команду `mv`, либо просто перетащить файл мышью в папку `.dbt`, открыв папку Downloads через диалог «Go to Folder» и воспользовавшись drag-and-drop в интерфейсе.

   Чтобы переместить файл с помощью терминала, используйте команду `mv` (или `move` в Windows). Эта команда перемещает `dbt_cloud.yml` из папки `Downloads` в папку `.dbt`. Если файл `dbt_cloud.yml` находится в другом месте, скорректируйте путь соответствующим образом.

   #### Mac или Linux

   В командной строке используйте команду `mv`, чтобы переместить файл `dbt_cloud.yml` в директорию `.dbt`. Если вы только что скачали файл `dbt_cloud.yml` и он находится в папке Downloads, команда может выглядеть так:

   ```bash
   mv ~/Downloads/dbt_cloud.yml ~/.dbt/dbt_cloud.yml
   ```

   #### Windows

   В командной строке используйте команду `move`. Если предположить, что файл находится в папке Downloads, команда может выглядеть следующим образом:

   ```bash
   move %USERPROFILE%\Downloads\dbt_cloud.yml %USERPROFILE%\.dbt\dbt_cloud.yml
   ```

   Если имя скачанного файла содержит числовой суффикс (например, `dbt_cloud(2).yml`), переименуйте его в `dbt_cloud.yml` перед перемещением. dbt platform CLI и расширение ищут файл только с этим точным именем.

4. Убедитесь, что `project-id` в [блоке `dbt-cloud` файла `dbt_project.yml`](#the-dbt-cloud-block-in-dbt_projectyml) соответствует проекту, с которым вы работаете. Это регистрирует ваш инструмент, подключает его к dbt platform и позволяет использовать такие возможности платформы, как Mesh и отложенное разрешение ссылок (deferral).

## Обновление или переключение проектов

Файл `dbt_cloud.yml` хранится локально на вашем компьютере и не обновляется автоматически. Обязательно скачивайте его заново в следующих случаях:

* Вы получили доступ к новому проекту и хотите работать с ним локально
* Проект удалён из вашей учётной записи или ваши права доступа к проекту изменились
* Ваш токен изменён или заменён в рамках ротации
* Хост вашей учётной записи изменился, например при переносе учётной записи в другой регион

Файл может содержать несколько проектов из одной учётной записи dbt platform. Чтобы переключиться на другой проект, укажите в `context.active-project` значение `project-id` нужного проекта. Активный проект должен соответствовать одному из проектов, перечисленных в `projects`.

Если вы работаете с несколькими учётными записями dbt platform, храните отдельный файл `dbt_cloud.yml` для каждой учётной записи и перемещайте нужный файл в каталог `.dbt`.

## Структура файла

Файл `dbt_cloud.yml` имеет следующую структуру:

dbt\_cloud.yml

```yaml
version: "1"
context:
  active-host: your_active_host       # for example, "abc123.us1.dbt.com"
  active-project: your_project_id     # for example, "123456"
projects:
  - project-name: your_project_name
    project-id: your_project_id
    account-name: your_account_name
    account-id: your_account_id
    account-host: your_account_host   # for example, "abc123.us1.dbt.com"
    token-name: your_token_name       # for example, "cloud-cli-1234"
    token-value: your_token_value

  - project-name: your_project_name
    project-id: your_project_id
    account-name: your_account_name
    account-id: your_account_id
    account-host: your_account_host
    token-name: your_token_name
    token-value: your_token_value
```

Например, если у вас есть учётная запись Jaffle and wizard shop, ваш файл `dbt_cloud.yml` будет выглядеть следующим образом:

dbt\_cloud.yml

```yaml
version: "1"
context:
  active-host: "abc123.us1.dbt.com"
  active-project: "123456"
projects:
  - project-name: "Project 1"
    project-id: "123"
    account-name: "Jaffle and wizard shop" 
    account-id: "1"
    account-host: "abc123.us1.dbt.com"
    token-name: "cloud-cli-1091"
    token-value: "dbtu_token_value"            # this would be a longer token value
  - project-name: "Project 2"
    project-id: "456"
    account-name: "Jaffle and wizard shop"
    account-id: "1"
    account-host: "abc123.us1.dbt.com"
    token-name: "cloud-cli-1091"
    token-value: "dbtu_token_value"
  - project-name: "Project 3"
    project-id: "789"
    account-name: "Jaffle and wizard shop"
    account-id: "1"
    account-host: "abc123.us1.dbt.com"
    token-name: "cloud-cli-1091"
    token-value: "dbtu_token_value"
```

### Справочник полей

| Поле                     | Обязательное | Описание                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `version`                | Да           | Версия схемы файла. В настоящее время — `"1"`.                                                                                                                                                                                                                                                                                                                                       |
| `context.active-host`    | Да           | Значение `account-host`, используемое по умолчанию. Его можно найти на странице **Account settings**.                                                                                                                                                                                                                                                                                |
| `context.active-project` | Да           | Значение `project-id` проекта, используемого по умолчанию при выполнении команд. Должно совпадать с одним из значений `project-id`, перечисленных в `projects`.                                                                                                                                                                                                                      |
| `context.defer-env-id`   | Нет          | Идентификатор среды, из которой следует использовать артефакты сборки при отложенном разрешении ссылок. Необязательное переопределение среды отложенного разрешения ссылок, заданной для проекта по умолчанию. Только для dbt platform CLI. См. [Настройка отложенного разрешения ссылок](https://docs.getdbt.tech/docs/platform/about-defer.md#configure-deferral-environment-id). |
| `projects.project-name`  | Да           | Понятное человеку название проекта.                                                                                                                                                                                                                                                                                                                                                  |
| `projects.project-id`    | Да           | Идентификатор проекта в dbt platform. Его можно найти в URL при просмотре проекта (например, `…/projects/123456`).                                                                                                                                                                                                                                                                   |
| `projects.account-name`  | Да           | Понятное человеку название учётной записи.                                                                                                                                                                                                                                                                                                                                           |
| `projects.account-id`    | Да           | Идентификатор учётной записи в dbt platform.                                                                                                                                                                                                                                                                                                                                         |
| `projects.account-host`  | Да           | Хост вашей учётной записи, например `cloud.getdbt.com`, `emea.dbt.com` или URL доступа к вашему однопользовательскому экземпляру (single-tenant).                                                                                                                                                                                                                                    |
| `projects.token-name`    | Да           | Имя [персонального токена доступа (PAT)](https://docs.getdbt.tech/docs/dbt-apis/user-tokens.md).                                                                                                                                                                                                                                                                                    |
| `projects.token-value`   | Да           | Значение PAT. Обращайтесь с ним как с секретом.                                                                                                                                                                                                                                                                                                                                      |

## Блок dbt-cloud в dbt\_project.yml

Блок `dbt-cloud` — это сопутствующая конфигурация, которая находится в файле `dbt_project.yml` вашего проекта (а не в `dbt_cloud.yml`). Он сообщает dbt platform CLI, Studio IDE и dbt v2, какому проекту в dbt platform соответствует ваш локальный проект.

dbt\_project.yml

```yaml
name:
version:
# Your project configs...

dbt-cloud:
  project-id: your_project_id
  defer-env-id: '123456'  # optional
```

| Поле           | Обязательное | Описание                                                                                                                                                                                                                                                                                                               |
| -------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project-id`   | Да           | Идентификатор проекта в dbt platform, которому соответствует этот локальный проект. Его можно найти в URL при просмотре проекта (например, `https://YOUR_ACCESS_URL/develop/26228/projects/123456` → `123456`).                                                                                                        |
| `defer-env-id` | Нет          | Идентификатор среды, из которой следует использовать артефакты сборки при отложенном разрешении ссылок. Используется для [автоматического отложенного разрешения ссылок](https://docs.getdbt.tech/docs/platform/about-defer.md) в dbt v2 и переопределения настроек отложенного разрешения ссылок в dbt platform CLI. |
| `account_id`   | Нет          | Только для dbt v2. Идентификатор учётной записи dbt platform, которой принадлежит этот локальный проект. Обратите внимание на символ подчёркивания — в отличие от других полей в этом блоке, здесь не используется дефис.                                                                                              |

## Связанная документация

* [dbt platform CLI](https://docs.getdbt.tech/docs/platform/dbt-cli-installation.md)
* [Расширение dbt для VS Code](https://docs.getdbt.tech/docs/about-dbt-extension.md)
* [`dbt_project.yml`](https://docs.getdbt.tech/reference/dbt_project.yml.md)