Felsökning av Azure Cosmos DB

Vanliga frågor

Vad är Azure Cosmos DB-stöd i DAB?

Data API Builder stöder Azure Cosmos DB som en NoSQL-serverdel. DAB ansluter till Cosmos DB med hjälp av Azure Cosmos DB .NET SDK och exponerar entiteter som GraphQL-typer. REST-stöd för Cosmos DB är inte tillgängligt. alla frågor hanteras via GraphQL-slutpunkten.

Vilket API använder DAB med Cosmos DB?

DAB använder Azure Cosmos DB för NoSQL API (tidigare SQL API). Andra Cosmos DB-API:er som MongoDB, Gremlin och Table stöds inte. Kontrollera att ditt Cosmos DB-konto har skapats med Azure Cosmos DB för NoSQL API.

Stöds Cosmos DB-emulatorn?

Ja. Azure Cosmos DB-emulatorn stöds för lokal utveckling. Ange anslutningssträngen till emulatorns standardslutpunkt: AccountEndpoint=https://localhost:8081/;AccountKey=<emulator-key>;. Du måste lita på emulatorns självsignerade certifikat på utvecklingsdatorn innan DAB kan ansluta.

Vanliga problem

Emulatorcertifikatet är inte betrodda

Symptom: DAB kan inte ansluta till emulatorn med ett SSL- eller certifikatverifieringsfel.

Orsaka: Azure Cosmos DB-emulatorn använder ett självsignerat certifikat som inte är betrott som standard i operativsystemet.

Upplösning: Exportera och installera emulatorcertifikatet från https://localhost:8081/_explorer/emulator.pem den lokala datorns betrodda rotcertifikatarkiv. Öppna certifikatfilen i Windows och installera den på betrodda rotcertifikatutfärdare för lokala datorer>. Starta om DAB när du har installerat certifikatet.

Det går inte att ansluta till emulatorn

Symptom: DAB kan inte starta med The remote name could not be resolved: 'localhost' eller ett anslutningsfel som pekar på port 8081.

Orsaka: Emulatorn körs inte eller så är slutpunkten eller kontonyckeln i anslutningssträngen felaktig.

Upplösning: Starta Azure Cosmos DB-emulatorn från Start-menyn eller genom att köra den körbara emulatorn. Bekräfta att anslutningssträngen använder AccountEndpoint=https://localhost:8081/ och rätt emulatornyckel, som visas på emulatorns datautforskarens sida på https://localhost:8081/_explorer/index.html.

GraphQL-schemafilen hittades inte

Symptom: DAB kan inte börja med ett fel som Schema file not found eller graphql-schema path is invalid.

Orsaka: Sökvägen graphql.schema i dab-config.json pekar på en fil som inte finns eller använder en felaktig relativ sökväg.

Upplösning: Kontrollera att schemafilen finns på sökvägen som anges i dab-config.json. Sökvägen är relativ till konfigurationsfilens plats. Kör dab init med --cosmosdb_nosql-schema för att återskapa konfigurationen med rätt schemasökväg, och bekräfta sedan att .gql- eller .graphql-filen finns på den platsen.

Frågan returnerar tomma resultat

Symptom: GraphQL-frågor returnerar en tom lista trots att containern har data.

Orsaka: Sökvägen för containernamn eller partitionsnyckel i entitetskonfigurationen matchar inte den faktiska Cosmos DB-containern, eller så är databasnamnet felaktigt.

Upplösning: Kontrollera entitetens värde i source och bekräfta att det matchar det exakta containernamnet (skiftlägeskänsligtdab-config.json). Kontrollera att fältet database under data-source matchar Cosmos DB-databasnamnet. Öppna Datautforskaren för kontot i Azure-portalen och bekräfta databas- och containernamnen.

TCP-anslutningar i direktläge misslyckas med Linux-emulatorn

Symptom: DAB hänger sig eller överskrider tidsgränsen när den ansluter till Cosmos DB Linux-emulatorn i Docker, även med AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1 inställt. Begäranden stannar vid återförsök av anslutningen.

