Resolução de problemas do Azure Cosmos DB

Soluções para problemas comuns de emuladores do Azure Cosmos DB, conectividade e configuração de esquema no Data API Builder.

Perguntas frequentes

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

O Data API Builder suporta o Azure Cosmos DB como back-end NoSQL. O DAB liga-se ao Cosmos DB usando o Azure Cosmos DB .NET SDK e expõe entidades como tipos GraphQL. O suporte REST para Cosmos DB não está disponível; todas as consultas são servidas através do endpoint GraphQL.

Que API é que o DAB usa com o Cosmos DB?

O DAB utiliza o Azure Cosmos DB para a API NoSQL (anteriormente SQL API). Outras APIs do Cosmos DB, como MongoDB, Gremlin e Table, não são suportadas. Certifique-se de que a sua conta Cosmos DB foi criada com a API Azure Cosmos DB for NoSQL .

O emulador Cosmos DB é suportado?

Yes. O emulador Azure Cosmos DB é suportado para desenvolvimento local. Defina a string de ligação para o endpoint padrão do emulador: AccountEndpoint=https://localhost:8081/;AccountKey=<emulator-key>;. Deve confiar no certificado autoassinado do emulador na máquina de desenvolvimento antes de o DAB se poder conectar.

Problemas comuns

Certificado do emulador não confiável

Sintoma: O DAB falha em ligar-se ao emulador devido a um erro SSL ou de validação de certificado.

Causa: O emulador Azure Cosmos DB utiliza um certificado auto-assinado que não é confiável por defeito no sistema operativo.

Resolução: Exporte e instale o certificado do emulador de https://localhost:8081/_explorer/emulator.pem em o armazenamento de certificados raiz de confiança da máquina local. No Windows, abra o ficheiro de certificado e instale-o nas Autoridades de Certificação Root Confiáveis da Máquina > Local. Reinicie o DAB depois de instalar o certificado.

Não é possível ligar-se ao emulador

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

Causa: O emulador não está a correr, ou o endpoint ou a chave de conta na string de ligação estão incorretos.

Resolução: Inicie o emulador Azure Cosmos DB a partir do menu Iniciar ou executando o executável do emulador. Confirme que a string de ligação utiliza AccountEndpoint=https://localhost:8081/ e a chave correta do emulador, que é exibida na página do explorador de dados do emulador em https://localhost:8081/_explorer/index.html.

Ficheiro de esquema GraphQL não encontrado

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

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

Resolução: Verifique se o ficheiro de esquema existe no caminho especificado em dab-config.json. O caminho é relativo à localização do ficheiro de configuração. Executa dab init com --cosmosdb_nosql-schema para regenerar a configuração com o caminho de esquema correto, depois confirmar que .gql ficheiro ou .graphql está presente nesse local.

A consulta devolve resultados vazios

Sintoma: As consultas GraphQL retornam uma lista vazia mesmo que o contentor tenha dados.

Causa: O nome do contentor ou o caminho da chave de partição na configuração da entidade não correspondem ao contentor real do Cosmos DB, ou o nome da base de dados está incorreto.

Resolução: Verifique o valor da source entidade em dab-config.json e confirme que corresponde exatamente ao nome do contentor (distinção de maiúsculas e minúsculas). Verifique se o database campo abaixo data-source corresponde ao nome da base de dados Cosmos DB. No portal Azure, abra o Data Explorer da conta e confirme os nomes da base de dados e dos contentores.

As ligações TCP em modo direto falham com o emulador Linux

Sintoma: O DAB fica inativo ou esgota o tempo ao tentar conectar ao emulador Cosmos DB no Linux via Docker, mesmo com AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1 definido. Os pedidos são atrasados durante as tentativas de reconexão.

Causa: Atualmente, o DAB codifica fixamente o ConnectionMode.Direct, que faz com que o SDK do Cosmos descubra pontos finais físicos de partição (como 172.17.0.2:1025010255) e abra ligações TCP a eles. A partir da máquina anfitriã, esses endereços de contentores são inacessíveis. O modo gateway encaminharia todo o tráfego para um único endpoint HTTPS (porta 8081 no emulador) e evitaria o problema por completo. Esta é uma limitação conhecida registada na edição #3401 do GitHub.

Resolução: Define AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1 ao iniciar o contentor do emulador. Isto obriga o emulador a anunciar 127.0.0.1 como o seu endereço, tornando os endpoints descobertos acessíveis a partir do host. Até que o modo Gateway possa ser configurado no DAB, a substituição de IP é a solução alternativa recomendada para desenvolvimento local.

A autenticação On-Behalf-Of (OBO) não é suportada.

