Problemen met Azure Cosmos DB oplossen

Oplossingen voor veelvoorkomende problemen met de Azure Cosmos DB-emulator, connectiviteit en schemaconfiguratie in Data API Builder.

Veelgestelde vragen

Wat is Azure Cosmos DB-ondersteuning in DAB?

Data API Builder ondersteunt Azure Cosmos DB als een NoSQL-back-end. DAB maakt verbinding met Cosmos DB met behulp van de Azure Cosmos DB .NET SDK en maakt entiteiten beschikbaar als GraphQL-typen. REST-ondersteuning voor Cosmos DB is niet beschikbaar; alle query's worden geleverd via het GraphQL-eindpunt.

Welke API gebruikt DAB met Cosmos DB?

DAB maakt gebruik van de Azure Cosmos DB for NoSQL-API (voorheen SQL API). Andere Cosmos DB-API's, zoals MongoDB, Gremlin en Table, worden niet ondersteund. Zorg ervoor dat uw Cosmos DB-account is gemaakt met de Azure Cosmos DB for NoSQL-API .

Wordt de Cosmos DB-emulator ondersteund?

Ja. De Azure Cosmos DB-emulator wordt ondersteund voor lokale ontwikkeling. Stel de verbindingsreeks in op het standaardeindpunt van de emulator: AccountEndpoint=https://localhost:8081/;AccountKey=<emulator-key>;. U moet het zelfondertekende certificaat van de emulator vertrouwen op de ontwikkelcomputer voordat DAB verbinding kan maken.

Veelvoorkomende problemen

Emulatorcertificaat niet vertrouwd

Symptoom: DAB kan geen verbinding maken met de emulator met een SSL- of certificaatvalidatiefout.

Oorzaak: De Azure Cosmos DB-emulator maakt gebruik van een zelfondertekend certificaat dat niet standaard wordt vertrouwd op het besturingssysteem.

Resolutie: Exporteer en installeer het emulatorcertificaat vanuit https://localhost:8081/_explorer/emulator.pem het vertrouwde basiscertificaatarchief van de lokale computer. Open in Windows het certificaatbestand en installeer het naar de vertrouwde basiscertificeringsinstanties van de lokale computer>. Start DAB opnieuw nadat u het certificaat hebt geïnstalleerd.

Kan geen verbinding maken met de emulator

Symptoom: DAB start niet of er is een verbindingsweigering met verwijzing naar poort 8081.

Oorzaak: De emulator wordt niet uitgevoerd of de eindpunt- of accountsleutel in de verbindingsreeks is onjuist.

Resolutie: Start de Azure Cosmos DB-emulator vanuit het startmenu of door het uitvoerbare bestand van de emulator uit te voeren. Controleer of de verbindingsreeks gebruikmaakt van AccountEndpoint=https://localhost:8081/ en dat de juiste emulatorsleutel aanwezig is, die wordt weergegeven op de data explorer-pagina van de emulator op https://localhost:8081/_explorer/index.html.

GraphQL-schemabestand is niet gevonden

Symptoom: DAB kan niet worden gestart met een fout zoals Schema file not found of graphql-schema path is invalid.

Oorzaak: Het graphql.schema pad in dab-config.json verwijst naar een bestand dat niet bestaat of een onjuist relatief pad gebruikt.

Resolutie: Controleer of het schemabestand bestaat op het pad dat is opgegeven in dab-config.json. Het pad is relatief aan de locatie van het configuratiebestand. Voer dab init uit met --cosmosdb_nosql-schema om de configuratie opnieuw te genereren met het juiste schemapad en controleer vervolgens of het .gql bestand .graphql aanwezig is op die locatie.

Query retourneert lege resultaten

Symptoom: GraphQL-query's retourneren een lege lijst, ook al bevat de container gegevens.

Oorzaak: De containernaam of het partitiesleutelpad in de entiteitsconfiguratie komt niet overeen met de werkelijke Cosmos DB-container of de databasenaam is onjuist.

Resolutie: Controleer de waarde source van dab-config.json de entiteit en bevestig dat deze overeenkomt met de exacte containernaam (hoofdlettergevoelig). Controleer of het database veld onder data-source overeenkomt met de naam van de Cosmos DB-database. Open in Azure Portal de Data Explorer voor het account en bevestig de database- en containernamen.