Orsaka: DAB hårdkodar för närvarande ConnectionMode.Direct, vilket gör att Cosmos SDK identifierar fysiska partitionsslutpunkter (till exempel 172.17.0.2:1025010255) och öppnar TCP-anslutningar till dem. Från värddatorn går det inte att nå dessa containeradresser. Gatewayläget dirigerar all trafik över en enda HTTPS-slutpunkt (port 8081 på emulatorn) och undviker problemet helt. Det här är en känd begränsning som spåras i GitHub-problem #3401.

Upplösning: Ange AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1 när emulatorcontainern startas. Detta tvingar emulatorn att annonsera 127.0.0.1 som sin egen adress, vilket gör de upptäckta slutpunkterna nåbara från värden. Tills gatewayläget kan konfigureras i DAB är IP-överskrivning det rekommenderade tillvägagångssättet för lokal utveckling.

Autentisering med Behalf-Of (OBO) stöds inte

Symptom: Konfigurationen av OBO-autentisering (On-Behalf-Of) för en Azure Cosmos DB-backad DAB-instans misslyckas eller så vidarebefordras inte token som förväntat.

Orsaka: OBO-autentisering stöds för närvarande endast för SQL Server och Azure SQL. Stöd för Azure Cosmos DB har ännu inte implementerats. Det här är en känd begränsning som spåras i GitHub-problem #3159.

Upplösning: Använd en autentiseringsmetod som stöds, till exempel Cosmos DB-kontonyckeln eller den hanterade identiteten. Följ GitHub-problemet för uppdateringar om när OBO-stöd utökas till icke-SQL Server-databaser.

GraphQL i filtret misslyckas på Cosmos DB

Symptom: En GraphQL-fråga som använder in-operatorn mot en Cosmos DB-stödd entitet misslyckas vid körning med "Det går inte att skapa okänd förutsägelseoperation IN", även om operatorn in visas i schemat via introspektion.

Orsaka: In-operatorn exponeras i det genererade GraphQL-schemat för IdFilterInput och StringFilterInput, men den underliggande Cosmos DB-filteröversättningslogik implementerar den inte. Det här matchningsfelet mellan schemat och frågeexekutorn är ett känt fel som spåras i GitHub-problemet #3061.

Upplösning: Undvik att använda in-operatorn i GraphQL-frågor mot Cosmos DB-entiteter. Använd någon av dessa lösningar i stället:

• Ersätt med flera eller + q-uttryck för en liten, fast lista med värden.
• Använd flera punktläsningsaliaser (item_by_pk) när du frågar efter en känd lista med ID:er.
• Filtrera klientsidan när du har hämtat en bredare resultatuppsättning.

Sammansättningar stöds inte för Cosmos DB

Symptom: GraphQL-aggregerade frågor (till exempel antal, summa eller vg) mot en Cosmos DB-backad entitet misslyckas eller är inte tillgängliga i schemat.

Orsaka: Data API Builder stöder för närvarande inte aggregeringsåtgärder för Azure Cosmos DB. Sammansättningar är endast tillgängliga för relationsdatabaser. Det här är en känd begränsning som spåras i GitHub-problem #2849.

Upplösning: Det finns ingen lösning inom DAB just nu. Utför aggregeringar på klientsidan när du har hämtat resultatuppsättningen eller använd Cosmos DB:s inbyggda fråge-API direkt för aggregeringsåtgärder. Följ GitHub-problemet för uppdateringar.

Pluralfrågor (lista) kan inte inaktiveras för att endast framtvinga punktläsningar

Symptom: Klienter kan utfärda breda objekt listfrågor mot en Cosmos DB-entitet som förbrukar höga RU:er, när avsikten är att endast tillåta punktläsningar via item_by_pk.

Orsak: Data API Builder tillhandahåller för närvarande inte något konfigurationsalternativ för att undertrycka pluralfrågor och begränsa en entitet till endast pekläsningar. Det här är en känd begränsning som spåras i GitHub-problemet #2433.

Upplösning: Som en partiell lösning begränsar du liståtgärden i entitetens behörigheter för att begränsa vilka roller som kan utfärda listfrågor. Fullständig undertryckning av pluralfrågetypen från schemat stöds ännu inte.

Hierarkiska partitionsnycklar (MultiHash) stöds inte

Symptom: Mutationer mot en Cosmos DB-container som använder hierarkiska partitionsnycklar (mer än en partitionsnyckelsökväg) misslyckas med felet "kind"-värdet "MultiHash" som anges i partitionsnyckeldefinitionen är ogiltigt. Välj partitionstypen Hash.

