Устранение неполадок Azure Cosmos DB

Решения распространенных проблем с эмулятором Azure Cosmos DB, подключением и конфигурацией схемы в построителе API данных.

Распространенные вопросы

Что такое поддержка Azure Cosmos DB в DAB?

Data API builder поддерживает Azure Cosmos DB в качестве серверной части NoSQL базы данных. DAB подключается к Cosmos DB с помощью пакета SDK для .NET для Azure Cosmos DB и предоставляет сущности в виде типов GraphQL. Поддержка REST для Cosmos DB недоступна; все запросы обслуживаются через конечную точку GraphQL.

Какой API использует DAB с Cosmos DB?

DAB использует API Azure Cosmos DB для NoSQL (ранее — API SQL). Другие API Cosmos DB, такие как MongoDB, Gremlin и Table, не поддерживаются. Убедитесь, что учетная запись Cosmos DB создана с помощью API Azure Cosmos DB для NoSQL .

Поддерживается ли эмулятор Cosmos DB?

Да. Эмулятор Azure Cosmos DB поддерживается для локальной разработки. Установите строку подключения на значение конечной точки по умолчанию для эмулятора: AccountEndpoint=https://localhost:8081/;AccountKey=<emulator-key>;. Перед подключением DAB необходимо доверять самозаверяющему сертификату эмулятора на компьютере разработки.

Распространенные проблемы

Сертификат эмулятора не является доверенным

Симптом: DAB не удается подключиться к эмулятору с ошибкой проверки SSL или сертификата.

Причина: Эмулятор Azure Cosmos DB использует самоподписанный сертификат, который по умолчанию не доверяется операционной системой.

Разрешение: Экспортируйте и установите сертификат эмулятора из https://localhost:8081/_explorer/emulator.pem доверенного корневого хранилища сертификатов локального компьютера. В Windows откройте файл сертификата и установите его в доверенные корневые центры сертификации локального компьютера>. Перезапустите DAB после установки сертификата.

Не удается подключиться к эмулятору

Симптом: DAB не удается запуститься с The remote name could not be resolved: 'localhost' или возникает ошибка отказа в подключении, указывающая на порт 8081.

Причина: Эмулятор не запущен, или конечная точка или ключ учетной записи в строке подключения неверны.

Разрешение: Запустите эмулятор Azure Cosmos DB из меню "Пуск" или запустив исполняемый файл эмулятора. Убедитесь, что строка подключения используется AccountEndpoint=https://localhost:8081/ и правильный ключ эмулятора, который отображается на странице обозревателя данных эмулятора.https://localhost:8081/_explorer/index.html

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

Симптом: DAB не удаётся запуститься из-за ошибки, например, Schema file not found или graphql-schema path is invalid.

Причина: Путь в dab-config.json указывает на файл, который не существует или использует неправильный относительный путь.

Разрешение: Убедитесь, что файл схемы существует по пути, указанному в dab-config.json. Путь относительно расположения файла конфигурации. Выполните dab init с --cosmosdb_nosql-schema, чтобы повторно создать конфигурацию с правильным путем схемы. Затем подтвердите наличие файла .gql или .graphql в этом расположении.

Запрос возвращает пустые результаты

Симптом: Запросы GraphQL возвращают пустой список, даже если контейнер содержит данные.

Причина: Имя контейнера или путь ключа секции конфигурации сущности не соответствует фактическому контейнеру Cosmos DB, или имя базы данных указано неправильно.

Разрешение: Проверьте значение source сущности dab-config.json и подтвердите, что оно соответствует точному имени контейнера (с учетом регистра). Проверьте, соответствует ли поле database под data-source названию базы данных Cosmos DB. На портале Azure откройте обозреватель данных для учетной записи и подтвердите имена баз данных и контейнеров.

Сбой tcp-подключений в режиме direct с эмулятором Linux

Симптом: DAB зависает или истекает время ожидания при подключении к эмулятору Linux Cosmos DB в Docker, даже если установлено AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1. Запросы застопорились во время повторных попыток подключения.