Sintoma: Configurar a autenticação On-Behalf-Of (OBO) para uma instância DAB apoiada pelo Azure Cosmos DB falha ou o token não é encaminhado como esperado.

Causa: A autenticação OBO é atualmente suportada apenas para SQL Server e Azure SQL. O suporte para Azure Cosmos DB ainda não foi implementado. Esta é uma limitação conhecida registada na edição #3159 do GitHub.

Resolução: Use um método de autenticação suportado, como a chave de conta Cosmos DB ou identidade gerida. Siga a edição do GitHub para atualizações sobre quando o suporte OBO for expandido para bases de dados não SQL Server.

O filtro GraphQL falha no Cosmos DB

Sintoma: Uma consulta GraphQL usando o operador IN numa entidade com suporte do Cosmos DB falha em tempo de execução com a mensagem Não é possível construir a operação de predicado desconhecida IN, mesmo que IN apareça no esquema via introspeção.

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

Resolução: Evite usar o operador in em consultas GraphQL contra entidades do Cosmos DB. Use uma destas soluções alternativas:

• Substitua in por múltiplas ou + q expressões para uma lista pequena e fixa de valores.
• Use múltiplos aliases de leitura pontual (item_by_pk) ao consultar por uma lista conhecida de IDs.
• Filtrar do lado do cliente após obter um conjunto de resultados mais amplo.

Agregações não são suportadas para o Cosmos DB

Sintoma: Consultas agregadas GraphQL (como contagem, soma ou vg) contra uma entidade suportada pelo Cosmos DB falham ou não estão disponíveis no esquema.

Causa: O Data API Builder atualmente não suporta operações de agregação para o Azure Cosmos DB. Agregações estão disponíveis apenas para bases de dados relacionais. Esta é uma limitação conhecida registada na edição #2849 do GitHub.

Resolução: Neste momento, não há solução alternativa no DAB. Realize agregações do lado do cliente após recuperar o conjunto de resultados, ou use diretamente a API de consulta incorporada do Cosmos DB para operações de agregação. Siga a issue do GitHub para atualizações.

Consultas em plural (lista) não podem ser desativadas para impor exclusivamente leituras de pontos

Sintoma: Os clientes conseguem emitir consultas de lista de itens amplos contra uma entidade da Cosmos DB, consumindo muitas RUs, quando a intenção é permitir apenas leituras de pontos via item_by_pk.

Causa: O Data API Builder atualmente não oferece uma opção de configuração para suprimir consultas plurais e restringir uma entidade apenas a leituras por pontos. Esta é uma limitação conhecida registada na edição #2433 do GitHub.

Resolução: Como solução parcial, restringir a ação de listagem nas permissões da entidade para limitar quais funções podem emitir consultas de lista. A supressão total do tipo de consulta plural do esquema ainda não é suportada.

Chaves de partição hierárquica (MultiHash) não são suportadas

Sintoma: Mutações contra um contentor de base de dados Cosmos que utiliza chaves de partição hierárquicas (mais do que um caminho de chave de partição) falham com o erro O valor 'tipo' 'MultiHash' especificado na definição da chave de partição é inválido. Por favor, escolha o tipo de partição 'Hash'.

Causa: O Data API Builder apenas suporta definições de chaves de partição de chave única (Hash). Contentores configurados com chaves de partição hierárquicas (MultiHash) não são suportados. Esta é uma limitação conhecida registada na edição #1733 do GitHub.

Resolução: Neste momento, não há solução alternativa no DAB. Se possível, redesenhe o contentor para usar uma única chave de partição. Se o seu modelo de dados exige chaves de partição hierárquicas, siga a edição do GitHub para atualizações sobre quando o suporte multi-hash for adicionado.

As chaves de partição MultiHash não são suportadas

Sintoma: Mutações contra um contentor da Cosmos DB que utiliza uma chave de partição hierárquica (multi-hash) falham com O valor 'tipo' 'MultiHash' especificado na definição da chave de partição é inválido. Por favor, escolha o tipo de partição 'Hash'.

Causa: O Data API Builder suporta apenas chaves de partição Hash de valor único para o Azure Cosmos DB. Contentores configurados com chaves de partição hierárquicas (MultiHash), por exemplo, /TenantId, /EntityType, /EntityId, não são suportados. Esta é uma limitação conhecida registada na edição #1733 do GitHub.

Resolução: Neste momento, não há solução alternativa no DAB. Use um contentor com uma única chave de partição Hash em vez disso. Se for necessário particionamento hierárquico, considere reestruturar o contentor ou seguir o problema do GitHub para atualizações sobre quando o suporte a chaves de partição MultiHash é adicionado.

Múltiplas mutações não são atómicas no Cosmos DB

