Solução de problemas do Azure Cosmos DB

Soluções para problemas comuns de emulador, conectividade e configuração de esquema do Azure Cosmos DB no construtor de API de Dados.

Perguntas comuns

O que é o suporte do Azure Cosmos DB no DAB?

O Construtor de API de Dados dá suporte ao Azure Cosmos DB como um back-end NoSQL. O DAB se conecta ao Cosmos DB usando o .NET SDK do Azure Cosmos DB e expõe entidades como tipos GraphQL. O suporte REST para Cosmos DB não está disponível; todas as consultas são atendidas por meio do ponto de extremidade do GraphQL.

Qual API o DAB usa com o Cosmos DB?

O DAB usa a API do Azure Cosmos DB para NoSQL (anteriormente a API do SQL). Não há suporte para outras APIs do Cosmos DB, como MongoDB, Gremlin e Table. Verifique se sua conta do Cosmos DB foi criada com a API do Azure Cosmos DB para NoSQL .

Há suporte para o emulador do Cosmos DB?

Sim. O emulador do Azure Cosmos DB tem suporte para desenvolvimento local. Defina a cadeia de conexão como o ponto de extremidade padrão do emulador: AccountEndpoint=https://localhost:8081/;AccountKey=<emulator-key>;. Você deve confiar no certificado autoassinado do emulador no computador de desenvolvimento antes que o DAB possa se conectar.

Problemas comuns

Certificado do emulador não confiável

Sintoma: O DAB falha ao se conectar ao emulador com um erro de validação de certificado ou SSL.

Causa: O emulador do Azure Cosmos DB usa um certificado autoassinado que não é confiável por padrão no sistema operacional.

Resolução: Exporte o certificado do emulador de https://localhost:8081/_explorer/emulator.pem e instale-o no repositório de certificados raiz confiável do computador local. No Windows, abra o arquivo de certificado e instale-o em Máquina Local > Autoridades de Certificação Raiz Confiáveis. Reinicie o DAB depois de instalar o certificado.

Não é possível se conectar ao emulador

Sintoma: O DAB falha ao iniciar The remote name could not be resolved: 'localhost' ou apresenta um erro de conexão recusada apontando para a porta 8081.

Causa: O emulador não está em execução ou o ponto de extremidade ou a chave da conta na cadeia de conexão está incorreta.

Resolução: Inicie o emulador do Azure Cosmos DB no menu Iniciar ou executando o executável do emulador. Confirme se a cadeia de conexão usa AccountEndpoint=https://localhost:8081/ e a chave do emulador correta, que é exibida na página do data explorer do emulador em https://localhost:8081/_explorer/index.html.

Arquivo de esquema GraphQL não encontrado

Sintoma: O DAB falha ao iniciar com um erro como Schema file not found ou graphql-schema path is invalid.

Causa: O graphql.schema caminho em dab-config.json aponta para um arquivo que não existe ou usa um caminho relativo incorreto.

Resolução: Verifique se o arquivo de esquema existe no caminho especificado em dab-config.json. O caminho é relativo ao local do arquivo de configuração. Execute dab init com --cosmosdb_nosql-schema para regenerar a configuração com o caminho de esquema correto e confirme se o arquivo .gql ou .graphql está presente nesse local.

A consulta retorna resultados vazios

Sintoma: As consultas GraphQL retornam uma lista vazia, mesmo que o contêiner tenha dados.

Causa: O nome do contêiner ou o caminho da chave de partição na configuração da entidade não corresponde ao contêiner do Cosmos DB real ou o nome do banco de dados está incorreto.

Resolução: Verifique o valor source da entidade dab-config.json e confirme se ele corresponde exatamente ao nome do contêiner, respeitando maiúsculas e minúsculas. Verifique se o database campo em data-source corresponde ao nome do banco de dados do Cosmos DB. No portal do Azure, abra o Data Explorer para a conta e confirme os nomes do banco de dados e do contêiner.

As conexões TCP de modo direto falham com o emulador do Linux

Sintoma: O DAB trava ou atinge o tempo limite ao se conectar ao emulador do Linux do Cosmos DB no Docker, mesmo com AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1 definido. As solicitações ficam paradas durante as tentativas de reconexão.