TCP-verbindingen in de directe modus mislukken met de Linux-emulator

Symptoom: DAB loopt vast of treedt er een time-out op wanneer er verbinding wordt gemaakt met de Cosmos DB Linux-emulator in Docker, zelfs wanneer AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1 is ingesteld. Aanvragen stagneren tijdens hernieuwde verbindingspogingen.

Oorzaak: DAB codeert momenteel ConnectionMode.Direct, waardoor de Cosmos SDK fysieke partitie-eindpunten (zoals 172.17.0.2:1025010255) detecteert en TCP-verbindingen ernaar opent. Vanaf de hostcomputer zijn deze containeradressen onbereikbaar. De gatewaymodus routeert al het verkeer via één HTTPS-eindpunt (poort 8081 op de emulator) en voorkomt het probleem volledig. Dit is een bekende beperking die wordt bijgehouden in GitHub-probleem #3401.

Resolutie: Stel AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1 in bij het starten van de emulatorcontainer. Dit dwingt de emulator om 127.0.0.1 als adres te adverteren, waardoor de gedetecteerde eindpunten bereikbaar zijn vanaf de host. Totdat de gatewaymodus in DAB kan worden geconfigureerd, is de IP-onderdrukking de aanbevolen tijdelijke oplossing voor lokale ontwikkeling.

Verificatie On-Behalf-Of (OBO) wordt niet ondersteund

Symptoom: Het configureren van on-Behalf-Of -verificatie (OBO) voor een DOOR Azure Cosmos DB ondersteund DAB-exemplaar mislukt of het token wordt niet doorgestuurd zoals verwacht.

Oorzaak: OBO-verificatie wordt momenteel alleen ondersteund voor SQL Server en Azure SQL. Ondersteuning voor Azure Cosmos DB is nog niet geïmplementeerd. Dit is een bekende beperking die wordt bijgehouden in GitHub-probleem #3159.

Resolutie: Gebruik een ondersteunde verificatiemethode, zoals de cosmos DB-accountsleutel of beheerde identiteit. Volg het GitHub-probleem voor updates wanneer OBO-ondersteuning wordt uitgebreid naar niet-SQL Server-databases.

GraphQL filter mislukt bij gebruik met Cosmos DB

Symptoom: Een GraphQL-query met behulp van de in-operator voor een door Cosmos DB ondersteunde entiteit faalt tijdens runtime met Kan de onbekende predicatebewerking IN niet bouwen, ook al wordt deze via introspectie in het schema weergegeven.

Oorzaak: De in-operator wordt weergegeven in het gegenereerde GraphQL-schema voor IdFilterInput en StringFilterInput, maar de onderliggende Cosmos DB-filteromzettingslogica implementeert deze niet. Deze mismatch tussen het schema en de query-uitvoerder is een bekende fout die wordt bijgehouden in GitHub-probleem #3061.

Resolutie: Vermijd het gebruik van de in-operator in GraphQL-query's voor Cosmos DB-entiteiten. Gebruik in plaats daarvan een van deze tijdelijke oplossingen:

• Vervang in door meerdere of + q-expressies voor een kleine, vaste lijst met waarden.
• Gebruik meerdere point-read aliassen (item_by_pk) bij het uitvoeren van query's op een bekende lijst met id's.
• Filter aan de clientzijde na het ophalen van een bredere resultaatset.

Aggregaties worden niet ondersteund voor Cosmos DB

Symptoom: GraphQL-aggregatiequery's (zoals aantal, som of vg) gericht op een entiteit aangedreven door Cosmos DB mislukken of zijn niet beschikbaar in het schema.

Oorzaak: Data API Builder biedt momenteel geen ondersteuning voor aggregatiebewerkingen voor Azure Cosmos DB. Aggregaties zijn alleen beschikbaar voor relationele databases. Dit is een bekende beperking die wordt bijgehouden in GitHub-probleem #2849.

