Résolution des problèmes liés à Azure Cosmos DB

Solutions pour les problèmes courants d’émulateur, de connectivité et de configuration de schéma Azure Cosmos DB dans le générateur d’API de données.

Questions courantes

Qu’est-ce que la prise en charge d’Azure Cosmos DB dans DAB ?

Le générateur d’API de données prend en charge Azure Cosmos DB en tant que back-end NoSQL. DAB se connecte à Cosmos DB à l’aide du Kit de développement logiciel (SDK) .NET Azure Cosmos DB et expose des entités en tant que types GraphQL. La prise en charge REST pour Cosmos DB n’est pas disponible ; toutes les requêtes sont traitées via le point de terminaison GraphQL.

Quelle API DAB utilise-t-elle avec Cosmos DB ?

DAB utilise l’API Azure Cosmos DB pour NoSQL (anciennement API SQL). D’autres API Cosmos DB telles que MongoDB, Gremlin et Table ne sont pas prises en charge. Vérifiez que votre compte Cosmos DB est créé avec l’API Azure Cosmos DB pour NoSQL .

L’émulateur Cosmos DB est-il pris en charge ?

Yes. L’émulateur Azure Cosmos DB est pris en charge pour le développement local. Définissez la chaîne de connexion sur le point de terminaison par défaut de l’émulateur : AccountEndpoint=https://localhost:8081/;AccountKey=<emulator-key>;. Vous devez approuver le certificat auto-signé de l’émulateur sur l’ordinateur de développement avant que DAB puisse se connecter.

Problèmes courants

Certificat de l’émulateur non approuvé

Symptôme: DAB ne parvient pas à se connecter à l’émulateur avec une erreur de validation de certificat ou SSL.

Cause : L’émulateur Azure Cosmos DB utilise un certificat auto-signé qui n’est pas approuvé par défaut sur le système d’exploitation.

Résolution: Exportez et installez le certificat https://localhost:8081/_explorer/emulator.pem de l’émulateur dans le magasin de certificats racine approuvé de l’ordinateur local. Sur Windows, ouvrez le fichier de certificat et installez-le sur les autorités de certification racines approuvées de l’ordinateur > local. Redémarrez DAB après avoir installé le certificat.

Impossible de se connecter à l’émulateur

Symptôme: DAB ne parvient pas à démarrer avec The remote name could not be resolved: 'localhost' ou une connexion a refusé l’erreur pointant sur le port 8081.

Cause : L’émulateur n’est pas en cours d’exécution, ou la clé de point de terminaison ou de compte dans la chaîne de connexion est incorrecte.

Résolution: Démarrez l’émulateur Azure Cosmos DB à partir du menu Démarrer ou en exécutant l’exécutable de l’émulateur. Vérifiez que la chaîne de connexion utilise AccountEndpoint=https://localhost:8081/ et la clé d’émulateur correcte, qui s’affiche sur la page de l’Explorateur de données de l’émulateur à l’adresse https://localhost:8081/_explorer/index.html.

Fichier de schéma GraphQL introuvable

Symptôme: DAB ne parvient pas à démarrer avec une erreur telle que Schema file not found ou graphql-schema path is invalid.

Cause : Le chemin graphql.schema dans dab-config.json pointe vers un fichier qui n'existe pas ou utilise un chemin relatif incorrect.

Résolution: Vérifiez que le fichier de schéma existe au chemin d’accès spécifié dans dab-config.json. Le chemin d’accès est relatif à l’emplacement du fichier de configuration. Exécutez dab init avec --cosmosdb_nosql-schema pour régénérer la configuration avec le chemin d’accès de schéma approprié, puis vérifiez que le fichier .gql ou .graphql est présent à cet emplacement.

La requête retourne des résultats vides

Symptôme: Les requêtes GraphQL retournent une liste vide même si le conteneur a des données.

Cause : Le nom du conteneur ou le chemin de clé de partition dans la configuration de l’entité ne correspond pas au conteneur Cosmos DB réel, ou le nom de la base de données est incorrect.