Causa: Atualmente, o DAB codifica o ConnectionMode.Direct, que faz com que o SDK do Cosmos descubra pontos de extremidade de partição física (como 172.17.0.2:1025010255) e abra conexões TCP para eles. No computador host, esses endereços de contêiner são inacessíveis. O modo de gateway rotearia todo o tráfego em um único ponto de extremidade HTTPS (porta 8081 no emulador) e evitaria o problema completamente. Essa é uma limitação conhecida rastreada no problema do GitHub nº 3401.

Resolução: Defina AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1 ao iniciar o contêiner do emulador. Isso força o emulador a publicar 127.0.0.1 como seu endereço, tornando os endpoints descobertos acessíveis a partir do host. Até que o modo gateway seja configurável no DAB, a substituição de IP é a solução alternativa recomendada para o desenvolvimento local.

Não há suporte para autenticação On-Behalf-Of (OBO)

Sintoma: A configuração da autenticação on-Behalf-Of (OBO) para uma instância do DAB apoiada pelo Azure Cosmos DB falha ou o token não é encaminhado conforme o esperado.

Causa: Atualmente, a autenticação OBO só tem suporte para SQL Server e SQL do Azure. O suporte para o Azure Cosmos DB ainda não foi implementado. Essa é uma limitação conhecida rastreada no problema do GitHub nº 3159.

Resolução: Use um método de autenticação com suporte, como a chave de conta do Cosmos DB ou a identidade gerenciada. Siga o tópico no GitHub para atualizações sobre quando o suporte a OBO será expandido para bancos de dados que não utilizam o SQL Server.

Falha no filtro do GraphQL no Cosmos DB

Sintoma: Uma consulta GraphQL usando o operador in em uma entidade com suporte do Cosmos DB falha em tempo de execução com a mensagem Não foi possível construir a operação de predicado desconhecida IN, mesmo que in esteja presente no esquema por meio de introspecção.

Causa: O operador in é exposto no esquema do GraphQL gerado para IdFilterInput e StringFilterInput, mas a lógica de tradução de filtro do Cosmos DB subjacente não a implementa. Essa incompatibilidade entre o esquema e o executor de consulta é um bug conhecido rastreado no problema do GitHub nº 3061.

Resolução: Evite usar o operador in em consultas GraphQL em relação a entidades do Cosmos DB. Em vez disso, use uma destas soluções alternativas:

• Substitua por várias ou + q expressões para uma lista pequena e fixa de valores.
• Use vários aliases de leitura de ponto (item_by_pk) ao consultar por uma lista conhecida de IDs.
• Filtre no lado do cliente depois de recuperar um conjunto de resultados mais amplo.

Não há suporte para agregações para o Cosmos DB

Sintoma: As consultas de agregação do GraphQL (como contagem, soma ou vg) em uma entidade apoiada pelo Cosmos DB falham ou não estão disponíveis no esquema.

Causa: Atualmente, o Construtor de API de Dados não dá suporte a operações de agregação para o Azure Cosmos DB. As agregações estão disponíveis somente para bancos de dados relacionais. Essa é uma limitação conhecida rastreada no problema do GitHub nº 2849.

Resolução: Não há nenhuma solução alternativa dentro do DAB no momento. Execute agregações do lado do cliente depois de recuperar o conjunto de resultados ou use a API de consulta interna do Cosmos DB diretamente para operações de agregação. Acompanhe a issue no GitHub para atualizações.

Consultas do tipo plural (lista) não podem ser desativadas para impor somente leitura pontual.

Sintoma: Os clientes podem emitir consultas de lista de itens amplos em uma entidade do Cosmos DB, consumindo RUs altas, quando a intenção é permitir somente leituras pontuais por meio de item_by_pk.

Causa: Atualmente, o Construtor de API de Dados não fornece uma opção de configuração para suprimir consultas plurais e restringir uma entidade a apontar somente leituras. Essa é uma limitação conhecida rastreada no problema do GitHub nº 2433.

Resolução: Como uma solução alternativa parcial, restrinja a ação de lista nas permissões da entidade para limitar quais funções podem emitir consultas de lista. Ainda não há suporte para a supressão completa do tipo de consulta plural do esquema.

Não há suporte para chaves de partição hierárquicas (MultiHash)

Sintoma: Mutações em um contêiner do Cosmos DB que usa chaves de partição hierárquicas (mais de um caminho de chave de partição) falham com o erro O valor 'kind' 'MultiHash' especificado na definição da chave de partição é inválido. Escolha o tipo de partição 'Hash'.

