Risoluzione dei problemi di Azure Cosmos DB

Soluzioni per problemi comuni di configurazione dell'emulatore, della connettività e dello schema di Azure Cosmos DB in Generatore API dati.

Domande comuni

Che cos'è il supporto di Azure Cosmos DB in DAB?

Il costruttore di API dati supporta Azure Cosmos DB come back-end NoSQL. DAB si connette a Cosmos DB usando .NET SDK di Azure Cosmos DB ed espone le entità come tipi GraphQL. Il supporto REST per Cosmos DB non è disponibile; tutte le query vengono gestite tramite l'endpoint GraphQL.

Quale API usa DAB con Cosmos DB?

DAB usa l'API Azure Cosmos DB per NoSQL (in precedenza API SQL). Altre API di Cosmos DB, ad esempio MongoDB, Gremlin e Table, non sono supportate. Assicurarsi che l'account Cosmos DB venga creato con l'API Azure Cosmos DB per NoSQL .

L'emulatore cosmos DB è supportato?

Sì. L'emulatore di Azure Cosmos DB è supportato per lo sviluppo locale. Impostare la stringa di connessione sull'endpoint predefinito dell'emulatore: AccountEndpoint=https://localhost:8081/;AccountKey=<emulator-key>;. È necessario considerare attendibile il certificato autofirmato dell'emulatore nel computer di sviluppo prima che DAB possa connettersi.

Problemi comuni

Certificato dell'emulatore non attendibile

Sintomo: DAB non riesce a connettersi all'emulatore con un errore di convalida SSL o certificato.

Causa: L'emulatore di Azure Cosmos DB usa un certificato autofirmato non considerato attendibile per impostazione predefinita nel sistema operativo.

Risoluzione: Esportare e installare il certificato dell'emulatore da https://localhost:8081/_explorer/emulator.pem nell'archivio certificati radice attendibile del computer locale. In Windows aprire il file del certificato e installarlo in Autorità di certificazione radice attendibili del computer > locale. Riavviare DAB dopo l'installazione del certificato.

Impossibile connettersi all'emulatore

Sintomo: L'avvio di DAB non riesce con The remote name could not be resolved: 'localhost' o un errore di connessione rifiutata che punta alla porta 8081.

Causa: L'emulatore non è in esecuzione o la chiave dell'endpoint o dell'account nella stringa di connessione non è corretta.

Risoluzione: Avviare l'emulatore di Azure Cosmos DB dal menu Start o eseguendo l'eseguibile dell'emulatore. Verificare che la stringa di connessione usi AccountEndpoint=https://localhost:8081/ e la chiave dell'emulatore corretta, visualizzata nella pagina esplora dati dell'emulatore all'indirizzo https://localhost:8081/_explorer/index.html.

File di schema GraphQL non trovato

Sintomo: DAB non viene avviato con un errore, Schema file not found ad esempio o graphql-schema path is invalid.

Causa: Il graphql.schema percorso in dab-config.json punta a un file che non esiste o usa un percorso relativo non corretto.

Risoluzione: Verificare che il file di schema esista nel percorso specificato in dab-config.json. Il percorso è relativo al percorso del file di configurazione. Eseguire dab init con --cosmosdb_nosql-schema per rigenerare la configurazione con il percorso dello schema corretto, quindi verificare che il .gql file o .graphql sia presente in tale percorso.

La query restituisce risultati vuoti

Sintomo: Le query GraphQL restituiscono un elenco vuoto anche se il contenitore contiene dati.

Causa: Il nome del contenitore o il percorso della chiave di partizione nella configurazione dell'entità non corrisponde al contenitore Cosmos DB effettivo oppure il nome del database non è corretto.

Risoluzione: Controllare il valore dell'entità in source e verificare che corrisponda al nome esatto del dab-config.json contenitore (con distinzione tra maiuscole e minuscole). Verificare che il database campo in data-source corrisponda al nome del database Cosmos DB. Nel portale di Azure aprire Esplora dati per l'account e confermare i nomi di database e contenitori.

Le connessioni TCP in modalità diretta hanno esito negativo con l'emulatore Linux

Sintomo: DAB si blocca o si verifica il timeout durante la connessione all'emulatore Linux di Cosmos DB in Docker, anche con AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1 impostato. Le richieste si bloccano durante i tentativi di connessione.