Причина: В настоящее время DAB жестко кодирует параметр ConnectionMode.Direct, что приводит к обнаружению конечных точек физической секции (например, 172.17.0.2:1025010255) и открытию TCP-подключений к ним. На хост-компьютере эти адреса контейнеров недоступны. Режим шлюза будет направлять весь трафик через одну конечную точку HTTPS (порт 8081 в эмуляторе) и полностью избежать проблемы. Это известное ограничение, отслеживаемое в проблеме GitHub #3401.

Разрешение: Задайте AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1 при запуске контейнера эмулятора. Это заставляет эмулятор объявлять 127.0.0.1 в качестве своего адреса, что делает обнаруженные конечные точки доступными от узла. Пока режим шлюза не настраивается в DAB, переопределение IP-адресов является рекомендуемым решением для локальной разработки.

Аутентификация On-Behalf-Of (OBO) не поддерживается.

Симптом: Настройка проверки подлинности On-Behalf-Of (OBO) для экземпляра DAB, который поддерживается Azure Cosmos DB, не выполняется, или токен не пересылается должным образом.

Причина: Проверка подлинности OBO в настоящее время поддерживается только для SQL Server и Azure SQL. Поддержка Azure Cosmos DB еще не реализована. Это известное ограничение, отслеживаемое в проблеме GitHub #3159.

Разрешение: Используйте поддерживаемый метод проверки подлинности, например ключ учетной записи Cosmos DB или управляемое удостоверение. Следите за задачей GitHub для обновлений о расширении поддержки OBO на другие базы данных, кроме SQL Server.

Сбой GraphQL в фильтре в Cosmos DB

Симптом: Запрос GraphQL, использующий оператор in для сущности, поддерживаемой Cosmos DB, завершается сбоем во время выполнения с ошибкой сборки неизвестной операции предиката IN, даже если она отображается в схеме с помощью интроспектации.

Причина: Оператор in предоставляется в созданной схеме GraphQL для IdFilterInput и StringFilterInput, но логика перевода фильтра Cosmos DB его не поддерживает. Это несоответствие между схемой и исполнителем запросов является известной ошибкой, отслеживаемой в проблеме GitHub #3061.

Рекомендация: Избегайте использования оператора in в запросах GraphQL к сущностям Cosmos DB. Используйте одно из следующих обходных решений.

• Замените "in" на несколько выражений или выражения с + q для небольшого фиксированного списка значений.
• Используйте несколько псевдонимов для точечных чтений (item_by_pk) при выполнении запроса по заданному списку идентификаторов.
• Отфильтруйте на стороне клиента после получения более широкого набора результатов.

Агрегации не поддерживаются для Cosmos DB

Симптом: Статистические запросы GraphQL (например, количество, сумма или vg) для объекта, поддерживаемого Cosmos DB, завершаются сбоем или недоступны в схеме.

Причина: Построитель API данных сейчас не поддерживает агрегационные операции для Azure Cosmos DB. Агрегации доступны только для реляционных баз данных. Это известное ограничение, отслеживаемое в проблеме GitHub #2849.

Разрешение: В настоящее время в DAB не существует обходного решения. Выполняйте агрегаты на стороне клиента после извлечения результирующих наборов или используйте встроенный API запросов Cosmos DB непосредственно для агрегатных операций. Следите за задачей на GitHub, чтобы получать обновления.

Запросы множественные (списковые) не могут быть отключены, чтобы использовать только точечные чтения.

Симптом: Клиенты могут выдавать широкие запросы списка элементов к сущности Cosmos DB, потребляя высокие значения RUs, когда намерение заключается только в выполнении точечных операций чтения через item_by_pk.

Причина: В настоящее время построитель API данных не предоставляет возможность настройки для подавления запросов на множественное чтение и ограничения сущности только на операции чтения. Это известное ограничение, отслеживаемое в проблеме GitHub #2433.

Разрешение: В качестве частичного обходного решения ограничьте действие списка в разрешениях сущности, чтобы ограничить, какие роли могут выдавать запросы списка. Полное подавление типа запроса plural из схемы пока не поддерживается.

Иерархические ключи раздела (MultiHash) не поддерживаются

Симптом: Изменения в контейнере Cosmos DB, который использует иерархические ключи разбиения (несколько путей ключа разбиения), завершаются с ошибкой: указанное в определении ключа разбиения значение 'kind' 'MultiHash' является недопустимым. Выберите тип раздела Hash.