Resolutie: Er is op dit moment geen tijdelijke oplossing binnen DAB. Voer aggregaties aan de clientzijde uit nadat u de resultatenset hebt opgehaald of gebruik de ingebouwde query-API van Cosmos DB rechtstreeks voor statistische bewerkingen. Volg het GitHub-probleem voor updates.

Meervoudige query's (lijst) kunnen niet worden uitgeschakeld om alleen puntlezen af te dwingen

Symptoom: Clients kunnen brede itemlijstquery's uitvoeren op een Cosmos DB-entiteit, waardoor veel RU's worden verbruikt, terwijl de intentie is om alleen puntlezingen via item_by_pk toe te staan.

Oorzaak: Data API Builder biedt momenteel geen configuratieoptie om meervoudige query's te onderdrukken en een entiteit te beperken tot alleen point-lezers. Dit is een bekende beperking die wordt bijgehouden in GitHub-probleem #2433.

Resolutie: Als gedeeltelijke tijdelijke oplossing beperkt u de lijstactie in de machtigingen van de entiteit om te beperken welke rollen lijstquery's kunnen uitgeven. Volledige onderdrukking van het meervoudsquerytype van het schema wordt nog niet ondersteund.

Hiërarchische partitiesleutels (MultiHash) worden niet ondersteund

Symptoom: Mutaties tegen een Cosmos DB-container die gebruikmaakt van hiërarchische partitiesleutels (meer dan één partitiesleutelpad) mislukken met de fout De 'soort' waarde 'MultiHash' die is opgegeven in de definitie van de partitiesleutel is ongeldig. Kies het 'Hash' partitietype.

Oorzaak: Data API Builder ondersteunt alleen partitiesleuteldefinities met één sleutel (Hash). Containers die zijn geconfigureerd met hiërarchische partitiesleutels (MultiHash) worden niet ondersteund. Dit is een bekende beperking die wordt bijgehouden in GitHub-probleem #1733.

Resolutie: Er is op dit moment geen tijdelijke oplossing binnen DAB. Ontwerp indien mogelijk de container opnieuw om één partitiesleutel te gebruiken. Als hiërarchische partitiesleutels vereist zijn voor uw gegevensmodel, volgt u het GitHub-probleem voor updates wanneer ondersteuning voor meerdere hashs wordt toegevoegd.

MultiHash-partitiesleutels worden niet ondersteund

Symptoom: Mutaties tegen een Cosmos DB-container die een hiërarchische (multi-hash) partitiesleutel gebruikt, mislukken. De 'soort'-waarde 'MultiHash' zoals opgegeven in de partitiesleuteldefinitie is ongeldig. Gelieve het 'Hash'-partitietype te kiezen.

Oorzaak: Data API Builder ondersteunt alleen hash-partitiesleutels met één waarde voor Azure Cosmos DB. Containers die zijn geconfigureerd met hiërarchische partitiesleutels (MultiHash), bijvoorbeeld /TenantId, /EntityType, /EntityId, worden niet ondersteund. Dit is een bekende beperking die wordt bijgehouden in GitHub-probleem #1733.

Resolutie: Er is op dit moment geen tijdelijke oplossing binnen DAB. Gebruik in plaats daarvan een container met één hash-partitiesleutel. Als hiërarchische partitionering is vereist, kunt u overwegen de container te herstructureren of het GitHub-probleem te volgen voor updates wanneer ondersteuning voor multiHash-partitiesleutels wordt toegevoegd.

Meerdere mutaties zijn niet atomisch in Cosmos DB

Symptoom: Wanneer meerdere GraphQL-mutaties worden verzonden in één aanvraag tegen Cosmos DB-entiteiten, wordt een fout in één mutatie niet teruggedraaid. Gedeeltelijke schrijfbewerkingen kunnen optreden.

Oorzaak: Data API Builder verpakt niet meerdere Cosmos DB-mutaties in een transactionele batch. In tegenstelling tot relationele databases, waarbij meerdere mutaties in een aanvraag atomisch worden uitgevoerd, worden Cosmos DB-mutaties onafhankelijk uitgegeven. Dit is een bekende beperking die wordt bijgehouden in GitHub-probleem #1621.

