Solución de problemas de Azure Cosmos DB

Soluciones para problemas comunes del emulador de Azure Cosmos DB, conectividad y configuración de esquema en Data API Builder.

Preguntas frecuentes

¿Qué es la compatibilidad de Azure Cosmos DB con DAB?

Data API Builder admite Azure Cosmos DB como back-end NoSQL. DAB se conecta a Cosmos DB mediante el SDK de .NET de Azure Cosmos DB y expone entidades como tipos de GraphQL. La compatibilidad con REST para Cosmos DB no está disponible; todas las consultas se sirven a través del punto de conexión de GraphQL.

¿Qué API usa DAB con Cosmos DB?

DAB usa la API de Azure Cosmos DB para NoSQL (anteriormente SQL API). No se admiten otras API de Cosmos DB, como MongoDB, Gremlin y Table. Asegúrese de que la cuenta de Cosmos DB se crea con la API de Azure Cosmos DB para NoSQL .

¿Se admite el emulador de Cosmos DB?

Sí. El emulador de Azure Cosmos DB es compatible con el desarrollo local. Establezca la cadena de conexión en el punto de conexión predeterminado del emulador: AccountEndpoint=https://localhost:8081/;AccountKey=<emulator-key>;. Tienes que confiar en el certificado autofirmado del emulador en la máquina de desarrollo antes de que DAB pueda conectarse.

Problemas comunes

Certificado del emulador que no es de confianza

Síntoma: DAB no se puede conectar al emulador con un error de validación de certificado o SSL.

Causa: El emulador de Azure Cosmos DB usa un certificado autofirmado que no es de confianza de forma predeterminada en el sistema operativo.

Resolución: Exporte e instale el certificado del emulador desde https://localhost:8081/_explorer/emulator.pem en el almacén de certificados raíz de confianza del equipo local. En Windows, abra el archivo de certificado e instálelo en Entidades de certificación raíz de confianza del equipo > local. Reinicie DAB después de instalar el certificado.

No se puede conectar al emulador

Síntoma: DAB no se inicia con The remote name could not be resolved: 'localhost' o se rechaza un error de conexión que apunta al puerto 8081.

Causa: El emulador no se está ejecutando o la clave de punto de conexión o cuenta de la cadena de conexión es incorrecta.

Resolución: Inicie el emulador de Azure Cosmos DB desde el menú Inicio o ejecutando el ejecutable del emulador. Confirme que la cadena de conexión usa AccountEndpoint=https://localhost:8081/ y la clave del emulador correcta, que se muestra en la página del explorador de datos del emulador en https://localhost:8081/_explorer/index.html.

No se encontró el archivo de esquema de GraphQL

Síntoma: DAB no se inicia con un error como Schema file not found o graphql-schema path is invalid.

Causa: La graphql.schema ruta de acceso de dab-config.json apunta a un archivo que no existe o usa una ruta de acceso relativa incorrecta.

Resolución: Compruebe que el archivo de esquema existe en la ruta de acceso especificada en dab-config.json. La ruta de acceso es relativa a la ubicación del archivo de configuración. Ejecute dab init con --cosmosdb_nosql-schema para regenerar la configuración con la ruta de acceso de esquema correcta y confirme que el archivo .gql o el .graphql está presente en esa ubicación.

La consulta devuelve resultados vacíos

Síntoma: Las consultas de GraphQL devuelven una lista vacía aunque el contenedor tenga datos.

Causa: El nombre del contenedor o la ruta de acceso de la clave de partición de la configuración de la entidad no coincide con el contenedor de Cosmos DB real o el nombre de la base de datos es incorrecto.

Resolución: Compruebe el valor de la entidad en source y confirme que coincide exactamente con el nombre del contenedor dab-config.json (sensible a mayúsculas y minúsculas). Compruebe que el database campo debajo data-source coincide con el nombre de la base de datos de Cosmos DB. En Azure Portal, abra el Explorador de datos de la cuenta y confirme los nombres de la base de datos y del contenedor.

Error en las conexiones TCP en modo directo con el emulador de Linux

Síntoma: DAB se bloquea o agota el tiempo de espera al conectarse al emulador de Cosmos DB en Linux a través de Docker, incluso con AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1 establecido. Las solicitudes se detienen durante los reintentos de conexión.