Причина: Построитель данных API поддерживает только определения разделительных ключей с одним ключом (хэш). Контейнеры, настроенные с помощью иерархических ключей секций (MultiHash), не поддерживаются. Это известное ограничение, отслеживаемое в проблеме GitHub #1733.

Разрешение: В настоящее время в DAB не существует обходного решения. Если возможно, переработайте контейнер, чтобы использовать один ключ партиции. Если иерархические ключи разделов требуются для вашей модели данных, следите за обсуждением на GitHub об обновлении для добавления поддержки нескольких хэшей.

Ключи раздела MultiHash не поддерживаются

Симптом: Операции с контейнером Cosmos DB, использующим иерархический (мульти-хэш) ключ разбиения, завершаются ошибкой с недопустимым значением 'kind' – 'MultiHash', указанным в определении ключа разбиения. Пожалуйста, выберите тип раздела Hash.

Причина: Конструктор API данных поддерживает только однозначные ключи разделов Хэш для Azure Cosmos DB. Контейнеры, настроенные с помощью иерархических ключей секций (MultiHash), например /TenantId, /EntityType, /EntityId, не поддерживаются. Это известное ограничение, отслеживаемое в проблеме GitHub #1733.

Разрешение: В DAB в настоящее время не существует обходного пути. Вместо этого используйте контейнер с одним ключом секции Хэша. Если требуется иерархическое секционирование, рассмотрите возможность реструктуризации контейнера или следите за обновлениями по проблеме на GitHub о добавлении поддержки ключа секции MultiHash.

Несколько мутаций не являются атомарными в Cosmos DB

Симптом: Если несколько мутаций GraphQL отправляются в одном запросе к сущностям Cosmos DB, сбой в одной мутации не откатывает другие. Частичные операции записи могут выполняться.

Причина: Построитель API данных не объединяет несколько мутаций Cosmos DB в транзакционный пакет. В отличие от реляционных баз данных, в которых несколько мутаций в запросе выполняются атомарно, мутации Cosmos DB выдаются независимо. Это известное ограничение, отслеживаемое в проблеме GitHub #1621.

Разрешение: Разработайте ваше приложение для обработки каждой мутации в Cosmos DB как независимой. Если требуется атомарность, используйте пакет SDK Cosmos DB непосредственно с поддержкой транзакционных пакетов, ограниченных элементами в одном логическом разделе. Следите за задачей на GitHub за обновлениями о том, когда будет добавлена поддержка транзакционных мутаций для Cosmos DB.

Имя типа GraphQL в файле схемы не соответствует конфигурации сущности

Симптом: DAB запускается без ошибок, но запросы возвращают непредвиденные результаты или неправильный тип, так как имя типа GraphQL, определенное в schema.gql, не соответствует имени единственного типа, настроенного для сущности в dab-config.json.

Причина: Data API Builder на данный момент не проверяет, соответствует ли имя типа GraphQL в файле схемы уникальному имени типа, объявленному для сущности. Несоответствие автоматически создает несогласованную схему. Это известное ограничение, отслеживаемое в проблеме GitHub #1556.

Решение: Вручную убедитесь, что имя типа в schema.gql (задано с помощью директивы @model) соответствует одиночному значению в конфигурации graphql.type сущности в dab-config.json. Например, если в файле dab-config.json объявлено "singular": "Location", то файл схемы должен содержать Type Location @model(name:"Location").

Имя типа GraphQL в файле схемы не соответствует имени единственного типа сущности

Симптом: DAB запускается без ошибок, но запросы возвращают непредвиденные результаты или неправильный тип, так как имя типа GraphQL, определенное в schema.gql, не соответствует имени единственного типа, настроенного для сущности в dab-config.json.

Причина: Построитель данных в настоящее время не проверяет, совпадает ли @model имя директивы в файле схемы GraphQL с именем сингулярного типа, установленным для сущности. Если они отличаются, несоответствие автоматически приводит к неправильному поведению схемы. Это известное ограничение, отслеживаемое в проблеме GitHub #1556.