Résolution : Vérifiez la valeur de source de l’entité dans dab-config.json et assurez-vous qu’elle correspond exactement au nom du conteneur (respectant la casse). Vérifiez que le database champ sous data-source correspond au nom de la base de données Cosmos DB. Dans le portail Azure, ouvrez l’Explorateur de données pour le compte et confirmez les noms de la base de données et du conteneur.

Échec des connexions TCP en mode direct avec l’émulateur Linux

Symptôme: DAB se bloque ou expire lors de la connexion à l’émulateur Linux Cosmos DB dans Docker, même avec AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1 défini. Les demandes se bloquent pendant les nouvelles tentatives de connexion.

Cause : DAB code actuellement en dur ConnectionMode.Direct, ce qui entraîne la découverte des points de terminaison de partition physique (tels que 172.17.0.2:1025010255) et l’ouverture de connexions TCP à ces points de terminaison. À partir de l’ordinateur hôte, ces adresses de conteneur sont inaccessibles. Le mode passerelle acheminerait tout le trafic sur un seul point de terminaison HTTPS (port 8081 sur l’émulateur) et éviterait entièrement le problème. Il s’agit d’une limitation connue suivie dans le problème GitHub #3401.

Résolution: Définissez AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1 lors du démarrage du conteneur de l’émulateur. Cela force l’émulateur à publier 127.0.0.1 comme adresse, ce qui rend les points de terminaison découverts accessibles à partir de l’hôte. Tant que le mode passerelle n’est pas configurable dans DAB, le remplacement IP est la solution recommandée pour le développement local.

L’authentification « On-Behalf-Of » (OBO) n’est pas prise en charge

Symptôme: La configuration de l’authentification on-Behalf-Of (OBO) pour une instance DAB sauvegardée par Azure Cosmos DB échoue ou le jeton n’est pas transféré comme prévu.

Cause : L’authentification OBO est actuellement prise en charge uniquement pour SQL Server et Azure SQL. La prise en charge d’Azure Cosmos DB n’a pas encore été implémentée. Il s’agit d’une limitation connue suivie dans le problème GitHub #3159.

Résolution: Utilisez une méthode d’authentification prise en charge, telle que la clé de compte Cosmos DB ou l’identité managée. Suivez le problème GitHub pour les mises à jour sur le moment où la prise en charge de OBO est étendue aux bases de données non-SQL Server.

GraphQL du filtre ne fonctionne pas avec Cosmos DB

Symptôme: Une requête GraphQL utilisant l’opérateur in sur une entité basée sur Cosmos DB échoue au moment de l’exécution avec Impossible de générer l’opération de prédicat inconnu IN, même si elle apparaît dans le schéma via l’introspection.

Cause : L’opérateur in est exposé dans le schéma GraphQL généré pour IdFilterInput et StringFilterInput, mais la logique de traduction de filtre Cosmos DB sous-jacente ne l’implémente pas. Cette incompatibilité entre le schéma et l’exécuteur de requête est un bogue connu suivi dans le problème GitHub #3061.

Résolution: Évitez d’utiliser l’opérateur in dans les requêtes GraphQL sur les entités Cosmos DB. Utilisez plutôt l’une de ces solutions de contournement :

• Remplacez "in" par des expressions multiples ou des expressions "+ q" pour une petite liste fixe de valeurs.
• Utilisez plusieurs alias de lecture de point (item_by_pk) lors de l’interrogation à partir d’une liste connue d'identifiants.
• Filtrez côté client après avoir récupéré un jeu de résultats plus large.

Les agrégations ne sont pas prises en charge pour Cosmos DB

Symptôme: Les requêtes d’agrégation GraphQL (telles que le nombre, la somme ou vg) sur une entité sauvegardée par Cosmos DB échouent ou ne sont pas disponibles dans le schéma.