Causa: DAB codifica actualmente ConnectionMode.Direct, lo que hace que el SDK de Cosmos detecte puntos de conexión de partición físicos (como 172.17.0.2:1025010255) y abra conexiones TCP a ellos. Desde la máquina host, esas direcciones de contenedor no son accesibles. El modo de puerta de enlace enrutaría todo el tráfico a través de un único punto de conexión HTTPS (puerto 8081 en el emulador) y evitaría el problema por completo. Se trata de una limitación conocida que se realiza en el problema de GitHub n.º 3401.

Resolución: Establezca AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1 al iniciar el contenedor del emulador. Esto obliga al emulador a anunciar 127.0.0.1 como dirección, lo que hace que los puntos de conexión detectados sean accesibles desde el host. Hasta que el modo de puerta de enlace sea configurable en DAB, la anulación de IP es la solución alternativa recomendada para el desarrollo local.

No se admite la autenticación de En Nombre De (OBO)

Síntoma: Falla la configuración de la autenticación En-Nombre-De (OBO) para una instancia DAB respaldada por Azure Cosmos DB o el token no se reenvía como se espera.

Causa: Actualmente, la autenticación de OBO solo se admite para SQL Server y Azure SQL. Todavía no se ha implementado la compatibilidad con Azure Cosmos DB. Se trata de una limitación conocida que se sigue en la incidencia de GitHub número 3159.

Resolución: Use un método de autenticación compatible, como la clave de cuenta de Cosmos DB o la identidad administrada. Siga el problema de GitHub para obtener actualizaciones cuando la compatibilidad con OBO se expanda a bases de datos que no son de SQL Server.

Error de GraphQL en el filtro en Cosmos DB

Síntoma: Una consulta de GraphQL que utiliza el operador in en una entidad respaldada por Cosmos DB fracasa en tiempo de ejecución con el mensaje No se puede construir la operación de predicado desconocida IN, aunque in aparece en el esquema a través de la introspección.

Causa: El operador in se expone en el esquema graphQL generado para IdFilterInput y StringFilterInput, pero la lógica de traducción de filtros subyacente de Cosmos DB no la implementa. Esta falta de coincidencia entre el esquema y el ejecutor de consultas es un error conocido que se realiza en el problema de GitHub n.º 3061.

Resolución: Evite usar el operador in en las consultas de GraphQL en entidades de Cosmos DB. Use una de estas soluciones alternativas en su lugar:

• Reemplace por varias expresiones o + q para una lista pequeña y fija de valores.
• Use varios alias de lectura de punto (item_by_pk) al consultar mediante una lista conocida de identificadores.
• Filtre el lado cliente después de recuperar un conjunto de resultados más amplio.

No se admiten agregaciones para Cosmos DB

Síntoma: Las consultas agregadas de GraphQL (como count, sum o vg) en una entidad respaldada por Cosmos DB producen un error o no están disponibles en el esquema.

Causa: Data API Builder no admite actualmente operaciones de agregación para Azure Cosmos DB. Las agregaciones solo están disponibles para bases de datos relacionales. Se trata de una limitación conocida que se monitoriza en la incidencia de GitHub n.º 2849.

Resolución: No hay ninguna solución alternativa en DAB en este momento. Realice agregaciones del lado cliente después de recuperar el conjunto de resultados o use directamente la API de consulta integrada de Cosmos DB para las operaciones de agregado. Siga la incidencia de GitHub para obtener actualizaciones.

Las consultas plurales (lista) no se pueden deshabilitar para aplicar solo lecturas puntuales

Síntoma: Los clientes pueden emitir consultas de lista de elementos extensas en una entidad de Cosmos DB, que consumen RUs elevadas, cuando la intención es permitir solo lecturas puntuales a través del item_by_pk.

Causa: El generador de API de datos no proporciona actualmente una opción de configuración para suprimir consultas plurales y restringir una entidad para que apunte solo lecturas. Se trata de una limitación conocida que se sigue en el issue de GitHub n.º 2433.

Resolución: Como solución alternativa parcial, restrinja la acción de lista en los permisos de la entidad para limitar qué roles pueden emitir consultas de lista. Todavía no se admite la supresión completa del tipo de consulta plural del esquema.

No se admiten claves de partición jerárquicas (MultiHash)

Síntoma: Las modificaciones en un contenedor de Cosmos DB que usa claves de partición jerárquicas (más de un camino de clave de partición) producen el error: el valor 'kind' 'MultiHash' especificado en la definición de clave de partición no es válido. Elija el tipo de partición "Hash".