Разрешение: Вручную убедитесь, что имя типа в schema.gql точно соответствует единственному значению в конфигурации graphql.type сущности в dab-config.json. Например, если сущность определяет "singular": Location", файл схемы должен объявить расположение ype @model(name:"Location"). Запустите команду dab validate после внесения изменений, чтобы обнаружить другие ошибки конфигурации.

Типы перечисления в файле схемы GraphQL вызывают сбой построения схемы

Симптом: DAB не удается начать с HotChocolate.SchemaException: не удается разрешить ссылку на тип ... Ошибка OrderByInput, если файл schema.gql Cosmos DB определяет тип числов GraphQL, используемый в поле типа объекта.

Причина: Конструктор API данных не поддерживает типы перечисления GraphQL в файле схемы Cosmos DB. Если перечисление используется в качестве типа поля, построитель схем не может создать соответствующий тип OrderByInput и вызывает необработанное исключение. Это известное ограничение, отслеживаемое в проблеме GitHub #748.

Разрешение: Замените поля перечисления скалярными эквивалентами (например, использовать String вместо пользовательского типа перечисления) в schema.gql. Примените проверку перечисления на уровне приложения, а не в определении схемы DAB.

Типы перечисления в схеме GraphQL приводят к сбою DAB при запуске

Симптом: DAB не запускается из-за ошибки HotChocolate.SchemaException, "Не удается разрешить тип ссылки None: FooOrderByInput", когда в файле схемы GraphQL базы данных Cosmos определяется перечисляемый тип, используемый в модели.

Причина: Построитель схем для Data API неправильно обрабатывает типы перечисления GraphQL, определенные в schema.gql. Когда перечисление используется в качестве типа поля в модели, внутреннее поколение типов OrderByInput не удается его разрешить, что приводит к сбою инициализации схемы. Это известное ограничение, отслеживаемое в проблеме GitHub #748.

Разрешение: Избегайте определения enum типов GraphQL в файле schema.gql для сущностей Cosmos DB. В качестве обходного решения замените поля перечисления строкой и примените допустимые значения на уровне приложения. Следите за проблемой на GitHub, чтобы получать обновления о добавлении поддержки перечислений.

Сопоставления полей (псевдонимы) не поддерживаются для сущностей Cosmos DB

Симптом: Раздел сопоставлений, определенный для сущности Cosmos DB в dab-config.json, не влияет на исходные имена полей, которые по-прежнему отображаются в схеме GraphQL вместо настроенных псевдонимов.

Причина: Функция сопоставления, которая позволяет предоставлять имена столбцов базы данных под различными именами полей в API, предназначена только для реляционных баз данных. Сущности Cosmos DB в настоящее время не поддерживают сопоставления полей. Это известное ограничение, отслеживаемое в проблеме GitHub #1512.

Разрешение: Используйте имена полей точно так же, как они отображаются в документах Cosmos DB. Если требуется псевдоним, примените его на уровне клиентского приложения. Следите за проблемой на GitHub, чтобы получать обновления о добавлении поддержки маппинга для Cosmos DB.

Переменные мутации GraphQL не разрешаются и остаются именами переменных, хранящимися вместо значений.

Симптом: Мутация GraphQL, использующая переменные (например, createExample(item: { id: , name: })) сохраняет имена переменных "" и "" в базе данных вместо фактических значений, переданных в полезных данных ariables.

Причина: Data API сборщик на данный момент не разрешает ссылки на переменные GraphQL в входных данных мутации для Cosmos DB. Подстановка переменных пропускается, а имя литеральной переменной записывается в качестве значения поля. Это известная ошибка, отслеживаемая в проблеме GitHub #1482.

Разрешение: Внедрите значения переменных непосредственно в тело мутации вместо того, чтобы использовать переменные GraphQL. Например, замените id: на "1234". Это не идеально подходит для использования в рабочей среде, поэтому следите за обсуждением на GitHub для получения обновлений о том, когда будет исправлена обработка переменных для мутаций Cosmos DB.

Типы объединения в файле схемы GraphQL вызывают ошибку 500

Симптом: DAB возвращает код состояния 500 для всех запросов GraphQL, когда schema.gql определяет тип объединения GraphQL. Журналы запуска содержат HotChocolate.SchemaException: не удается разрешить ссылку на тип ... OrderByInput.