Orsak: Data API Builder stöder endast enkel nyckel (Hash) som partitionsnyckel. Containrar som konfigurerats med hierarkiska partitionsnycklar (MultiHash) stöds inte. Det här är en känd begränsning som spåras i GitHub-problemet #1733.

Upplösning: Det finns ingen lösning inom DAB just nu. Om möjligt gör du om containern så att den använder en enda partitionsnyckel. Om hierarkiska partitionsnycklar krävs av datamodellen följer du GitHub-problemet för uppdateringar om när stöd för flera hash läggs till.

MultiHash-partitionsnycklar stöds inte

Symptom: Mutationer mot en Cosmos DB-container som använder en hierarkisk (multi-hash) partitionsnyckel misslyckas med felet: 'kind'-värdet 'MultiHash' som anges i partitionsnyckeldefinitionen är ogiltigt. Välj partitionstypen Hash.

Orsaka: Data API Builder stöder endast hash-partitionsnycklar med ett värde för Azure Cosmos DB. Containrar som konfigurerats med hierarkiska partitionsnycklar (MultiHash) till exempel /TenantId, /EntityType, /EntityId stöds inte. Det här är en känd begränsning som spåras i GitHub-problemet #1733.

Upplösning: Det finns ingen lösning inom DAB just nu. Använd en container med en enda Hash-partitionsnyckel i stället. Om hierarkisk partitionering krävs kan du överväga att omstrukturera containern eller följa GitHub-problemet för uppdateringar när stöd för MultiHash-partitionsnyckel läggs till.

Flera mutationer är inte atomiska i Cosmos DB

Symptom: När flera GraphQL-mutationer skickas i en enda begäran mot Cosmos DB-entiteter återställs inte ett fel i en mutation de andra. Partiella skrivningar kan inträffa.

Orsaka: Data API Builder omsluter inte flera Cosmos DB-mutationer i en transaktionsbatch. Till skillnad från relationsdatabaser, där flera mutationer i en begäran körs atomiskt, utfärdas Cosmos DB-mutationer oberoende av varandra. Det här är en känd begränsning som spåras i GitHub-problemet #1621.

Upplösning: Utforma ditt program för att behandla varje Cosmos DB-mutation som oberoende. Om atomiskhet krävs använder du Cosmos DB SDK direkt med transaktionsbatchstöd, begränsat till objekt inom samma logiska partition. Följ GitHub-ärendet för uppdateringar om när stöd för transaktionsändringar läggs till för Cosmos DB.

GraphQL-typnamnet i schemafilen matchar inte entitetskonfigurationen

Symptom: DAB startar utan fel men frågor returnerar oväntade resultat eller fel typ, eftersom GraphQL-typnamnet som definierats i schema.gql inte matchar namnet på den singulartyp som konfigurerats för entiteten i dab-config.json.

Orsaka: Data-API-byggare verifierar för närvarande inte att GraphQL-typnamnet i schemafilen matchar namnet på den singulartyp som deklarerats för entiteten. En diskrepans ger tyst upphov till ett inkonsekvent schema. Det här är en känd begränsning som spåras i GitHub-problem #1556.

Upplösning: Kontrollera manuellt att typnamnet i schema.gql (som anges via @model direktivet) matchar singularvärdet i entitetens graphql.type-konfiguration i dab-config.json. Om dab-config.json till exempel deklarerar "singular": "Location" ska schemafilen innehålla ype Location @model(name:"Location").

GraphQL-typnamnet i schemafilen matchar inte namnet på entitetens singulartyp

Symptom: DAB startar utan fel men frågor returnerar oväntade resultat eller fel typ, eftersom GraphQL-typnamnet som definierats i schema.gql inte matchar namnet på den singulartyp som konfigurerats för entiteten i dab-config.json.

Orsaka: Data-API-byggare verifierar för närvarande inte att @model direktivnamnet i GraphQL-schemafilen matchar den singulartypsnamn som angetts för entiteten. När de skiljer sig orsakar felet tyst ett felaktigt schemabeteende. Det här är en känd begränsning som spåras i GitHub-problem #1556.