Cause : Le générateur d’API de données ne prend actuellement pas en charge les opérations d’agrégation pour Azure Cosmos DB. Les agrégations sont disponibles uniquement pour les bases de données relationnelles. Il s’agit d’une limitation connue suivie dans le problème GitHub #2849.

Résolution: Il n’existe aucune solution de contournement dans DAB pour l’instant. Effectuez des agrégations côté client après avoir récupéré le jeu de résultats, ou utilisez l’API de requête intégrée de Cosmos DB directement pour les opérations d’agrégation. Suivez l'issue GitHub pour les mises à jour.

Les requêtes plurales (liste) ne peuvent pas être désactivées pour appliquer uniquement les lectures de points

Symptôme: Les clients peuvent émettre des requêtes de liste d'éléments globaux sur une entité Cosmos DB, ce qui consomme des unités de requête élevées, alors que l'intention est d'autoriser uniquement les lectures ponctuelles via item_by_pk.

Cause : Le générateur d’API de données ne fournit actuellement pas d’option de configuration pour supprimer les requêtes plurales et restreindre une entité pour pointer les lectures uniquement. Il s’agit d’une limitation connue suivie dans le problème GitHub #2433.

Résolution: En guise de solution de contournement partielle, limitez l’action de liste dans les autorisations de l’entité pour limiter les rôles pouvant émettre des requêtes de liste. La suppression complète du type de requête pluriel du schéma n’est pas encore prise en charge.

Les clés de partition hiérarchique (MultiHash) ne sont pas prises en charge

Symptôme: Les mutations par rapport à un conteneur Cosmos DB qui utilise des clés de partition hiérarchiques (plusieurs chemins de clé de partition) échouent avec l’erreur La valeur « type » « MultiHash » spécifiée dans la définition de clé de partition n’est pas valide. Choisissez le type de partition « Hash ».

Cause : Le générateur d’API de données prend uniquement en charge les définitions de clé de partition à clé unique (hash). Les conteneurs configurés avec des clés de partition hiérarchiques (MultiHash) ne sont pas pris en charge. Il s’agit d’une limitation connue suivie dans le problème GitHub #1733.

Résolution: Il n’existe aucune solution de contournement dans DAB pour l’instant. Si possible, reconcevoir le conteneur pour utiliser une clé de partition unique. Si les clés de partition hiérarchiques sont requises par votre modèle de données, suivez le problème GitHub pour les mises à jour sur le moment où la prise en charge du hachage multiple est ajoutée.

Les clés de partition multihash ne sont pas prises en charge

Symptôme : Les mutations par rapport à un conteneur Cosmos DB qui utilise une clé de partition hiérarchique (multi-hachage) échouent. La valeur « kind » « MultiHash » spécifiée dans la définition de la clé de partition n'est pas valide. Choisissez le type de partition « Hash ».

Cause : Le générateur d’API de données prend uniquement en charge les clés de partition de hachage à valeur unique pour Azure Cosmos DB. Les conteneurs configurés avec des clés de partition hiérarchiques (MultiHash) par exemple, /TenantId, /EntityType, /EntityId ne sont pas pris en charge. Il s’agit d’une limitation connue suivie dans le problème GitHub #1733.

Résolution: Il n’existe aucune solution de contournement dans DAB pour l’instant. Utilisez plutôt un conteneur avec une seule clé de partition de hachage. Si le partitionnement hiérarchique est requis, envisagez de restructurer le conteneur ou de suivre le problème GitHub pour les mises à jour lorsque la prise en charge de la clé de partition MultiHash est ajoutée.

Plusieurs mutations ne sont pas atomiques sur Cosmos DB

Symptôme: Lorsque plusieurs mutations GraphQL sont envoyées dans une seule requête sur les entités Cosmos DB, une défaillance dans une mutation ne restaure pas les autres. Des écritures partielles peuvent se produire.