Causa: Data API Builder solo admite definiciones de clave de partición de clave única (hash). No se admiten contenedores configurados con claves de partición jerárquicas (MultiHash). Se trata de una limitación conocida que está registrada en la incidencia de GitHub n.º 1733.

Resolución: No hay ninguna solución alternativa en DAB en este momento. Si es posible, vuelva a diseñar el contenedor para usar una sola clave de partición. Si el modelo de datos requiere claves de partición jerárquicas, siga el problema de GitHub para obtener actualizaciones cuando se agregue compatibilidad con varios hash.

No se admiten claves de partición multihash

Síntoma: Las mutaciones en un contenedor de Cosmos DB que utiliza una clave de partición jerárquica (multi-hash) fallan debido a que el valor 'kind' 'MultiHash' especificado en la definición de la clave de partición es inválido. Elija el tipo de partición "Hash".

Causa: Data API Builder solo admite claves de partición hash de valor único para Azure Cosmos DB. Los contenedores configurados con claves de partición jerárquicas (MultiHash) por ejemplo, /TenantId, /EntityType, /EntityId no se admiten. Se trata de una limitación conocida documentada en la incidencia de GitHub n.º 1733.

Resolución: No hay ninguna solución alternativa en DAB en este momento. Use un contenedor con una sola clave de partición hash en su lugar. Si se requiere la creación de particiones jerárquicas, considere la posibilidad de reestructurar el contenedor o seguir el problema de GitHub para las actualizaciones cuando se agregue compatibilidad con la clave de partición MultiHash.

Varias mutaciones no son atómicas en Cosmos DB

Síntoma: Cuando se envían varias mutaciones de GraphQL en una sola solicitud a entidades de Cosmos DB, un error en una mutación no revierte a los demás. Se pueden producir escrituras parciales.

Causa: Data API Builder no encapsula varias mutaciones de Cosmos DB en un lote transaccional. A diferencia de las bases de datos relacionales, donde se ejecutan varias mutaciones en una solicitud de forma atómica, las mutaciones de Cosmos DB se emiten de forma independiente. Se trata de una limitación conocida que se rastrea en la incidencia de GitHub n.º 1621.

Resolución: Diseñe la aplicación para tratar cada mutación de Cosmos DB como independiente. Si se requiere atomicidad, use el SDK de Cosmos DB directamente con compatibilidad con lotes transaccionales, aplicados a elementos dentro de la misma partición lógica. Siga el problema en GitHub para obtener actualizaciones sobre cuándo se añadirá el soporte para mutaciones transaccionales en Cosmos DB.

El nombre de tipo graphQL en el archivo de esquema no coincide con la configuración de la entidad

Síntoma: DAB se inicia sin error, pero las consultas devuelven resultados inesperados o el tipo incorrecto, ya que el nombre del tipo GraphQL definido en schema.gql no coincide con el nombre de tipo singular configurado para la entidad en dab-config.json.

Causa: El generador de API de datos no valida actualmente que el nombre de tipo GraphQL del archivo de esquema coincida con el nombre de tipo singular declarado para la entidad. Una falta de coincidencia genera silenciosamente un esquema incoherente. Se trata de una limitación conocida que está registrada en la incidencia de GitHub n.º 1556.

Resolución: Compruebe manualmente que el nombre de tipo en schema.gql (establecido a través de la @model directiva) coincide con el valor singular en la configuración de graphql.type de la entidad en dab-config.json. Por ejemplo, si dab-config.json declara "singular": "Location", el archivo de esquema debe contener ype Location @model(name:"Location").

El nombre de tipo GraphQL en el archivo de esquema no coincide con el nombre de tipo singular de entidad

Síntoma: DAB se inicia sin error, pero las consultas devuelven resultados inesperados o el tipo incorrecto, ya que el nombre del tipo GraphQL definido en schema.gql no coincide con el nombre de tipo singular configurado para la entidad en dab-config.json.

Causa: Data API Builder no valida actualmente que el @model nombre de directiva del archivo de esquema graphQL coincida con el nombre de tipo singular establecido para la entidad. Cuando difieren, la falta de coincidencia genera silenciosamente un comportamiento de esquema incorrecto. Se trata de una limitación conocida que se realiza en el problema de GitHub n.º 1556.

Resolución: Asegúrese manualmente de que el nombre de tipo de schema.gql coincide exactamente con el valor singular de la configuración de graphql.type de la entidad en dab-config.json. Por ejemplo, si la entidad define "singular": "Location", el archivo de esquema debe declarar ype Location @model(name:"Location"). Ejecute dab validate después de realizar cambios para detectar otros errores de configuración.