Causa: O Construtor de API de Dados só dá suporte a definições de chave de partição de hash (chave única). Não há suporte para contêineres configurados com chaves de partição hierárquicas (MultiHash). Essa é uma limitação conhecida rastreada no problema do GitHub nº 1733.

Resolução: Não há nenhuma solução alternativa dentro do DAB no momento. Se possível, reprojete o contêiner para usar uma única chave de partição. Se as chaves de partição hierárquicas forem exigidas pelo seu modelo de dados, siga o issue do GitHub para atualizações sobre quando o suporte multi-hash for implementado.

Não há suporte para chaves de partição MultiHash

Sintoma: Mutações em um contêiner do Cosmos DB que usa uma chave de partição hierárquica (multi-hash) falham devido ao valor 'kind' 'MultiHash' especificado na definição da chave de partição ser inválido. Escolha o tipo de partição 'Hash'.

Causa: O Construtor de API de Dados dá suporte apenas a chaves de partição hash de valor único para o Azure Cosmos DB. Não há suporte para contêineres configurados com chaves de partição hierárquicas (MultiHash), por exemplo, /TenantId, /EntityType, /EntityId. Essa é uma limitação conhecida rastreada no problema do GitHub nº 1733.

Resolução: Não há nenhuma solução alternativa dentro do DAB no momento. Em vez disso, use um contêiner com uma única chave de partição hash. Se o particionamento hierárquico for necessário, considere reestruturar o contêiner ou seguir o problema do GitHub para atualizações sobre quando o suporte à chave de partição MultiHash for adicionado.

Várias mutações não são atômicas no Cosmos DB

Sintoma: Quando várias mutações do GraphQL são enviadas em uma única solicitação contra entidades do Cosmos DB, uma falha em uma mutação não reverte as outras. Podem ocorrer gravações parciais.

Causa: O Construtor de API de Dados não encapsula várias mutações do Cosmos DB em um lote transacional. Ao contrário dos bancos de dados relacionais, em que várias mutações em uma solicitação são executadas atomicamente, as mutações do Cosmos DB são emitidas de forma independente. Essa é uma limitação conhecida rastreada no problema do GitHub nº 1621.

Resolução: Crie seu aplicativo para tratar cada mutação do Cosmos DB como independente. Se a atomicidade for necessária, use o SDK do Cosmos DB diretamente com suporte a lote transacional, com escopo para itens dentro da mesma partição lógica. Siga o issue do GitHub para atualizações sobre quando for adicionado suporte a mutação transacional para o Cosmos DB.

O nome do tipo GraphQL no arquivo de esquema não coincide com a configuração da entidade

Sintoma: O DAB inicia sem erro, mas as consultas retornam resultados inesperados ou o tipo errado, pois o nome do tipo GraphQL definido em schema.gql não corresponde ao nome de tipo singular configurado para a entidade em dab-config.json.

Causa: Atualmente, o construtor de API de Dados não valida que o nome do tipo GraphQL no arquivo de esquema corresponde ao nome de tipo singular declarado para a entidade. Uma incompatibilidade silenciosamente produz um esquema inconsistente. Essa é uma limitação conhecida rastreada no problema do GitHub nº 1556.

Resolução: Verifique manualmente se o nome do tipo em schema.gql (definido por meio da @model diretiva) corresponde ao valor singular na configuração graphql.type da entidade em dab-config.json. Por exemplo, se dab-config.json declarar "singular": "Local", o arquivo de esquema deverá conter o local @model(nameda ype :"Local").

O nome do tipo GraphQL no arquivo de esquema não corresponde ao nome do tipo singular da entidade

Sintoma: O DAB inicia sem erro, mas as consultas retornam resultados inesperados ou o tipo errado, pois o nome do tipo GraphQL definido em schema.gql não corresponde ao nome de tipo singular configurado para a entidade em dab-config.json.

Causa: Atualmente, o Data API builder não valida que o nome da @model diretiva no arquivo de esquema GraphQL corresponde ao nome de tipo singular definido para a entidade. Quando diferem, a incompatibilidade produz silenciosamente um comportamento de esquema incorreto. Essa é uma limitação conhecida rastreada no problema do GitHub nº 1556.

Resolução: Verifique manualmente se o nome do tipo em schema.gql corresponde exatamente ao valor singular na configuração graphql.type da entidade em dab-config.json. Por exemplo, se a entidade definir "singular": "Local", o arquivo de esquema deverá declarar tipo Local @model(name:"Local"). Execute o comando dab validate depois de fazer alterações para identificar outros erros de configuração.