Причина: Построитель API данных не поддерживает унифицированные типы GraphQL в файле схемы Cosmos DB. Как и типы перечисления, типы объединения вызывают сбой построителя схем при генерации входных данных для сортировки и фильтрации. Это известная ошибка, отслеживаемая в проблеме GitHub #1384.

Решение: Удаление определений типов объединения из schema.gql. Модель полиморфных данных с использованием одного типа объекта с необязательными полями или разделение данных по отдельным сущностям. Следуйте проблеме GitHub с обновлениями при добавлении поддержки типов объединения.

Создание мутации завершается ошибкой во время выполнения, если идентификатор определяется как допускающий значение NULL в схеме

Симптом: Создается мутация, возвращается ошибка времени выполнения, даже если схема кажется допустимой. Ошибка возникает из-за того, что поле идентификатора не было предоставлено или было null.

Причина: Cosmos DB требует поле id для каждого документа и использует его в качестве части ключа раздела. Если schema.gql объявляет идентификатор как допускающий значение null (например, id: ID вместо id: ID!), DAB принимает схему, но завершается сбоем во время выполнения при создании мутации, когда поле опускается. Схема должна применять ненулевое значение во время проверки схемы, но в настоящее время это не так. Этот разрыв отслеживается в проблеме GitHub 1238.

Разрешение: Всегда объявляйте поле идентификатора как непустое в схеме GraphQL Cosmos DB:

graphql type MyEntity @model(name: "MyEntity") { id: ID! ... }

Обеспечение идентификатора: ID! Приводит к тому, что клиенты получают четкую ошибку уровня схемы, если идентификатор опущен, вместо непрозрачного сбоя на этапе выполнения.

Циклические связи GraphQL вызывают исключение переполнения стека при запуске

Симптом: DAB завершает работу при запуске с исключением переполнения стека, когда в schema.gql определены типы, которые ссылаются друг на друга в цикле (например, Игрок ссылается на Игру, а Игра ссылается на Игрока).

Причина: Построитель схем обходит все ссылки на типы рекурсивно для создания типов входных данных изменений. Циклические связи вызывают бесконечную рекурсию, исчерпывая стек вызова. Это известная ошибка, отслеживаемая в проблеме GitHub #746.

Разрешение: Избегайте циклических ссылок на тип в schema.gql. Разорвать цикл, удалив обратную ссылку из одного из типов или моделируя связь в виде списка идентификаторов (скалярных полей), а не вложенных типов объектов. Следите за задачей GitHub, чтобы получать обновления о том, когда будет поддержка циклических зависимостей.

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

Симптом: DAB работает только с контейнерами Cosmos DB, которые используют /id в качестве ключа секции. Контейнеры, секционированные любым другим полем (например, /userId или /category), не могут запрашиваться или изменяться правильно.

Причина: Data API построитель жёстко задаёт id как ключ раздела для всех сущностей Cosmos DB. В dab-config.json или schema.gql невозможно указать пользовательский путь ключа секции. Это известное ограничение, отслеживаемое в проблеме GitHub #747.

Разрешение: Создайте новые контейнеры с помощью /id в качестве ключа партиции при использовании DAB. Для существующих контейнеров с другим ключом секции DAB в настоящее время не поддерживается. Следите за задачей на GitHub, чтобы получать обновления о добавлении настраиваемых ключей разделов.

Запрос вложенных массивов в документе (внутриэлементые соединения) не поддерживаются

Симптом: Нельзя фильтровать или пересекать свойства вложенного массива в документе Cosmos DB с помощью DAB. Запросы, требующие соединения Cosmos DB между элементами массива, не возвращают результатов или ошибки.

Причина: Построитель API данных не поддерживает внутридокументные соединения Cosmos DB (также называемые внутриэлементными соединениями), которые необходимы для запроса вложенных массивов в одном документе. Это известное ограничение, отслеживаемое в проблеме GitHub #262.

Разрешение: Сделайте вложенные массивы плоскими, преобразуя их в отдельные сущности или дочерние документы, если необходимо фильтровать их содержимое. Кроме того, выполните постобработку полного документа на уровне приложения. Следите за задачей на GitHub, чтобы получать обновления, когда будет добавлена поддержка внутридокументного присоединения.