Cause : Le générateur d’API de données n’encapsule pas plusieurs mutations Cosmos DB dans un lot transactionnel. Contrairement aux bases de données relationnelles, où plusieurs mutations dans une requête sont exécutées atomiquement, les mutations Cosmos DB sont émises indépendamment. Il s’agit d’une limitation connue suivie dans le problème GitHub #1621.

Résolution: Concevez votre application pour traiter chaque mutation Cosmos DB comme indépendante. Si l’atomicité est requise, utilisez le SDK Cosmos DB directement avec la prise en charge des transactions par lot, limitée aux éléments de la même partition logique. Suivez le ticket GitHub pour les mises à jour sur quand la prise en charge des mutations transactionnelles est ajoutée pour Cosmos DB.

Le nom de type GraphQL dans le fichier de schéma ne correspond pas à la configuration d’entité

Symptôme: DAB démarre sans erreur, mais les requêtes retournent des résultats inattendus ou le type incorrect, car le nom de type GraphQL défini dans schema.gql ne correspond pas au nom de type singulier configuré pour l’entité dans dab-config.json.

Cause : Le générateur d’API de données ne valide pas actuellement que le nom de type GraphQL dans le fichier de schéma correspond au nom de type singulier déclaré pour l’entité. Une incompatibilité produit silencieusement un schéma incohérent. Il s’agit d’une limitation connue suivie dans le problème GitHub #1556.