Tipos de enumeração no arquivo de esquema GraphQL causam uma falha na construção do esquema

Sintoma: O DAB falha ao iniciar com um HotChocolate.SchemaException: não é possível resolver a referência de tipo... erro OrderByInput ocorre quando o arquivo schema.gql do Cosmos DB define um tipo num do GraphQL usado em um campo de tipo de objeto.

Causa: Atualmente, o Construtor de API de Dados não dá suporte a tipos de enumeração GraphQL no arquivo de esquema do Cosmos DB. Quando uma enumeração é usada como um tipo de campo, o construtor de esquemas não pode gerar o tipo OrderByInput correspondente e gera uma exceção sem tratamento. Essa é uma limitação conhecida rastreada no problema do GitHub nº 748.

Resolução: Substitua campos de enumeração por seus equivalentes escalares (por exemplo, use String em vez de um tipo de enumeração personalizado) em schema.gql. Aplique a validação de enumeração em sua camada de aplicativo em vez de na definição de esquema da DAB.

Tipos de enumeração no esquema GraphQL fazem com que o DAB falhe na inicialização

Sintoma: O DAB falha ao iniciar com um erro HotChocolate.SchemaException, tal como Não é possível resolver a referência de tipo 'None: FooOrderByInput' quando o arquivo de esquema GraphQL do Cosmos DB define um tipo enum usado em um modelo.

Causa: O construtor de esquemas do Construtor de API de Dados não manipula corretamente os tipos de enumeração GraphQL definidos em schema.gql. Quando uma enumeração é referenciada como um tipo de campo em um modelo, a geração interna de tipo OrderByInput falha ao resolvê-la, falhando na inicialização do esquema. Essa é uma limitação conhecida rastreada no problema do GitHub nº 748.

Resolução: Evite definir tipos de enum GraphQL no arquivo schema.gql para entidades do Cosmos DB. Como solução alternativa, substitua os campos de enumeração por Cadeia de caracteres e imponha valores válidos na camada do aplicativo. Siga o problema do GitHub para atualizações sobre quando o suporte de enumeração é adicionado.

Não há suporte para mapeamentos de campo (aliases) para entidades do Cosmos DB

Sintoma: Uma seção de mapeamento definida para uma entidade do Cosmos DB no dab-config.json não tem efeito; os nomes de campo originais ainda são expostos no esquema GraphQL em vez dos aliases configurados.

Causa: O recurso de mapeamentos, que permite expor nomes de coluna de banco de dados em nomes de campo diferentes na API, é implementado apenas para bancos de dados relacionais. Atualmente, as entidades do Cosmos DB não dão suporte a mapeamentos de campo. Essa é uma limitação conhecida rastreada no problema do GitHub nº 1512.

Resolução: Use os nomes de campo exatamente como aparecem nos documentos do Cosmos DB. Se o aliasing for necessário, aplique-o na camada do aplicativo cliente. Siga a questão do GitHub para atualizações sobre quando o suporte de mapeamento for adicionado ao Cosmos DB.

Variáveis de mutação do GraphQL não têm seus nomes de variáveis resolvidos quando armazenados, em vez de valores

Sintoma: Uma mutação GraphQL que usa variáveis (por exemplo, createExample(item: { id: , nome: })) armazena os nomes de variáveis "" e "" no banco de dados em vez dos valores reais passados na carga de ariables.

Causa: Atualmente, o Construtor de API de Dados não resolve referências de variável GraphQL em entradas de mutação para o Cosmos DB. A substituição de variável é ignorada e o nome da variável literal é gravado como o valor do campo. Esse é um bug conhecido rastreado no problema do GitHub nº 1482.

Resolução: Incorporar os valores das variáveis diretamente no corpo da mutação em vez de usar variáveis GraphQL. Por exemplo, substitua a ID: pela id: "1234". Isso não é ideal para ambientes de produção, portanto, siga o tópico no GitHub para atualizações de quando o tratamento de variáveis for corrigido para mutações do Cosmos DB.

Tipos de união no arquivo de esquema GraphQL causam um erro de 500

Sintoma: O DAB retorna um código de status 500 em todas as solicitações do GraphQL quando schema.gql define um tipo de união GraphQL. Os logs de inicialização mostram HotChocolate.SchemaException: Não é possível resolver a referência de tipo... OrderByInput.