Resolutie: Ontwerp uw toepassing om elke Cosmos DB-mutatie als onafhankelijk te behandelen. Als atomiciteit is vereist, gebruikt u de Cosmos DB SDK rechtstreeks met transactionele batchondersteuning, die is gericht op items binnen dezelfde logische partitie. Volg het GitHub-probleem voor updates wanneer ondersteuning voor transactionele mutatie wordt toegevoegd voor Cosmos DB.

De naam van het GraphQL-type in het schemabestand komt niet overeen met de entiteitsconfiguratie

Symptoom: DAB begint zonder fout, maar query's retourneren onverwachte resultaten of het verkeerde type, omdat de GraphQL-typenaam die is gedefinieerd in schema.gql niet overeenkomt met de enkelvoudige typenaam die is geconfigureerd voor de entiteit in dab-config.json.

Oorzaak: Data API Builder valideert momenteel niet dat de GraphQL-typenaam in het schemabestand overeenkomt met de naam van het enkelvoudige type die voor de entiteit is gedeclareerd. Een mismatch produceert stilletjes een inconsistent schema. Dit is een bekende beperking die wordt bijgehouden in GitHub-probleem #1556.

Resolutie: Controleer handmatig of de typenaam in schema.gql (ingesteld via de @model instructie) overeenkomt met de enkelvoudige waarde in de graphql.type-configuratie van de entiteit in dab-config.json. Als dab-config.json bijvoorbeeld 'singular': 'Location' declareert, moet het schemabestand ype Location @model(name:"Location" bevatten).

De naam van het GraphQL-type in het schemabestand komt niet overeen met de naam van het enkelvoudige entiteitstype

Symptoom: DAB begint zonder fout, maar query's retourneren onverwachte resultaten of het verkeerde type, omdat de GraphQL-typenaam die is gedefinieerd in schema.gql niet overeenkomt met de enkelvoudige typenaam die is geconfigureerd voor de entiteit in dab-config.json.

Oorzaak: Data API Builder valideert momenteel niet dat de @model instructienaam in het GraphQL-schemabestand overeenkomt met de naam van het enkelvoudige type dat is ingesteld voor de entiteit. Wanneer ze verschillen, leidt de afwijking stilzwijgend tot onjuist schemagedrag. Dit is een bekende beperking die wordt bijgehouden in GitHub-probleem #1556.

Resolutie: Zorg er handmatig voor dat de typenaam in schema.gql exact overeenkomt met de enkelvoudige waarde in de graphql.type-configuratie van de entiteit in dab-config.json. Als de entiteit bijvoorbeeld 'singular' definieert: 'Location', moet het schemabestand de ype-locatie @model(name:"Location" declareren). Voer dab-validatie uit nadat u wijzigingen hebt aangebracht om andere configuratiefouten op te vangen.

Opsommingstypen in het GraphQL-schemabestand veroorzaken een fout bij het bouwen van een schema

Symptoom: DAB kan niet worden gestart met een HotChocolate.SchemaException: Kan typereferentie niet oplossen ... OrderByInput-fout wanneer het Cosmos DB schema.gql-bestand een GraphQL num-type definieert dat wordt gebruikt voor een objecttypeveld.

Oorzaak: Data API Builder biedt momenteel geen ondersteuning voor GraphQL-enumtypen in het Cosmos DB-schemabestand. Wanneer een enum wordt gebruikt als veldtype, kan de opbouwfunctie voor schema's het bijbehorende OrderByInput-type niet genereren en wordt er een onverwerkte uitzondering gegenereerd. Dit is een bekende beperking die wordt bijgehouden in GitHub-probleem #748.

Resolutie: Vervang enumvelden door hun scalaire equivalenten (gebruik bijvoorbeeld Tekenreeks in plaats van een aangepast enumtype) in schema.gql. Enumvalidatie toepassen in de toepassingslaag in plaats van in de DAB-schemadefinitie.

Enum-typen in het GraphQL-schema zorgen ervoor dat DAB mislukt bij het opstarten

Symptoom: DAB kan niet worden gestart met een HotChocolate.SchemaException-fout, zoals 'Kan typeverwijzing 'None: FooOrderByInput' niet oplossen' wanneer het Cosmos DB GraphQL-schemabestand een enumtype definieert dat in een model wordt gebruikt.