Causa: DAB attualmente codifica in modo fisso il ConnectionMode.Direct, il che porta il Cosmos SDK a rilevare gli endpoint di partizione fisica (ad esempio 172.17.0.2:1025010255) e ad aprire connessioni TCP verso di essi. Dal computer host, gli indirizzi dei contenitori non sono raggiungibili. La modalità gateway instrada tutto il traffico su un singolo endpoint HTTPS (porta 8081 nell'emulatore) ed evitare completamente il problema. Si tratta di una limitazione nota rilevata nel problema gitHub #3401.

Risoluzione: Impostare AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1 all'avvio del contenitore dell'emulatore. Ciò impone all'emulatore di annunciare 127.0.0.1 come indirizzo, rendendo gli endpoint individuati raggiungibili dall'host. Fino a quando la modalità gateway non è configurabile in DAB, l'override IP è la soluzione consigliata per lo sviluppo locale.

L'autenticazione on-Behalf-Of (OBO) non è supportata

Sintomo: La configurazione dell'autenticazione DAB basata su On-Behalf-Of (OBO) per un'istanza di DAB basata su Azure Cosmos DB non riesce o il token non viene inoltrato come previsto.

Causa: L'autenticazione OBO è attualmente supportata solo per SQL Server e Azure SQL. Il supporto per Azure Cosmos DB non è ancora stato implementato. Si tratta di una limitazione nota rilevata nel problema di GitHub #3159.

Risoluzione: Usare un metodo di autenticazione supportato, ad esempio la chiave dell'account Cosmos DB o l'identità gestita. Seguire la segnalazione su GitHub per aggiornamenti su quando il supporto OBO verrà esteso ai database diversi da SQL Server.

GraphQL nel filtro riscontra un problema su Cosmos DB

Sintomo: Una query GraphQL che usa l'operatore in su un'entità supportata da Cosmos DB ha esito negativo in fase di esecuzione con Non è possibile compilare operazioni di predicato sconosciute IN, anche se in viene visualizzato nello schema tramite introspezione.

Causa: L'operatore in viene esposto nello schema GraphQL generato per IdFilterInput e StringFilterInput, ma la logica di conversione del filtro Cosmos DB sottostante non lo implementa. Questa mancata corrispondenza tra lo schema e l'executor di query è un bug noto rilevato nel problema di GitHub #3061.

Risoluzione: Evitare di usare l'operatore in nelle query GraphQL contro le entità di Cosmos DB. Usare invece una di queste soluzioni alternative:

• Sostituire "in" con espressioni multiple o + q per un piccolo elenco fisso di valori.
• Usare più alias di lettura da punto (item_by_pk) durante l'esecuzione di query tramite un elenco noto di ID.
• Filtrare il lato client dopo il recupero di un set di risultati più ampio.

Le aggregazioni non sono supportate per Cosmos DB

Sintomo: Le query di aggregazione GraphQL (ad esempio count, sum o vg) su un'entità supportata da Cosmos DB hanno esito negativo o non sono disponibili nello schema.

Causa: Il generatore di API dati attualmente non supporta le operazioni di aggregazione per Azure Cosmos DB. Le aggregazioni sono disponibili solo per i database relazionali. Si tratta di una limitazione nota rilevata nel problema 2849 di GitHub.

Risoluzione: Al momento non esiste alcuna soluzione alternativa all'interno di DAB. Eseguire aggregazioni sul lato client dopo aver recuperato il set di risultati oppure usare direttamente l'API di query predefinita di Cosmos DB per le operazioni di aggregazione. Segui la segnalazione su GitHub per gli aggiornamenti.

Le query plurali (elenco) non possono essere disabilitate per consentire solo letture puntuali.

Sintomo: I client sono in grado di eseguire query di elenco di elementi generali su un'entità Cosmos DB, usando UR elevate, quando la finalità è consentire solo letture di punti tramite item_by_pk.

Causa: Il generatore di API dati non offre attualmente un'opzione di configurazione per eliminare le query plurali e limitare le operazioni di sola lettura di un'entità. Si tratta di una limitazione nota rilevata nel problema di GitHub #2433.

Risoluzione: Come soluzione alternativa parziale, limitare l'azione elenco nelle autorizzazioni dell'entità per limitare i ruoli che possono eseguire query di elenco. L'eliminazione completa del tipo di query plurale dallo schema non è ancora supportata.

Le chiavi di partizione gerarchica (MultiHash) non sono supportate

Sintomo: Le mutazioni in un contenitore Cosmos DB che utilizza chiavi di partizione gerarchiche (più di un percorso della chiave di partizione) falliscono con l'errore Il valore 'kind' 'MultiHash' specificato nella definizione della chiave di partizione non è valido. Scegliere il tipo di partizione 'Hash'.

Causa: Generatore API dati supporta solo definizioni di chiave di partizione a chiave singola (hash). I contenitori configurati con chiavi di partizione gerarchica (MultiHash) non sono supportati. Si tratta di una limitazione nota rilevata nel problema 1733 di GitHub.

Risoluzione: Al momento non esiste alcuna soluzione alternativa all'interno di DAB. Se possibile, riprogettare il contenitore per usare una singola chiave di partizione. Se le chiavi di partizione gerarchica sono richieste dal modello di dati, seguire il problema di GitHub per gli aggiornamenti su quando viene aggiunto il supporto multi-hash.

Le chiavi di partizione multiHash non sono supportate

Sintomo: Le mutazioni in un contenitore Cosmos DB che usa una chiave di partizione gerarchica (multi-hash) hanno esito negativo e il valore 'kind' 'MultiHash' specificato nella definizione della chiave di partizione non è valido. Scegliere il tipo di partizione 'Hash'.

Causa: Il generatore di API dati supporta solo chiavi di partizione hash a valore singolo per Azure Cosmos DB. I contenitori configurati con chiavi di partizione gerarchica (MultiHash), ad esempio , /TenantId, /EntityType, /EntityId non sono supportati. Si tratta di una limitazione nota rilevata nel problema 1733 di GitHub.

Risoluzione: Al momento non esiste alcuna soluzione alternativa all'interno di DAB. Usare invece un contenitore con una singola chiave di partizione Hash. Se è necessario il partizionamento gerarchico, è consigliabile ristrutturare il contenitore o seguire il problema di GitHub per gli aggiornamenti quando viene aggiunto il supporto della chiave di partizione MultiHash.

Molteplici mutazioni non sono atomiche su Cosmos DB

Sintomo: Quando più mutazioni GraphQL vengono inviate in una singola richiesta alle entità di Cosmos DB, un errore in una mutazione non esegue il rollback degli altri. Le scritture parziali possono verificarsi.

Causa: Il generatore di API dati non esegue il wrapping di più mutazioni di Cosmos DB in un batch transazionale. A differenza dei database relazionali, in cui vengono eseguite più mutazioni in una richiesta in modo atomico, le mutazioni di Cosmos DB vengono eseguite in modo indipendente. Si tratta di una limitazione nota rilevata nel problema di GitHub #1621.

Risoluzione: Progettare l'applicazione per considerare ogni mutazione di Cosmos DB come indipendente. Se è necessaria l'atomicità, utilizzare direttamente il Cosmos DB SDK con il supporto per batch transazionali, limitato agli elementi all'interno della stessa partizione logica. Segui l'issue di GitHub per ricevere aggiornamenti sull'aggiunta del supporto alla mutazione transazionale per Cosmos DB.

Il nome del tipo GraphQL nel file di schema non corrisponde alla configurazione dell'entità

Sintomo: DAB viene avviato senza errori, ma le query restituiscono risultati imprevisti o il tipo errato, perché il nome del tipo GraphQL definito in schema.gql non corrisponde al nome di tipo singolare configurato per l'entità in dab-config.json.

Causa: Il generatore di API dati non convalida attualmente che il nome del tipo GraphQL nel file di schema corrisponda al nome del tipo singolare dichiarato per l'entità. Una mancata corrispondenza genera automaticamente uno schema incoerente. Si tratta di una limitazione nota rilevata nel problema 1556 di GitHub.

Risoluzione: Verificare manualmente che il nome del tipo in schema.gql (impostato tramite la @model direttiva) corrisponda al valore singolare nella configurazione graphql.type dell'entità in dab-config.json. Ad esempio, se dab-config.json dichiara "singular": "Location", il file di schema deve contenere ype Location @model(name:"Location").

Il nome del tipo GraphQL nel file di schema non corrisponde al nome del tipo singolare dell'entità

Sintomo: DAB viene avviato senza errori, ma le query restituiscono risultati imprevisti o il tipo errato, perché il nome del tipo GraphQL definito in schema.gql non corrisponde al nome di tipo singolare configurato per l'entità in dab-config.json.

Causa: Il generatore di API dati non convalida attualmente che il nome della @model direttiva nel file di schema GraphQL corrisponda al nome del tipo singolare impostato per l'entità. Quando differiscono, la mancata corrispondenza genera automaticamente un comportamento di schema non corretto. Si tratta di una limitazione nota rilevata nel problema 1556 di GitHub.

Risoluzione: Assicurarsi manualmente che il nome del tipo in schema.gql corrisponda esattamente al valore singolare nella configurazione graphql.type dell'entità in dab-config.json. Ad esempio, se l'entità definisce "singolare": "Location", il file di schema deve dichiarare ype Location @model(name:"Location". Eseguire dab validate dopo aver apportato modifiche per rilevare altri errori di configurazione.

I tipi di enumerazione nel file di schema GraphQL causano un errore di compilazione dello schema

Sintomo: DAB non riesce a iniziare con hotChocolate.SchemaException: impossibile risolvere il riferimento al tipo ... Errore OrderByInput quando il file schema.gql di Cosmos DB definisce un tipo num GraphQL usato in un campo del tipo di oggetto.

Causa: Il generatore di API dati attualmente non supporta i tipi di enumerazione GraphQL nel file di schema di Cosmos DB. Quando un'enumerazione viene utilizzata come tipo di campo, il generatore di schemi non può generare il tipo OrderByInput corrispondente e genera un'eccezione non gestita. Si tratta di una limitazione nota rilevata nel problema 748 di GitHub.

Risoluzione: Sostituire i campi enum con gli equivalenti scalari, ad esempio usare String anziché un tipo di enumerazione personalizzato in schema.gql. Applicare la validazione dell'enumerazione nello strato dell'applicazione anziché nella definizione dello schema DAB.

I tipi di enumerazione nello schema GraphQL causano il fallimento di DAB all'avvio

Sintomo: L'avvio di DAB fallisce con un errore di tipo HotChocolate.SchemaException, ad esempio "Impossibile risolvere il riferimento di tipo 'Nessuno: FooOrderByInput'", quando il file di schema GraphQL di Cosmos DB definisce un tipo enumerativo utilizzato su un modello.

Causa: Il generatore di schemi del generatore di API dati non gestisce correttamente i tipi di enumerazione GraphQL definiti in schema.gql. Quando viene fatto riferimento a un'enumerazione come tipo di campo in un modello, la generazione interna del tipo OrderByInput non riesce a risolverla, arrestando in modo anomalo l'inizializzazione dello schema. Si tratta di una limitazione nota rilevata nel problema 748 di GitHub.

Risoluzione: Evitare di definire tipi di enumerazione GraphQL in schema.gql per le entità Cosmos DB. Come soluzione alternativa, sostituire i campi di enumerazione con stringa e imporre valori validi nel livello dell'applicazione. Vedere l'issue su GitHub per gli aggiornamenti su quando viene aggiunto il supporto delle enumerazioni.

Le mappature dei campi (alias) non sono supportate per le entità di Cosmos DB

Sintomo: Una sezione mapping definita per un'entità Cosmos DB in dab-config.json non ha alcun effetto sui nomi dei campi originali ancora esposti nello schema GraphQL anziché negli alias configurati.

Causa: La funzionalità di mapping, che consente di esporre i nomi delle colonne di database con nomi di campo diversi nell'API, viene implementata solo per i database relazionali. Le entità di Cosmos DB attualmente non supportano i mapping dei campi. Si tratta di una limitazione nota rilevata nel problema di GitHub #1512.

Risoluzione: Usare i nomi dei campi esattamente come vengono visualizzati nei documenti di Cosmos DB. Se è necessario eseguire l'aliasing, applicarlo nel livello dell'applicazione client. Segui l'issue di GitHub per gli aggiornamenti per sapere quando sarà aggiunto il supporto per il mapping per Cosmos DB.

Le variabili di mutazione GraphQL non vengono risolte nei nomi delle variabili archiviate anziché nei valori

Sintomo: Una mutazione GraphQL che usa variabili (ad esempio createExample(item: { id: , name: })) archivia i nomi delle variabili "" e "" nel database anziché i valori effettivi passati nel payload ariables.

Causa: Il generatore di API dati non risolve attualmente i riferimenti alle variabili GraphQL negli input di mutazione per Cosmos DB. La sostituzione delle variabili viene ignorata e il nome della variabile letterale viene scritto come valore del campo. Si tratta di un bug noto rilevato nel problema di GitHub #1482.

Risoluzione: Inline i valori delle variabili direttamente nel corpo della mutazione anziché usare le variabili GraphQL. Ad esempio, sostituire id: con ID: "1234". Questo non è ideale per l'uso in produzione, quindi segui il problema su GitHub per gli aggiornamenti sulla correzione della gestione delle variabili per le mutazioni di Cosmos DB.

I tipi di unione nel file di schema GraphQL causano un errore 500

Sintomo: DAB restituisce un codice di stato 500 in tutte le richieste GraphQL quando schema.gql definisce un tipo di unione GraphQL. I log di avvio mostrano HotChocolate.SchemaException: Impossibile risolvere il riferimento al tipo ... OrderByInput.

Causa: Il generatore di API dati non supporta i tipi di unione GraphQL nel file di schema di Cosmos DB. Analogamente ai tipi di enumerazione, i tipi di unione causano un errore del generatore di schemi durante la generazione di tipi di input di ordinamento/filtro. Si tratta di un bug noto rilevato in GitHub #1384.

Risoluzione: Rimuovere le definizioni dei tipi di unione da schema.gql. Modellare dati polimorfici usando un singolo tipo di oggetto con campi facoltativi o suddividere i dati tra entità separate. Seguire l'issue di GitHub per gli aggiornamenti su quando viene aggiunto il supporto per i tipi unione.

La mutazione di creazione fallisce durante l'esecuzione quando l'ID è definito come annullabile nello schema.

Sintomo: Una mutazione create restituisce un errore di runtime anche se lo schema è valido. L'errore si verifica perché il campo ID non è stato specificato o è null.

Causa: Cosmos DB richiede il campo ID per ogni documento e lo usa come parte della chiave di partizione. Se il file schema.gql dichiara id come nullable (ad esempio, id: ID anziché id: ID!), DAB accetta lo schema ma fallisce in fase di esecuzione quando una mutazione di creazione omette il campo. Lo schema dovrebbe imporre il non null al momento della convalida dello schema, ma attualmente non lo fa. Questo gap viene rilevato nel problema GitHub n. 1238.

Risoluzione: Dichiarare sempre il campo ID come non Null nello schema GraphQL di Cosmos DB:

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

Verifica id: ID! fa sì che i client ricevano un errore chiaro a livello di schema se id viene omesso, anziché un errore di runtime opaco.

Le relazioni GraphQL circolari causano un'eccezione di overflow dello stack all'avvio

Sintomo: DAB si arresta in modo anomalo all'avvio con un'eccezione di overflow dello stack quando schema.gql definisce tipi che si riferiscono tra loro in un ciclo (ad esempio, Gioco fa riferimento a Giocatore e Giocatore fa riferimento a Gioco).

Causa: Il generatore di schemi percorre in modo ricorsivo tutti i riferimenti ai tipi per generare i tipi di input per mutazioni. Le relazioni circolari causano una ricorsione infinita, esaurendo lo stack di chiamate. Si tratta di un bug noto rilevato in GitHub #746.

Risoluzione: Evitare riferimenti a tipi circolari in schema.gql. Interrompere il ciclo rimuovendo il back-reference da uno dei tipi o modellando la relazione come elenco di ID (campi scalari) anziché tipi di oggetto annidati. Seguire la questione su GitHub per gli aggiornamenti su quando saranno supportate relazioni circolari.

La chiave di partizione è sempre 'id' e i percorsi di chiave di partizione personalizzata non sono supportati

Sintomo: DAB funziona solo con i contenitori cosmos DB che usano /id come chiave di partizione. I contenitori partizionati da qualsiasi altro campo ,ad esempio /userId o /category, non possono essere sottoposti a query o modificati correttamente.

Causa: Data API builder codifica in modo fisso l'ID come chiave di partizione per tutte le entità Cosmos DB. Non è possibile specificare un percorso di chiave di partizione personalizzato in dab-config.json o schema.gql. Si tratta di una limitazione nota rilevata nel problema 747 di GitHub.

Risoluzione: Progettare nuovi contenitori con /id come chiave di partizione quando si usa DAB. Per i contenitori esistenti con una chiave di partizione diversa, DAB non è attualmente supportato. Seguire la segnalazione su GitHub per gli aggiornamenti riguardanti il momento in cui vengono aggiunte chiavi di partizione configurabili.

L'esecuzione di query su matrici annidate all'interno di un documento (join in elemento) non è supportata

Sintomo: Non è possibile filtrare o esplorare le proprietà degli array nidificati all'interno di un documento di Cosmos DB usando DAB. Le query che richiedono un join di Cosmos DB tra gli elementi della matrice non restituiscono risultati o errori.

Causa: Il generatore di API dati non supporta i join all'interno del documento di Cosmos DB (detti anche join in-item), necessari per eseguire query su matrici annidate all'interno di un singolo documento. Si tratta di una limitazione nota rilevata nel problema #262 di GitHub.

Risoluzione: Rendere piatte le matrici annidate in entità separate o documenti figlio se è necessario filtrare il loro contenuto. In alternativa, eseguire la post-elaborazione del documento completo nel livello dell'applicazione. Seguire la segnalazione su GitHub per aggiornamenti su quando verrà aggiunto il supporto all'unione intra-documento.