Sintoma: Quando múltiplas mutações GraphQL são enviadas num único pedido contra entidades do Cosmos DB, uma falha numa mutação não reverte as outras. Podem ocorrer escritas parciais.

Causa: O Data API Builder não encapsula múltiplas mutações do Cosmos DB num lote de transação. Ao contrário das bases de dados relacionais, onde múltiplas mutações num pedido são executadas de forma atómica, as mutações do Cosmos DB são emitidas de forma independente. Esta é uma limitação conhecida registada na edição #1621 do GitHub.

Resolução: Desenhe a sua aplicação para tratar cada mutação do Cosmos DB como independente. Se for necessária atomicidade, use diretamente o SDK do Cosmos DB com suporte a lotes transacionais, dentro do âmbito dos itens na mesma partição lógica. Siga a issue do GitHub para receber atualizações sobre quando o suporte a mutações transacionais for adicionado ao Cosmos DB.

O nome do tipo GraphQL no ficheiro de esquema não corresponde à configuração da entidade

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

Causa: O Data API builder não valida atualmente que o nome do tipo GraphQL no ficheiro de esquema corresponde ao nome do tipo singular declarado para a entidade. Um desajuste produz silenciosamente um esquema inconsistente. Esta é uma limitação conhecida registada na edição #1556 do GitHub.

Resolução: Verifique manualmente se o nome do tipo no schema.gql (definido via diretiva @model ) corresponde ao valor singular na configuração graphql.type da entidade em dab-config.json. Por exemplo, se dab-config.json declarar "singular": "Localização", o ficheiro de esquema deve conter ype Localização @model(name:"Localização").

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

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

Causa: O Data API builder não valida atualmente se o nome da diretiva no ficheiro de esquema GraphQL coincide com o nome de tipo singular definido para a entidade. Quando diferem, o desajuste produz silenciosamente um comportamento incorreto do esquema. Esta é uma limitação conhecida registada na edição #1556 do GitHub.

Resolução: Garanta manualmente que o nome do tipo no 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": "Localização", o ficheiro de esquema deve declarar ype Localização @model(name:"Localização"). Executa o dab valide depois de fazeres alterações para detetar outros erros de configuração.

Tipos de enum no ficheiro de esquema GraphQL causam uma falha na construção do esquema

Sintoma: O DAB falha ao iniciar com uma HotChocolate.SchemaException: Incapaz de resolver a referência de tipo ... Erro OrderByInput quando o ficheiro schema.gql do Cosmos DB define um tipo numérico GraphQL usado num campo de um tipo de objeto.

Causa: O Data API Builder atualmente não suporta tipos de enum GraphQL no ficheiro de esquema do Cosmos DB. Quando um enum é usado como tipo de campo, o construtor de esquemas não consegue gerar o tipo correspondente OrderByInput e lança uma exceção não tratada. Esta é uma limitação conhecida acompanhada na edição #748 do GitHub.

Resolução: Substituir os campos enum pelos seus equivalentes escalares (por exemplo, usar String em vez de um tipo enum personalizado) no schema.gql. Aplique a validação enum na sua camada de aplicação em vez da definição do esquema DAB.

Tipos de enum no esquema GraphQL fazem com que o DAB falhe no arranque

Sintoma: O DAB não se inicia devido a um erro HotChocolate.SchemaException, como "Incapaz de resolver a referência de tipo 'None: FooOrderByInput'" quando o ficheiro de esquema Cosmos DB GraphQL define um tipo enum usado num modelo.

Causa: O construtor de esquemas do Data API builder não lida corretamente com os tipos de enum GraphQL definidos no schema.gql. Quando um enum é referenciado como tipo de campo num modelo, a geração interna do tipo OrderByInput falha em resolvê-lo, o que provoca uma falha na inicialização do esquema. Esta é uma limitação conhecida acompanhada no problema #748 do GitHub.

Solução: Evite definir tipos enum GraphQL no schema.gql para entidades do Cosmos DB. Como solução alternativa, substituir os campos enum por String e aplicar valores válidos na camada de aplicação. Siga o issue do GitHub para atualizações sobre quando o suporte a enum for adicionado.

Mapeamentos de campos, conhecidos como alias, não são suportados para entidades do Cosmos DB

Sintoma: Uma secção de mapeamento definida para uma entidade do Cosmos DB em dab-config.json não tem efeito: os nomes originais dos campos continuam expostos no esquema GraphQL em vez dos alias configurados.

Causa: A funcionalidade de mapeamentos, que permite expor nomes de colunas da base de dados sob diferentes nomes de campos na API, é implementada apenas para bases de dados relacionais. As entidades do Cosmos DB atualmente não suportam mapeamentos de campo. Esta é uma limitação conhecida registada na edição #1512 do GitHub.

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