Los tipos de enumeración en el archivo de esquema GraphQL provocan un error de construcción de esquema

Síntoma: DAB no se puede iniciar con HotChocolate.SchemaException: No se puede resolver la referencia de tipo ... Error OrderByInput cuando el archivo schema.gql de Cosmos DB define un tipo numérico de GraphQL usado en un campo de tipo de objeto.

Causa: Data API Builder no admite actualmente los tipos de enumeración GraphQL en el archivo de esquema de Cosmos DB. Cuando se usa una enumeración como un tipo de campo, el generador de esquemas no puede generar el tipo OrderByInput correspondiente y produce una excepción no controlada. Se trata de una limitación conocida registrada en la incidencia de GitHub n.º 748.

Resolución: Reemplace los campos de enumeración por sus equivalentes escalares (por ejemplo, use String en lugar de un tipo de enumeración personalizado) en schema.gql. Aplique la validación de enumeraciones en la capa de aplicación en lugar de en la definición del esquema DAB.

Los tipos de enumeración en el esquema GraphQL producen que DAB falle al inicio.

Síntoma: DAB no se inicia con un error "HotChocolate.SchemaException" como "No se puede resolver la referencia de tipo 'None: FooOrderByInput'" cuando el archivo de esquema GraphQL de Cosmos DB defina un tipo de enumeración que se utiliza en un modelo.

Causa: El generador de esquemas de Data API Builder no controla correctamente los tipos de enumeración graphQL definidos en schema.gql. Cuando se hace referencia a una enumeración como un tipo de campo en un modelo, la generación interna de tipos OrderByInput no puede resolverla, bloqueando la inicialización del esquema. Se trata de una limitación conocida registrada en la incidencia de GitHub n.º 748.

Resolución: Evite definir tipos de enumeración de GraphQL en schema.gql para entidades de Cosmos DB. Como solución alternativa, reemplace los campos de enumeración por String y aplique valores válidos en el nivel de aplicación. Siga la incidencia de GitHub para recibir actualizaciones acerca de cuándo se añadirá compatibilidad con enumeraciones.

Los mapeos de campos (alias) no se admiten para las entidades de Cosmos DB.

Síntoma: Una sección de asignaciones definida para una entidad de Cosmos DB en dab-config.json no tiene ningún efecto, ya que los nombres de campo originales todavía se exponen en el esquema GraphQL en lugar de los alias configurados.

Causa: La funcionalidad de mapeo, que permite exponer los nombres de columna de la base de datos bajo nombres de campo diferentes en la API, solo se implementa para bases de datos relacionales. Las entidades de Cosmos DB no admiten actualmente asignaciones de campos. Se trata de una limitación conocida que se realiza en el problema de GitHub n.º 1512.

Resolución: Use los nombres de campo exactamente como aparecen en los documentos de Cosmos DB. Si se necesita el alias, aplíquelo en el nivel de aplicación cliente. Siga el problema de GitHub para obtener actualizaciones sobre cuándo se añade compatibilidad con la asignación para Cosmos DB.

Las variables de mutación de GraphQL no se resuelven como nombres de variables almacenadas, sino que permanecen en lugar de los valores.

Síntoma: Una mutación de GraphQL que usa variables (por ejemplo, createExample(item: { id: , name: })) almacena los nombres de variable "" y "" en la base de datos en lugar de los valores reales pasados en la carga ariables.

Causa: Data API Builder no resuelve actualmente las referencias de variables de GraphQL en entradas de mutación para Cosmos DB. Se omite la sustitución de variables y el nombre de la variable literal se escribe como valor de campo. Se trata de un error conocido que se registra en el issue de GitHub #1482.

Resolución: Inserte los valores de variable directamente en el cuerpo de la mutación en lugar de usar variables GraphQL. Por ejemplo, reemplace id: por id: "1234". Esto no es ideal para su uso en producción; por lo tanto, siga el tema en GitHub para actualizaciones sobre cuándo se resolverá el manejo de variables para las mutaciones en Cosmos DB.

Los tipos de unión en el archivo del esquema de GraphQL provocan un error 500.

Síntoma: DAB devuelve un código de estado 500 en todas las solicitudes de GraphQL cuando schema.gql define un tipo de unión GraphQL. Los registros de inicio muestran HotChocolate.SchemaException: No se puede resolver la referencia de tipo ... OrderByInput.