Oorzaak: De schemabouwer van Data API Builder verwerkt GraphQL-enumtypen die zijn gedefinieerd in schema.gql niet correct. Wanneer naar een enum wordt gerefereerd als veldtype op een model, lukt het de interne generatie van het OrderByInput-type niet om dit op te lossen, waardoor het initialiseren van het schema vastloopt. Dit is een bekende beperking die wordt bijgehouden in GitHub-probleem #748.

Resolutie: Vermijd het definiëren van GraphQL-enumtypen in schema.gql voor Cosmos DB-entiteiten. Gebruik als tijdelijke oplossing strings in plaats van enumvelden en zorg ervoor dat geldige waarden worden afgedwongen in de toepassing. Volg het GitHub-probleem voor updates wanneer enum-ondersteuning wordt toegevoegd.

Veldtoewijzingen (aliassen) worden niet ondersteund voor Cosmos DB-entiteiten

Symptoom: Een sectie toewijzingen die is gedefinieerd voor een Cosmos DB-entiteit in dab-config.json heeft geen effect; de oorspronkelijke veldnamen worden nog steeds weergegeven in het GraphQL-schema in plaats van de geconfigureerde aliassen.

Oorzaak: De toewijzingsfunctie, waarmee databasekolomnamen onder verschillende veldnamen in de API kunnen worden weergegeven, wordt alleen geïmplementeerd voor relationele databases. Cosmos DB-entiteiten bieden momenteel geen ondersteuning voor veldtoewijzingen. Dit is een bekende beperking die wordt bijgehouden in GitHub-probleem #1512.

Resolutie: Gebruik de veldnamen precies zoals ze worden weergegeven in de Cosmos DB-documenten. Als aliasing nodig is, past u deze toe in de clienttoepassingslaag. Volg voor updates de GitHub-issue wanneer toewijzingsondersteuning voor Cosmos DB wordt toegevoegd.

GraphQL mutatievariabelen zijn niet opgeloste variabelenamen die zijn opgeslagen in plaats van waarden

Symptoom: Een GraphQL-mutatie die gebruikmaakt van variabelen (bijvoorbeeld createExample(item: { id: , name: })) slaat de plaatsaanduidingen "" en "" voor variabelen op in de database in plaats van de werkelijke waarden die zijn doorgegeven in de gegevens.

Oorzaak: Data API Builder lost momenteel geen GraphQL-variabeleverwijzingen op in mutatie-invoer voor Cosmos DB. Het vervangen van variabelen wordt overgeslagen en de naam van de letterlijke variabele wordt geschreven als de veldwaarde. Dit is een bekende fout die wordt bijgehouden in GitHub-probleem #1482.

Oplossing: Verwerk de waarden van de variabelen rechtstreeks in het mutatielichaam, zonder gebruik te maken van GraphQL-variabelen. Vervang bijvoorbeeld id: door id: '1234'. Dit is niet ideaal voor productiegebruik, dus volg het GitHub-probleem voor updates wanneer variabele verwerking is opgelost voor Cosmos DB-mutaties.

Samenvoegtypen in het GraphQL-schemabestand veroorzaken een 500-fout

Symptoom: DAB retourneert een 500-statuscode voor alle GraphQL-aanvragen wanneer schema.gql een Type GraphQL-samenvoeging definieert. De opstartlogboeken tonen HotChocolate.SchemaException: Kan typeverwijzing niet oplossen... OrderByInput.

Oorzaak: Data API Builder biedt geen ondersteuning voor GraphQL-samenvoegtypen in het Cosmos DB-schemabestand. Net als enumtypen zorgen samenvoegtypen ervoor dat de opbouwfunctie voor schema's mislukt bij het genereren van invoertypen voor sorteren/filteren. Dit is een bekende fout die wordt bijgehouden in GitHub-probleem #1384.

Resolutie: Verwijder samenvoegtypedefinities uit schema.gql. Modelleer polymorfe gegevens met één objecttype met optionele velden of splits de gegevens over afzonderlijke entiteiten. Volg het GitHub-ticket voor updates over wanneer ondersteuning voor unietypen wordt toegevoegd.