Causa: O Construtor de API de Dados não dá suporte a tipos de união GraphQL no arquivo de esquema do Cosmos DB. Assim como os tipos de enumeração, os tipos de união fazem com que o construtor de esquemas falhe ao gerar tipos de entrada de classificação/filtro. Esse é um bug conhecido rastreado no problema do GitHub nº 1384.

Resolução: Remova definições de tipo de união de schema.gql. Modele dados polimórficos usando um único tipo de objeto com campos opcionais ou divida os dados entre entidades separadas. Siga o issue do GitHub para atualizações sobre quando será adicionado o suporte ao tipo união.

A criação de mutação falha em tempo de execução quando a ID é definida como nulo no esquema.

Sintoma: Uma mutação de criação retorna um erro de runtime mesmo que o esquema pareça válido. O erro ocorre porque o campo de ID não foi fornecido ou foi nulo.

Causa: O Cosmos DB requer o campo de ID para cada documento e o usa como parte da chave de partição. Se o schema.gql declarar o id como nulo (por exemplo, id: ID em vez de id: ID!), o DAB aceitará o esquema, mas falhará em tempo de execução quando uma mutação de criação omitir o campo. O esquema deve impor que não seja nulo no momento da validação do esquema, mas atualmente não o faz. Essa lacuna é acompanhada no issue do GitHub nº 1238.

Resolução: Sempre declare o campo de ID como não nulo no esquema GraphQL do Cosmos DB:

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

Garantindo a identificação: ID! faz com que os clientes recebam um erro claro no nível do esquema se a ID for omitida, em vez de uma falha de runtime opaca.

Relações circulares do GraphQL causam uma exceção de estouro de pilha na inicialização

Sintoma: O DAB falha na inicialização com uma exceção de estouro de pilha quando schema.gql define tipos que se referenciam mutuamente em um ciclo (por exemplo, Jogador faz referência ao Jogo e Jogo faz referência ao Jogador).

Causa: O construtor de esquemas percorre todas as referências de tipo recursivamente para gerar tipos de entrada de mutação. Relações circulares causam recursão infinita, esgotando a pilha de chamadas. Esse é um bug conhecido rastreado no problema do GitHub nº 746.

Resolução: Evite referências de tipo circular em schema.gql. Quebre o ciclo removendo a referência inversa de um dos tipos ou modele o relacionamento como uma lista de IDs (campos escalares) em vez de tipos de objetos aninhados. Siga a questão no GitHub para atualizações sobre quando as relações circulares serão suportadas.

A chave de partição é sempre "id"; caminhos de chave de partição personalizados não são suportados.

Sintoma: O DAB funciona apenas com contêineres do Cosmos DB que usam /id como a chave de partição. Contêineres particionados por qualquer outro campo (por exemplo, /userId ou /category) não podem ser consultados ou modificados corretamente.

Causa: O construtor de API de dados codifica a ID como a chave de partição para todas as entidades do Cosmos DB. Não há como especificar um caminho de chave de partição personalizado em dab-config.json ou schema.gql. Essa é uma limitação conhecida rastreada no problema do GitHub nº 747.

Resolução: Crie novos contêineres com /id como a chave de partição ao usar o DAB. Para contêineres existentes com uma chave de partição diferente, o DAB não tem suporte no momento. Siga o problema do GitHub para atualizações sobre quando as chaves de partição configuráveis são adicionadas.

Não há suporte para realizar consultas em matrizes aninhadas dentro de um documento (junções internas aos itens)

Sintoma: Você não pode filtrar ou percorrer propriedades de matriz aninhadas em um documento do Cosmos DB usando o DAB. Consultas que exigiriam um JOIN do Cosmos DB entre elementos de matriz não retornam nenhum resultado ou erro.

Causa: O Construtor de API de Dados não dá suporte a junções intra-documentais do Cosmos DB (também chamadas de junções no item), que são necessárias para consultar matrizes aninhadas em um único documento. Essa é uma limitação conhecida rastreada no problema do GitHub nº 262.

Resolução: Achate matrizes aninhadas em entidades separadas ou documentos subordinados se precisar filtrar o conteúdo. Como alternativa, execute o pós-processamento do documento completo na camada do aplicativo. Siga o issue do GitHub para atualizações sobre quando o suporte de junção intra-documento é adicionado.