As variáveis de mutação do GraphQL são nomes de variáveis não resolvidos, armazenados em vez de valores.

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

Causa: O Data API Builder atualmente não resolve referências de variáveis GraphQL em entradas de mutação para o Cosmos DB. A substituição de variáveis é ignorada e o nome literal da variável é escrito como o valor do campo. Este é um bug conhecido rastreado na edição #1482 do GitHub.

Resolução: Insira os valores das variáveis diretamente no corpo da mutação em vez de usar variáveis GraphQL. Por exemplo, substitua id: por id: "1234". Isto não é ideal para uso em produção, por isso siga a edição do GitHub para atualizações sobre quando o tratamento de variáveis é corrigido para mutações no Cosmos DB.

Os tipos de união no ficheiro de esquema GraphQL causam um erro 500

Sintoma: O DAB devolve um código de estado 500 em todos os pedidos GraphQL quando o schema.gql define um tipo de união GraphQL. Os registos de arranque mostram HotChocolate.SchemaException: Não foi possível resolver a referência do tipo ... OrderByInput.

Causa: O Data API Builder não suporta tipos de união GraphQL no ficheiro de esquema do Cosmos DB. Tal como os tipos enum, os tipos union fazem com que o construtor de esquemas falhe ao gerar os tipos de entrada de ordenação/filtro. Este é um bug conhecido rastreado na edição #1384 do GitHub.

Resolução: Remover definições de tipos de união do schema.gql. Modele dados polimórficos usando um único tipo de objeto com campos opcionais, ou divida os dados entre entidades separadas. Siga a edição do GitHub para atualizações sobre quando é adicionado o suporte a tipos union.

A criação de mutações falha durante a execução quando o ID é definido como anulável no esquema

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

Causa: O Cosmos DB requer o campo id para cada documento e usa-o como parte da chave de partição. Se o schema.gql declarar id como nullável (por exemplo, id: ID em vez de id: ID!), o DAB aceita o esquema mas falha em tempo de execução quando uma mutação de criação omite o campo. O esquema deveria impor a não-nulidade no momento da validação do esquema, mas atualmente não o faz. Esta lacuna está registada na edição #1238 do GitHub.

Resolução: Declare sempre o campo id como não nulo no seu esquema Cosmos DB GraphQL:

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

Garantindo ID: ID! faz com que os clientes recebam um erro claro ao nível do esquema se o ID for omitido, em vez de uma falha opaca em tempo de execução.

Relações circulares GraphQL causam uma exceção de estouro de pilha no arranque

Sintoma: O DAB crasha no arranque com uma exceção de stack overflow quando o schema.gql define tipos que se referenciam mutuamente num ciclo (por exemplo, Jogador faz referência a Jogo, e Jogo faz referência a Jogador).

Causa: O construtor de esquemas percorre todas as referências de tipos recursivamente para gerar tipos de entrada de mutações. Relações circulares causam recursão infinita, esgotando a pilha de chamadas. Este é um bug conhecido que foi registado na edição #746 do GitHub.

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

A chave de partição é sempre id, caminhos de chaves de partição personalizadas não são suportados

Sintoma: O DAB só funciona com contentores de bases de dados Cosmos que usam /id como chave de partição. Contentores particionados por qualquer outro campo (por exemplo, /userId ou /category) não podem ser consultados ou mutados corretamente.

Causa: O Data API Builder codifica o id como chave de partição para todas as entidades do Cosmos DB. Não há forma de especificar um caminho de chave de partição personalizado nem no dab-config.json nem no schema.gql. Esta é uma limitação conhecida registada na edição #747 do GitHub.

Resolução: Projete novos contentores com /id como chave de partição ao usar DAB. Para contentores existentes com uma chave de partição diferente, o DAB não é atualmente suportado. Siga a edição do GitHub para atualizações sobre quando são adicionadas chaves de partição configuráveis.

Não é suportado fazer consultas a arrays aninhados dentro de um documento (junções em itens)

pt-PT: Sintoma: Não pode filtrar ou percorrer propriedades de arrays aninhados dentro de um documento Cosmos DB usando DAB. Consultas que exigiriam uma JOIN da base de dados Cosmos entre elementos do array não retornam resultados nem erro.

Causa: O Data API Builder não suporta junções intra-documento no Cosmos DB (também conhecidas como junções intra-item), que são necessárias para consultar arrays aninhados dentro de um único documento. Esta é uma limitação conhecida registada na edição #262 do GitHub.

Resolução: Achatem arrays aninhados em entidades separadas ou documentos filhos se precisares de filtrar o seu conteúdo. Em alternativa, realize o pós-processamento do documento completo na sua camada de aplicação. Siga a edição do GitHub para atualizações sobre quando é adicionado o suporte para integração intra-documento.