Résolution: Vérifiez manuellement que le nom de type dans schema.gql (défini via la @model directive) correspond à la valeur singulière dans la configuration graphql.type de l’entité dans dab-config.json. Par exemple, si dab-config.json déclare « singular » : « Location », le fichier de schéma doit contenir ype Location @model(name:"Location »).

Le nom de type GraphQL dans le fichier de schéma ne correspond pas au nom de type unique d’entité

Symptôme: DAB démarre sans erreur, mais les requêtes retournent des résultats inattendus ou le type incorrect, car le nom de type GraphQL défini dans schema.gql ne correspond pas au nom de type singulier configuré pour l’entité dans dab-config.json.

Cause : Le générateur d’API de données ne valide pas actuellement que le @model nom de directive dans le fichier de schéma GraphQL correspond au nom de type singulier défini pour l’entité. Lorsqu’elles diffèrent, l’incompatibilité produit silencieusement un comportement de schéma incorrect. Il s’agit d’une limitation connue suivie dans le problème GitHub #1556.

Résolution: Vérifiez manuellement que le nom de type dans schema.gql correspond exactement à la valeur singulière dans la configuration graphql.type de l’entité dans dab-config.json. Par exemple, si l’entité définit « singular » : « Location », le fichier de schéma doit déclarer ype Location @model(name:"Location »). Exécutez la validation dab après avoir apporté des modifications pour intercepter d’autres erreurs de configuration.

Les types d’énumération dans le fichier de schéma GraphQL provoquent un échec de génération de schéma

Symptôme: DAB ne parvient pas à démarrer avec un HotChocolate.SchemaException : Impossible de résoudre la référence de type ... Erreur OrderByInput lorsque le fichier schema.gql Cosmos DB définit un type num GraphQL utilisé sur un champ de type objet.

Cause : Le générateur d’API de données ne prend actuellement pas en charge les types d’énumération GraphQL dans le fichier de schéma Cosmos DB. Lorsqu’une énumération est utilisée comme type de champ, le générateur de schémas ne peut pas générer le type OrderByInput correspondant et lève une exception non gérée. Il s’agit d’une limitation connue suivie dans le problème GitHub #748.

Résolution: Remplacez les champs d’énumération par leurs équivalents scalaires (par exemple, utilisez String au lieu d’un type d’énumération personnalisé) dans schema.gql. Appliquez la validation d'énumération dans votre couche d'application plutôt que dans la définition de schéma BDA.

Les types d’énumération dans le schéma GraphQL provoquent l’échec du DAB au démarrage

Symptôme: DAB ne parvient pas à démarrer avec une erreur HotChocolate.SchemaException telle que Impossible de résoudre la référence de type « None : FooOrderByInput » lorsque le fichier de schéma GraphQL Cosmos DB définit un type d’énumération utilisé sur un modèle.

Cause : Le générateur de schémas du générateur d’API de données ne gère pas correctement les types d’énumération GraphQL définis dans schema.gql. Lorsqu’une énumération est référencée en tant que type de champ sur un modèle, la génération de type OrderByInput interne ne parvient pas à la résoudre, ce qui bloque l’initialisation du schéma. Il s’agit d’une limitation connue suivie dans le problème GitHub #748.

Résolution: Évitez de définir des types d’énumération GraphQL dans schema.gql pour les entités Cosmos DB. Pour contourner ce problème, remplacez les champs d’énumération par String et appliquez des valeurs valides dans la couche Application. Suivez l’issue GitHub pour les mises à jour afin de savoir quand la prise en charge des énumérations sera ajoutée.

Les mappages de champs (alias) ne sont pas pris en charge pour les entités Cosmos DB

Symptôme: Une section de mappages définie pour une entité Cosmos DB dans dab-config.json n’a aucun effet ; les noms de champs d’origine sont toujours exposés dans le schéma GraphQL au lieu des alias configurés.

Cause : La fonctionnalité de mappages, qui permet d’exposer des noms de colonnes de base de données sous différents noms de champs dans l’API, est implémentée uniquement pour les bases de données relationnelles. Les entités Cosmos DB ne prennent actuellement pas en charge les mappages de champs. Il s’agit d’une limitation connue suivie dans le problème GitHub #1512.

Résolution: Utilisez les noms de champs exactement comme ils apparaissent dans les documents Cosmos DB. Si l’alias est nécessaire, appliquez-le dans la couche d’application cliente. Suivez le ticket GitHub pour les mises à jour concernant l'ajout du support du mappage pour Cosmos DB.

Les variables de mutation GraphQL ne sont pas des noms de variables résolus stockés au lieu de valeurs

Symptôme: Une mutation GraphQL qui utilise des variables (par exemple, createExample(item : { id : , name : })) stocke les noms de variables « » et « » dans la base de données au lieu des valeurs réelles passées dans la charge utile des ariables.

Cause : Le générateur d’API de données ne résout actuellement pas les références de variables GraphQL dans les entrées de mutation pour Cosmos DB. La substitution de variable est ignorée et le nom de la variable littérale est écrit en tant que valeur de champ. Il s’agit d’un bogue connu suivi dans le problème GitHub #1482.

Résolution: Inlinez les valeurs des variables directement dans le corps de mutation au lieu d’utiliser des variables GraphQL. Par exemple, remplacez l’ID : par l’ID : « 1234 ». Ce n'est pas idéal pour une utilisation en production, alors suivez le problème sur GitHub pour les mises à jour concernant la correction de la gestion des variables pour les mutations Cosmos DB.

Les types d’union dans le fichier de schéma GraphQL provoquent une erreur 500

Symptôme: DAB retourne un code d’état 500 sur toutes les requêtes GraphQL lorsque schema.gql définit un type d’union GraphQL. Les logs de démarrage montrent HotChocolate.SchemaException : Impossible de résoudre la référence de type ... OrderByInput.

Cause : Le générateur d’API de données ne prend pas en charge les types d’union GraphQL dans le fichier de schéma Cosmos DB. Comme les types d’énumération, les types union provoquent l’échec du générateur de schémas lors de la génération de types d’entrée de tri/filtre. Il s’agit d’un bogue connu suivi dans le problème GitHub #1384.

Résolution: Supprimez les définitions de type union de schema.gql. Modéliser des données polymorphes à l’aide d’un type d’objet unique avec des champs facultatifs ou fractionner les données entre des entités distinctes. Suivez l'incident sur GitHub pour les mises à jour lorsque la prise en charge du type union est ajoutée.

La mutation de création échoue au moment de l’exécution lorsque l’ID est défini comme nullable dans le schéma

Symptôme: Une mutation de création retourne une erreur d’exécution même si le schéma apparaît valide. L’erreur se produit car le champ ID n’a pas été fourni ou a été null.

Cause : Cosmos DB requiert le champ ID de chaque document et l’utilise dans le cadre de la clé de partition. Si schema.gql déclare l’ID comme nullable (par exemple, id : ID au lieu d’ID : ID !), DAB accepte le schéma, mais échoue au moment de l’exécution lorsqu’une mutation de création omet le champ. Le schéma doit appliquer non null au moment de la validation du schéma, mais ce n’est pas le cas actuellement. Cet écart est suivi dans le problème GitHub #1238.

Résolution: Déclarez toujours le champ ID comme non null dans votre schéma GraphQL Cosmos DB :

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

Vérification de l’ID : ID ! provoque la réception par les clients d’une erreur claire au niveau du schéma si l’ID est omis, plutôt qu’une défaillance d’exécution opaque.

Les relations circulaires dans GraphQL provoquent une exception de débordement de pile au démarrage.

Symptôme: DAB se bloque au démarrage avec une exception de dépassement de capacité de pile lorsque schema.gql définit des types qui se référencent mutuellement dans un cycle (par exemple, Player fait référence à Game, et Game fait référence à Player).

Cause : Le constructeur de schémas parcourt toutes les références de type de manière récursive pour générer des types d'entrée de mutation. Les relations circulaires entraînent une récursivité infinie, ce qui épuise la pile des appels. Il s’agit d’un bogue connu suivi dans le problème GitHub #746.

Résolution: Évitez les références de type circulaire dans schema.gql. Arrêtez le cycle en supprimant la référence back-reference de l’un des types ou modélisez la relation sous forme de liste d’ID (champs scalaires) plutôt que de types d’objets imbriqués. Suivez le sujet GitHub pour les mises à jour sur la prise en charge des relations circulaires.

La clé de partition est toujours « id » et les chemins de clé de partition personnalisés ne sont pas supportés.

Symptôme: DAB fonctionne uniquement avec les conteneurs Cosmos DB qui utilisent /id comme clé de partition. Les conteneurs partitionnés par tout autre champ (par exemple, /userId ou /category) ne peuvent pas être interrogés ou mutés correctement.

Cause : Le générateur d'API de données fixe l'identifiant comme clé de partition pour toutes les entités Cosmos DB. Il n’existe aucun moyen de spécifier un chemin de clé de partition personnalisé dans dab-config.json ou schema.gql. Il s’agit d’une limitation connue suivie dans le problème GitHub #747.

Résolution: Concevez de nouveaux conteneurs avec /id comme clé de partition lors de l’utilisation de DAB. Pour les conteneurs existants avec une autre clé de partition, DAB n’est actuellement pas pris en charge. Suivez le ticket GitHub pour les mises à jour concernant l'ajout de clés de partition configurables.

L’interrogation de tableaux imbriqués dans un document (jointures par élément) n’est pas prise en charge.

Symptôme: Vous ne pouvez pas filtrer ou parcourir les propriétés de tableau imbriquées dans un document Cosmos DB à l’aide de DAB. Les requêtes qui nécessitent une jointure Cosmos DB entre les éléments de tableau ne retournent aucun résultat ou une erreur.

Cause : Le générateur d’API de données ne prend pas en charge les jointures intra-document Cosmos DB (également appelées jointures in-item), qui sont nécessaires pour interroger des tableaux imbriqués dans un seul document. Il s’agit d’une limitation connue suivie dans le problème GitHub #262.

Résolution: Aplatissez les tableaux imbriqués pour en faire des entités distinctes ou des documents enfants si vous devez filtrer sur leur contenu. Vous pouvez également effectuer une post-traitement du document complet dans la couche application. Suivez le problème GitHub pour les mises à jour sur le moment où la prise en charge des jointures intra-document est ajoutée.