Upplösning: Kontrollera manuellt att typnamnet i schema.gql exakt matchar singularvärdet i entitetens graphql.type-konfiguration i dab-config.json. Om entiteten till exempel definierar "singular": "Location" ska schemafilen deklarera ype Location @model(name:"Location"). Kör dab-verifiering när du har gjort ändringar för att fånga upp andra konfigurationsfel.

Enum-typer i GraphQL-schemafilen orsakar ett schema byggefel

Symptom: DAB misslyckas med att starta med en HotChocolate.SchemaException: Det går inte att matcha typreferensen ... OrderByInput-fel när schemat Cosmos DB schema.gql definierar GraphQL-typen num, vilken används på ett objektfält.

Orsaka: Data API Builder stöder för närvarande inte GraphQL-uppräkningstyper i Cosmos DB-schemafilen. När en uppräkningstyp används som fälttyp kan schemabyggaren inte generera motsvarande typen OrderByInput och utlöser ett ohanterat undantag. Det här är en känd begränsning som spåras i GitHub-problem #748.

Upplösning: Ersätt uppräkningsfält med deras skalära motsvarigheter (till exempel använd Sträng i stället för en anpassad uppräkningstyp) i schema.gql. Använd uppräkningsverifiering i programlagret i stället för i DAB-schemadefinitionen.

Enum-typer i GraphQL-schemat gör att DAB misslyckas vid uppstart

Symptom: DAB kan inte starta med ett fel av typen HotChocolate.SchemaException, såsom "Det går inte att matcha typreferensen 'None: FooOrderByInput'" när Cosmos DB GraphQL-schemafilen definierar en uppräkningstyp som används i en modell.

Orsaka: Data API Builder schema builder hanterar inte GraphQL-uppräkningstyper som definierats i schema.gql korrekt. När en uppräkning refereras till som en fälttyp på en modell misslyckas den interna orderByInput-typgenereringen med att lösa det, vilket leder till att schemainitieringen kraschar. Det här är en känd begränsning som spåras i GitHub-problem #748.

Upplösning: Undvik att definiera GraphQL-enumtyper i schema.gql för Cosmos DB-entiteter. Som en lösning kan du ersätta uppräkningsfält med strängar och framtvinga giltiga värden i applikationslagret. Följ GitHub-ärendet för uppdateringar om när enum-stöd läggs till.

Fältmappningar (alias) stöds inte för Cosmos DB-entiteter

Symptom: Ett mappningsavsnitt som definierats för en Cosmos DB-entitet i dab-config.json har ingen effekt att de ursprungliga fältnamnen fortfarande exponeras i GraphQL-schemat i stället för de konfigurerade aliasen.

Orsaka: Funktionen mappningar, som gör det möjligt att exponera databaskolumnnamn under olika fältnamn i API:et, implementeras endast för relationsdatabaser. Cosmos DB-entiteter stöder för närvarande inte fältmappningar. Detta är en känd begränsning som spåras i GitHub-problem #1512.

Upplösning: Använd fältnamnen exakt som de visas i Cosmos DB-dokumenten. Om du behöver alias kan du använda det i klientprogramlagret. Följ GitHub-problemet för uppdateringar om när mappningsstöd läggs till för Cosmos DB.

GraphQL-mutationsvariabler är inte lösta variabelnamn som lagras i stället för värden

Symptom: En GraphQL-mutation som använder variabler (till exempel createExample(item: { id: , name: })) lagrar variabelnamnen "" och "" i databasen i stället för de faktiska värden som skickas i nyttolasten ariables.

Orsaka: Data API Builder löser för närvarande inte GraphQL-variabelreferenser i mutationsindata för Cosmos DB. Variabelersättning hoppas över och det bokstavliga variabelnamnet skrivs som fältvärdet. Det här är en känd bugg som spåras i GitHub-problem #1482.

Upplösning: Infoga variabelvärdena direkt i mutationskroppen i stället för att använda GraphQL-variabler. Ersätt till exempel ID: med ID: "1234". Detta är inte idealiskt för produktionsanvändning, så följ GitHub-problemet för uppdateringar om när variabelhantering har åtgärdats för Cosmos DB-mutationer.

Union-typer i GraphQL-schemafilen orsakar ett 500-fel

Symptom: DAB returnerar en 500-statuskod för alla GraphQL-begäranden när schema.gql definierar en GraphQL-uniontyp. Startloggarna visar HotChocolate.SchemaException: Det går inte att matcha typreferensen ... OrderByInput.

