Настройка построителя API данных для Azure Cosmos DB для NoSQL

Azure Cosmos DB для NoSQL — это база данных документов, не зависящих от схемы. В отличие от реляционных баз данных, Azure Cosmos DB не имеет предварительно определенной схемы, которую Data API builder (DAB) может автоматически анализировать. В этом руководстве объясняется, как создать файл схемы GraphQL и настроить DAB для работы с контейнерами Azure Cosmos DB.

Необходимые условия

Azure Cosmos DB для учетной записи NoSQL с хотя бы одной базой данных и контейнером
CLI инструмента построения API данных. Установка интерфейса командной строки

Общие сведения о требованиях к схеме

Так как Azure Cosmos DB для NoSQL не применяет схему, DAB не может автоматически создавать типы GraphQL из данных. Вместо этого необходимо указать файл схемы GraphQL, который определяет:

Типы объектов , представляющие структуру документа контейнера
Директива@model, которая сопоставляет типы GraphQL с именами сущностей в конфигурации DAB
@authorize Директива (необязательно), которая ограничивает доступ на уровне поля к определенным ролям.

Вы можете вручную создать схему, используя следующие примеры или сгенерировать её из существующих данных в Cosmos DB с помощью команды dab export.

Создание файла схемы GraphQL

.gql Создайте файл, описывающий модель данных. Файл схемы использует стандартный язык определения схемы GraphQL (SDL) с пользовательскими директивами для DAB.

Пример базовой схемы

В этом примере описан Book тип, содержащий общие поля, которые можно найти в контейнере книг.

type Book @model(name: "Book") {
  id: ID
  title: String
  year: Int
  pages: Int
  Authors: [Author]
}

type Author @model(name: "Author") {
  id: ID
  firstName: String
  lastName: String
}

Создание схемы из данных Cosmos DB

Если у вас уже есть данные в контейнерах, вы можете использовать их выборку, чтобы создать начальную схему. Эта команда записывает выведенный файл схемы GraphQL в выходной каталог, который вы указываете с помощью -o.

Bash
Командная строка

dab export \
  --graphql \
  --generate \
  -o ./schema-out

dab export ^
  --graphql ^
  --generate ^
  -o .\schema-out

По умолчанию используется выборка TopNExtractor.

Поддерживаемые режимы выборки: TopNExtractorи EligibleDataSamplerTimePartitionedSampler.

Замечание

Параметр -o/--output является обязательным. Если имя файла схемы не указано, DAB создает schema.gql в выходном каталоге.

Для других режимов и параметров см. справочник по CLI dab export.

Директива @model является обязательной. Он сопоставляет тип GraphQL с именем сущности в файле конфигурации DAB. Параметр name должен точно соответствовать имени сущности.

Замечание

Поле Authors: [Author] представляет внедренный массив в документе Book, а не связь с отдельным контейнером. В Azure Cosmos DB для NoSQL связанные данные должны быть внедрены в один документ, а не храниться в отдельных контейнерах.

Схема с авторизацией

Чтобы ограничить доступ к определенным полям, используйте директиву @authorize . Эта директива принимает параметр, указывающий roles , какие роли могут получить доступ к полю.

type Book @model(name: "Book") {
  id: ID
  title: String @authorize(roles: ["authenticated", "metadataviewer"])
  internalNotes: String @authorize(roles: ["editor"])
  Authors: [Author]
}

В этом примере:

Поле title доступно только для пользователей с ролью authenticated или metadataviewer.
Поле internalNotes доступно только пользователям с ролью editor
Поля без @authorize доступны на основе разрешений на уровне сущностей

Вы также можете применить @authorize на уровне типа, чтобы ограничить доступ ко всему типу:

type InternalReport @model(name: "InternalReport") @authorize(roles: ["editor", "auditor"]) {
  id: ID
  title: String
  confidentialData: String
}

Это важно

Директива @authorize работает в дополнение к разрешениям на уровне сущностей, определенным в конфигурации среды выполнения. Директива @authorize и разрешения сущности должны разрешать доступ для успешного выполнения запроса.

Например, если поле имеет @authorize(roles: ["editor"]), но сущность не имеет разрешения для editor роли, доступ к данному полю запрещен.

Предупреждение

@authorize(policy: "...") не поддерживается в данном потоке схемы. Используйте @authorize(roles: [...]).

Настройка среды выполнения DAB

После создания файла схемы настройте DAB для его использования с учетной записью Azure Cosmos DB.

Инициализация конфигурации

Используйте команду dab init для создания файла конфигурации для Azure Cosmos DB:

Bash
Командная строка

dab init \
  --database-type cosmosdb_nosql \
  --cosmosdb_nosql-database <your-database-name> \
  --graphql-schema schema.gql \
  --connection-string "<your-connection-string>"

dab init ^
  --database-type cosmosdb_nosql ^
  --cosmosdb_nosql-database <your-database-name> ^
  --graphql-schema schema.gql ^
  --connection-string "<your-connection-string>"

Замените <your-database-name> на имя вашей базы данных Azure Cosmos DB и <your-connection-string> на вашу строку подключения.

При необходимости включите --cosmosdb_nosql-container <your-container-name>, чтобы установить контейнер по умолчанию в конфигурации источника данных.

Подсказка

Для рабочих сред используйте переменные среды для строк подключения вместо жесткой кодировки:

dab init \
    --database-type cosmosdb_nosql \
    --cosmosdb_nosql-database <your-database-name> \
    --graphql-schema schema.gql \
    --connection-string "@env('COSMOSDB_CONNECTION_STRING')"

Добавить сущности

Добавьте сущности, соответствующие контейнерам. Имя сущности должно соответствовать значению в схеме @model(name: "...") :

Bash
Командная строка

dab add Book \
  --source Book \
  --permissions "anonymous:read"

dab add Book ^
  --source Book ^
  --permissions "anonymous:read"

Параметр --source принимает либо <container-name> или <database-name>.<container-name>. Используйте формат из двух частей, если вы хотите чётко указать как на базу данных, так и на контейнер.

Пример файла конфигурации

После инициализации файл конфигурации должен выглядеть примерно так:

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/download/v1.2.11/dab.draft.schema.json",
  "data-source": {
    "database-type": "cosmosdb_nosql",
    "options": {
      "database": "Library",
      "schema": "schema.gql"
    },
    "connection-string": "@env('COSMOSDB_CONNECTION_STRING')"
  },
  "entities": {
    "Book": {
      "source": "Book",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["read"]
        },
        {
          "role": "metadataviewer",
          "actions": ["read"]
        }
      ]
    }
  }
}

Замечание

schema Путь в файле конфигурации относится к расположению файла конфигурации DAB. Убедитесь, что файл схемы GraphQL находится в правильном каталоге.

Этот $schema URL-адрес указывает на определенный выпуск DAB. Используйте URL-адрес схемы, соответствующий версии DAB.

Доступ к полю на основе ролей

При использовании @authorize директивы с ролями следует учитывать, как назначаются роли:

Сценарий	Назначение ролей	Доступ к полям `@authorize`
Анонимный запрос	Нет назначенных ролей	Отказано
Запрос, прошедший проверку подлинности	Системная `authenticated` роль автоматически назначается	Разрешено, если роли совпадают
Запрос пользовательской роли	Включите заголовок `X-MS-API-ROLE` с именем роли	Разрешено, если роли совпадают

Эта таблица применяется к полям или типам, которые явно включают @authorize. Для полей без @authorize доступ определяется разрешениями на уровне сущностей.

Для прошедших проверку подлинности запросов, требующих настраиваемой роли, отправьте X-MS-API-ROLE заголовок:

GET /graphql HTTP/1.1
Host: localhost:5000
Authorization: Bearer <your-jwt-token>
X-MS-API-ROLE: metadataviewer

Межконтейнерные запросы

Операции GraphQL между контейнерами не поддерживаются в Azure Cosmos DB для NoSQL.

Если вы пытаетесь настроить связи между сущностями в разных контейнерах с помощью dab add или dab updateпроверка интерфейса командной строки завершается ошибкой.

Сообщение об ошибке CLI: Adding/updating Relationships is currently not supported in CosmosDB.

Сведения о конфигурации отношений (поддерживаемые для других баз данных) см. в разделе "Конфигурация связей".

Обход ограничений между контейнерами

Чтобы обойти это ограничение, рассмотрите возможность реструктуризации модели данных для использования внедренных документов в одном контейнере. Этот подход часто более эффективен для Azure Cosmos DB и соответствует рекомендациям по моделированию данных NoSQL.

Например, вместо отдельных Book и Author контейнеров с связями:

// Embedded model in a single container
{
  "id": "book-1",
  "title": "Introduction to DAB",
  "authors": [
    {
      "firstName": "Jane",
      "lastName": "Developer"
    }
  ]
}

Для получения дополнительной информации о стратегиях моделирования данных см. Моделирование данных в Azure Cosmos DB.

Доступность REST API

Построитель API данных не создает конечные точки REST для Azure Cosmos DB для NoSQL, так как Azure Cosmos DB уже предоставляет полный собственный REST API для операций с документами.

При использовании DAB с Azure Cosmos DB для NoSQL DAB предоставляет только конечные точки GraphQL и не создает OpenAPI. Чтобы получить доступ к данным через REST, используйте Azure Cosmos DB REST API напрямую.

Распространенные проблемы конфигурации

Файл схемы не найден

Ошибка: GraphQL schema file not found
Решение. Убедитесь, что schema путь в конфигурации соответствует расположению файла конфигурации.

Несоответствие имени сущности

Ошибка: Entity '<name>' not found in schema
Решение. Проверьте имя сущности в конфигурации точно соответствует директиве @model(name: "...") . В именах учитывается регистр.

Несанкционированный доступ к полю

Ошибка: ошибка авторизации GraphQL (например, если роль не разрешена)
Решение: Убедитесь, что разрешения для @authorize ролей и сущностей позволяют доступ запрашивающей роли.

Следующий шаг

Быстрый старт: использование конструктора API данных с NoSQL

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-04-01

Настройка построителя API данных для Azure Cosmos DB для NoSQL

Необходимые условия

Общие сведения о требованиях к схеме

Создание файла схемы GraphQL

Пример базовой схемы

Создание схемы из данных Cosmos DB

Схема с авторизацией

Настройка среды выполнения DAB

Инициализация конфигурации

Добавить сущности

Пример файла конфигурации

Доступ к полю на основе ролей

Межконтейнерные запросы

Обход ограничений между контейнерами

Доступность REST API

Распространенные проблемы конфигурации

Следующий шаг

Связанный контент

Обратная связь

Дополнительные ресурсы