Causa: Data API Builder no admite tipos de unión graphQL en el archivo de esquema de Cosmos DB. Al igual que los tipos de enumeración, los tipos de unión provocan un error en el generador de esquemas al generar tipos de entrada de ordenación o filtro. Se trata de un error conocido registrado en la incidencia de GitHub n.º 1384.

Resolución: Quite las definiciones de tipo de unión de schema.gql. Modele datos polimórficos mediante un único tipo de objeto con campos opcionales o divida los datos entre entidades independientes. Siga la incidencia de GitHub para obtener actualizaciones sobre cuándo se agregará soporte para tipos de unión.

Se produce un error en la mutación de creación en tiempo de ejecución cuando el identificador se define como que acepta valores NULL en el esquema.

Síntoma: Una mutación de creación devuelve un error en tiempo de ejecución aunque el esquema aparezca válido. El error se produce porque el campo id no se proporcionó o era null.

Causa: Cosmos DB requiere el campo id para cada documento y lo usa como parte de la clave de partición. Si schema.gql declara id como anulable (por ejemplo, id: ID en lugar de id: ID!), DAB acepta el esquema pero falla en tiempo de ejecución cuando una mutación de creación omite el campo. El esquema debe aplicar valores no NULL en el momento de la validación del esquema, pero actualmente no lo hace. Se realiza un seguimiento de esta brecha en el problema 1238 de GitHub.

Resolución: Declare siempre el campo id como no nulo en el esquema GraphQL de Cosmos DB.

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

Asegurando la ID: ID! hace que los clientes reciban un error claro a nivel de esquema si se omite el ID, en lugar de un fallo opaco en tiempo de ejecución.

Las relaciones circulares de GraphQL provocan una excepción de desbordamiento de pila al iniciarse

Síntoma: DAB se bloquea al iniciarse con una excepción de desbordamiento de pila cuando schema.gql define tipos que se hacen referencia mutuamente en un ciclo (por ejemplo, Player hace referencia a Game y Game hace referencia a Player).

Causa: El generador de esquemas recorre todas las referencias de tipo de forma recursiva para generar tipos de entrada de mutación. Las relaciones circulares provocan recursividad infinita y agotan la pila de llamadas. Se trata de un error conocido que se realiza en el problema de GitHub n.º 746.

Resolución: Evite las referencias de tipo circular en schema.gql. Interrumpa el ciclo quitando la referencia inversa de uno de los tipos, o modele la relación como una lista de identificadores (campos escalares) en lugar de tipos de objeto anidados. Siga el incidente de GitHub para obtener actualizaciones sobre cuándo se admitirán relaciones circulares.

La clave de partición siempre es "id"; no se admiten rutas de acceso de claves de partición personalizadas.

Síntoma: DAB solo funciona con contenedores de Cosmos DB que usan /id como clave de partición. Los contenedores particionados por cualquier otro campo (por ejemplo, /userId o /category) no se pueden consultar o mutar correctamente.

Causa: Data API Builder codifica de forma fija el id como clave de partición para todas las entidades de Cosmos DB. No hay manera de especificar una ruta de clave de partición personalizada en dab-config.json o schema.gql. Se trata de una limitación conocida que se realiza en el problema de GitHub n.º 747.

Resolución: Diseñe nuevos contenedores con /id como clave de partición al usar DAB. En el caso de los contenedores existentes con una clave de partición diferente, ACTUALMENTE no se admite DAB. Siga el problema de GitHub para obtener actualizaciones cuando se agregan claves de partición configurables.

No se admite la consulta de matrices anidadas dentro de un documento (combinaciones en elementos)

Síntoma: No se pueden filtrar ni atravesar propiedades de matriz anidadas dentro de un documento de Cosmos DB mediante DAB. Las consultas que requerirían una combinación de Cosmos DB entre elementos de matriz no devuelven ningún resultado ni un error.

Causa: Data API Builder no admite combinaciones entre documentos de Cosmos DB (también denominadas combinaciones de elementos), que son necesarias para consultar matrices anidadas dentro de un único documento. Se trata de una limitación conocida que está documentada en la incidencia de GitHub n.º 262.

Resolución: Aplane matrices anidadas en entidades independientes o documentos secundarios si necesita filtrar por su contenido. Como alternativa, realice el posprocesamiento del documento completo en la capa de aplicación. Siga la incidencia de GitHub para obtener actualizaciones acerca de cuándo se añadirá la compatibilidad con la combinación intradocumento.