Orsaka: Data-API Builder stöder inte GraphQL-unionstyper i Cosmos DB-schemafilen. Precis som enumtyper får unionstyper schemageneratorn att misslyckas när sorterings-/filtreringsindatatyper genereras. Det här är en känd bugg som spåras i GitHub-problem #1384.

Upplösning: Ta bort definitioner av unionstyp från schema.gql. Modellera polymorfa data med en enda objekttyp med valfria fält eller dela upp data mellan separata entiteter. Följ GitHub-frågan för uppdateringar om när stöd för unionstyper läggs till.

Det går inte att skapa mutation vid körning när ID definieras som null i schemat

Symptom: En create-mutation returnerar ett körningsfel trots att schemat verkar giltigt. Felet uppstår eftersom ID-fältet inte angavs eller var null.

Orsaka: Cosmos DB kräver ID-fältet för varje dokument och använder det som en del av partitionsnyckeln. Om schema.gql deklarerar ID som nullbart (till exempel ID: ID i stället för ID: ID!), accepterar DAB schemat men misslyckas vid körning när en create-mutation utelämnar fältet. Schemat bör framtvinga icke-null vid schemavalidering, men gör det för närvarande inte. Det här gapet spåras i GitHub-problem nr 1238.

Upplösning: Deklarera alltid id-fältet som icke-null i Cosmos DB GraphQL-schemat:

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

Säkerställa id: ID! gör att klienter får ett tydligt schemanivåfel om ID utelämnas i stället för ett ogenomskinligt körningsfel.

Cirkulära GraphQL-relationer orsakar ett stacköverflödesundantag vid start

Symptom: DAB kraschar vid start med ett stacköverflödesundantag när schema.gql definierar typer som refererar till varandra i en cykel (till exempel Spelare refererar till Spel, och Spel refererar till Spelare).

Orsak: Schemabyggaren genomsöker alla typreferenser rekursivt för att skapa inmatningstyper för mutationer. Cirkulära relationer orsakar oändlig rekursion, vilket uttömmer anropsstacken. Det här är en känd bugg som spåras i GitHub-problem #746.

Upplösning: Undvik cirkeltypreferenser i schema.gql. Bryt cykeln genom att ta bort backreferensen från någon av typerna, eller modellera relationen som en lista över ID:er (skalära fält) i stället för kapslade objekttyper. Följ GitHub-problemet för uppdateringar om när cirkulära relationer stöds.

Partitionsnyckeln är alltid "id" och anpassade partitionsnyckelsökvägar stöds inte.

Symptom: DAB fungerar bara med Cosmos DB-containrar som använder /id som partitionsnyckel. Containrar som partitioneras av något annat fält (till exempel /userId eller /category) kan inte efterfrågas eller muteras korrekt.

Orsaka: Data-API Builder hårdkodar ID som partitionsnyckel för alla Cosmos DB-entiteter. Det går inte att ange en anpassad partitionsnyckelsökväg i antingen dab-config.json eller schema.gql. Detta är en känd begränsning som spåras i GitHub-problem #747.

Upplösning: Utforma nya containrar med /id som partitionsnyckel när du använder DAB. För befintliga containrar med en annan partitionsnyckel stöds inte DAB för närvarande. Följ GitHub-problemet för uppdateringar om när konfigurerbara partitionsnycklar läggs till.

Det går inte att köra frågor mot kapslade arrays i ett dokument (inre objektanslutningar stöds inte).

Symptom: Du kan inte filtrera eller bläddra igenom kapslade matrisegenskaper i ett Cosmos DB-dokument med hjälp av DAB. Frågor som skulle kräva en Cosmos DB JOIN mellan matriselement returnerar inga resultat eller ett fel.

Orsaka: Data-API-byggare stöder inte Cosmos DB-intradokumentkopplingar (kallas även objektkopplingar), som behövs för att köra frågor mot kapslade matriser i ett enda dokument. Det här är en känd begränsning som spåras i GitHub-problem nr 262.

Upplösning: Platta ut kapslade matriser till separata entiteter eller underordnade dokument om du behöver filtrera på deras innehåll. Du kan också utföra efterbearbetning av det fullständiga dokumentet i programlagret. Följ GitHub-ärendet för uppdateringar om när stöd för sammanfogning inom dokument läggs till.