Het maken van mutatie mislukt tijdens runtime wanneer id is gedefinieerd als nullable in het schema

Symptoom: Een create mutatie retourneert een runtimefout, ook al lijkt het schema geldig. De fout treedt op omdat het id-veld niet is opgegeven of null was.

Oorzaak: Cosmos DB vereist het id-veld voor elk document en gebruikt dit als onderdeel van de partitiesleutel. Als schema.gql het id-veld als optioneel declareert (bijvoorbeeld id: ID in plaats van id: ID!), accepteert DAB het schema, maar het faalt tijdens de runtime wanneer een creatiemutatie het veld weglaat. Het schema moet niet-null afdwingen tijdens schemavalidatie, maar momenteel niet. Deze kloof wordt bijgehouden in GitHub-probleem 1238.

Resolutie: Declareer altijd het id-veld als niet-null in uw Cosmos DB GraphQL-schema:

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

Ervoor zorgen dat id: ID! zorgt ervoor dat cliënten een duidelijke fout op schemaniveau ontvangen als de id wordt weggelaten, in plaats van een ondoorzichtige fout op runtime-niveau.

Circulaire GraphQL-relaties veroorzaken een stack-overloop-uitzondering bij het opstarten

Symptoom: DAB loopt vast bij het opstarten met een stack overflow-uitzondering wanneer schema.gql typen definieert die naar elkaar verwijzen in een cyclus (bijvoorbeeld Speler verwijst naar Game en Game-verwijzingen Player).

Oorzaak: De schemabouwer doorloopt alle typeverwijzingen recursief om mutatieinvoertypen te genereren. Kringrelaties veroorzaken oneindige recursie, waardoor de aanroepstack wordt uitgeput. Dit is een bekende fout die wordt bijgehouden in GitHub-probleem #746.

Resolutie: Vermijd circulaire verwijzingen in schema.gql. Verbreek de cyclus door de back-reference te verwijderen uit een van de typen of de relatie te modelleren als een lijst met id's (scalaire velden) in plaats van geneste objecttypen. Volg het GitHub-issue voor updates over wanneer kringrelaties worden ondersteund.

Partitiesleutel is altijd id aangepaste partitiesleutelpaden worden niet ondersteund

Symptoom: DAB werkt alleen met Cosmos DB-containers die /id als partitiesleutel gebruiken. Containers die zijn gepartitioneerd door een ander veld (bijvoorbeeld /userId of /category) kunnen niet correct worden opgevraagd of gemuteerd.

Oorzaak: Data API Builder gebruikt id als vaste partitiesleutel voor alle Cosmos DB-entiteiten. Er is geen manier om een aangepast partitiesleutelpad op te geven in dab-config.json of schema.gql. Dit is een bekende beperking die wordt bijgehouden in GitHub-probleem #747.

Resolutie: Ontwerp nieuwe containers met /id als partitiesleutel bij gebruik van DAB. Voor bestaande containers met een andere partitiesleutel wordt DAB momenteel niet ondersteund. Volg het GitHub-probleem voor updates wanneer configureerbare partitiesleutels worden toegevoegd.

Het opvragen van geneste matrices in een document (in-item joins) wordt niet ondersteund

Symptoom: U kunt geneste matrixeigenschappen in een Cosmos DB-document niet filteren of doorlopen met BEHULP van DAB. Query's waarvoor een Cosmos DB JOIN voor matrixelementen is vereist, retourneren geen resultaten of een fout.

Oorzaak: Data API Builder biedt geen ondersteuning voor Cosmos DB intra-document joins (ook wel in-item joins genoemd), die nodig zijn om een query uit te voeren op geneste matrices binnen één document. Dit is een bekende beperking die wordt bijgehouden in GitHub-probleem #262.

Resolutie: Geneste matrices plat maken in afzonderlijke entiteiten of onderliggende documenten als u wilt filteren op hun inhoud. U kunt ook naverwerking uitvoeren van het volledige document in de toepassingslaag. Volg de GitHub-issue voor updates over wanneer ondersteuning voor intra-document join wordt toegevoegd.