Řešení potíží se službou Azure Cosmos DB

Řešení běžných problémů s emulátorem služby Azure Cosmos DB, připojením a konfigurací schématu v Tvůrci rozhraní Data API

Časté dotazy

Co je podpora služby Azure Cosmos DB v DAB?

Tvůrce rozhraní Data API podporuje Azure Cosmos DB jako back-end NoSQL. DAB se připojuje ke službě Cosmos DB pomocí sady .NET SDK služby Azure Cosmos DB a zveřejňuje entity jako typy GraphQL. Podpora REST pro Cosmos DB není k dispozici; Všechny dotazy se obsluhují prostřednictvím koncového bodu GraphQL.

Jaké rozhraní API používá DAB se službou Cosmos DB?

DAB používá rozhraní API služby Azure Cosmos DB for NoSQL (dříve SQL API). Jiná rozhraní API služby Cosmos DB, jako jsou MongoDB, Gremlin a Table, nejsou podporována. Ujistěte se, že je váš účet Cosmos DB vytvořený pomocí rozhraní API služby Azure Cosmos DB for NoSQL .

Podporuje se emulátor služby Cosmos DB?

Ano. Emulátor služby Azure Cosmos DB je podporovaný pro místní vývoj. Nastavte připojovací řetězec na výchozí koncový bod emulátoru: AccountEndpoint=https://localhost:8081/;AccountKey=<emulator-key>;. Než se DAB může připojit, musíte důvěřovat certifikátu podepsanému svým držitelem na vývojovém počítači emulátoru.

Běžné problémy

Certifikát emulátoru není důvěryhodný

Příznak: DAB se nemůže připojit k emulátoru kvůli chybě ověření SSL nebo certifikátu.

Příčina: Emulátor služby Azure Cosmos DB používá samopodepsaný certifikát, který ve výchozím nastavení není v operačním systému důvěryhodný.

Rozlišení: Exportujte a nainstalujte certifikát emulátoru z https://localhost:8081/_explorer/emulator.pem důvěryhodného úložiště kořenových certifikátů místního počítače. Ve Windows otevřete soubor certifikátu a nainstalujte ho do důvěryhodných kořenových certifikačních autorit místního počítače>. Po instalaci certifikátu restartujte DAB.

Nejde se připojit k emulátoru

Příznak: DAB se nedaří spustit The remote name could not be resolved: 'localhost' nebo dojde k chybě odmítnutí připojení na portu 8081.

Příčina: Emulátor není spuštěn, nebo je nesprávný koncový bod či klíč účtu v připojovacím řetězci.

Rozlišení: Spusťte emulátor služby Azure Cosmos DB z nabídky Start nebo spuštěním spustitelného souboru emulátoru. Ověřte, že připojovací řetězec používá AccountEndpoint=https://localhost:8081/ , a správný klíč emulátoru, který se zobrazí na stránce Průzkumníka dat emulátoru na adrese https://localhost:8081/_explorer/index.html.

Soubor schématu GraphQL nebyl nalezen.

Příznak: DAB se nepovede spustit s chybou, například Schema file not found nebo graphql-schema path is invalid.

Příčina: Cesta graphql.schema v dab-config.json odkazuje na soubor, který neexistuje nebo používá nesprávnou relativní cestu.

Rozlišení: Ověřte, že soubor schématu existuje v cestě zadané v dab-config.json. Cesta je relativní vzhledem k umístění konfiguračního souboru. Spusťte dab init s --cosmosdb_nosql-schema pro znovuvygenerování konfigurace se správnou cestou ke schématu a poté potvrďte, že se v tomto umístění nachází soubor .gql nebo .graphql.

Dotaz vrátí prázdné výsledky.

Příznakem: Dotazy GraphQL vrací prázdný seznam, i když kontejner obsahuje data.

Příčina: Název kontejneru nebo cesta klíče oddílu v konfiguraci entity neodpovídá skutečnému kontejneru v Cosmos DB, nebo název databáze je nesprávný.

Rozlišení: Zkontrolujte hodnotu source entity dab-config.json a ověřte, že odpovídá přesnému názvu kontejneru (rozlišují se malá a velká písmena). Ověřte, že database pole v části data-source odpovídá názvu databáze Cosmos DB. Na webu Azure Portal otevřete Průzkumník dat pro účet a potvrďte názvy databází a kontejnerů.

Připojení TCP v přímém režimu selžou s emulátorem Linuxu

Příznak: DAB přestane reagovat nebo vyprší časový limit při připojování k emulátoru služby Cosmos DB v Linuxu v Dockeru, a to i při nastavení AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1. Požadavky se zastaví během opětovného pokusu o připojení.

Příčina: DAB v současné době pevně zakóduje ConnectionMode.Direct, což způsobuje, že sada Cosmos SDK zjistí koncové body fyzické partitiony (například 172.17.0.2:1025010255) a otevře k nim TCP připojení. Z hostitelského počítače jsou tyto adresy kontejneru nedostupné. Režim brány by směroval veškerý provoz přes jeden koncový bod HTTPS (port 8081 na emulátoru) a zcela tak obejít problém. Jedná se o známé omezení sledované v problému GitHubu č. 3401.

Rozlišení: Při spuštění kontejneru emulátoru nastavte AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1. Tím se emulátor přinutí uvádět 127.0.0.1 jako svou adresu, čímž umožní, aby byly zjištěné koncové body dostupné z hostitele. Dokud se režim brány v DAB nedá konfigurovat, je doporučené řešení pro místní vývoj přepis IP adresy.

Ověřování pomocí On-Behalf-Of (OBO) není podporováno.

Příznakem: Konfigurace ověřování on-Behalf-Of (OBO) pro instanci DAB založené na službě Azure Cosmos DB selže nebo se token nepřesměruje podle očekávání.

Příčina: Ověřování OBO je aktuálně podporováno pouze pro SQL Server a Azure SQL. Podpora služby Azure Cosmos DB ještě nebyla implementována. Jedná se o známé omezení sledované v problému GitHubu č. 3159.

Rozlišení: Použijte podporovanou metodu ověřování, jako je klíč účtu služby Cosmos DB nebo spravovaná identita. Sledujte issue na GitHubu pro aktualizace týkající se rozšíření podpory OBO na databáze jiné než SQL Server.

GraphQL ve filtru selže ve službě Cosmos DB

Příznak: Dotaz GraphQL, který používá operátor „in“ vůči entitě založené na Cosmos DB, selže za běhu s chybou "Nelze sestavit neznámou operaci predikátu IN," ačkoliv se objevuje ve schématu přes introspekci.

Příčina: Operátor in je viditelný ve vygenerovaném schématu GraphQL pro IdFilterInput a StringFilterInput, ale základní logika překladu filtru v Cosmos DB ho neimplementuje. Tato neshoda mezi schématem a exekutorem dotazů je známá chyba, která se sleduje v problému GitHubu č. 3061.

Rozlišení: Nepoužívejte operátor in v dotazech GraphQL na entity Cosmos DB. Místo toho použijte jedno z těchto alternativních řešení:

Nahraďte s využitím více výrazů nebo s použitím q výrazů pro malý, pevný seznam hodnot.
Při dotazování pomocí známého seznamu ID použijte více aliasů pro přímé čtení (item_by_pk).
Filtrování na straně klienta po načtení širší sady výsledků

Pro Cosmos DB se nepodporují agregace.

Příznakem: Agregované dotazy GraphQL (například počet, součet nebo vg) vůči entitě založené na Cosmos DB selžou nebo nejsou ve schématu k dispozici.

Příčina: Tvůrce Data API v současné době nepodporuje agregační operace pro službu Azure Cosmos DB. Agregace jsou k dispozici pouze pro relační databáze. Jedná se o známé omezení sledované v problému GitHubu č. 2849.

Řešení: V tuto chvíli neexistuje žádné alternativní řešení v rámci DAB. Agregace provádí na straně klienta po načtení sady výsledků nebo přímo k agregačním operacím použijte integrované rozhraní API dotazů služby Cosmos DB. Sledujte případ na GitHubu pro aktualizace.

Dotazy v množném čísle (seznamu) nelze zakázat, aby bylo možné vynutit jen čtení bodů.

Příznak: Klienti mohou zadávat dotazy na široký seznam položek pro entitu Cosmos DB, což spotřebovává vysoké RUs, když je záměr povolit pouze přímé čtení z položek pomocí item_by_pk.

Příčina: Tvůrce rozhraní Data API v současné době neposkytuje možnost konfigurace pro potlačení dotazů v množném čísle a omezení entity pouze na čtení. Jedná se o známé omezení sledované v problému GitHubu č. 2433.

Rozlišení: Jako částečné alternativní řešení omezte akci seznamu v oprávněních entity tak, aby omezovala role, které můžou vydávat dotazy na seznam. Úplné potlačení typu dotazu v množném čísle ze schématu se zatím nepodporuje.

Hierarchické klíče oddílů (MultiHash) se nepodporují.

Příznak: Mutace proti kontejneru Cosmos DB, který používá hierarchické klíče oddílu (více než jednu cestu ke klíči oddílu), selžou s chybou: Zadaná hodnota typu 'MultiHash' ve definici klíče oddílu je neplatná. Zvolte typ oddílu Hash.

Příčina: Nástroj rozhraní Data API podporuje pouze definice klíče oddílu s jedním klíčem (hash). Kontejnery nakonfigurované s hierarchickými klíči oddílů (MultiHash) se nepodporují. Jedná se o známé omezení sledované v problému GitHubu č. 1733.

Řešení: V tuto chvíli neexistuje žádné řešení v DAB. Pokud je to možné, přepracujte kontejner tak, aby používal jeden oddílový klíč. Pokud váš datový model vyžaduje hierarchické klíče oddílů, sledujte vlákno na GitHubu pro aktualizace o tom, kdy bude přidána podpora více hodnot hash.

Není podporováno používání MultiHash klíčů jako klíče pro oddíly.

Příznak: Operace vůči kontejneru Cosmos DB, který používá hierarchický klíč oddílu (multi-hash), selžou s neplatnou hodnotou 'kind' 'MultiHash' zadanou v definici klíče oddílu. Zvolte typ oddílu Hash.

Příčina: Tvůrce API pro Data podporuje pouze jednoduché klíče hash oddílů pro službu Azure Cosmos DB. Kontejnery nakonfigurované s hierarchickými klíči oddílu (MultiHash), například /TenantId, /EntityType, /EntityId, se nepodporují. Jedná se o známé omezení sledované v problému GitHubu č. 1733.

Řešení: V tuto chvíli neexistuje žádné alternativní řešení v rámci DAB. Místo toho použijte kontejner s jedním klíčem oddílu hash. Pokud je potřeba hierarchické dělení, zvažte restrukturalizaci kontejneru nebo sledování problému na GitHubu pro aktualizace, až bude přidána podpora klíče oddílu MultiHash.

Více mutací není v Cosmos DB atomické.

Příznak: Když se na entity Cosmos DB odešle několik mutací GraphQL v jediné žádosti, selhání v jedné mutaci nezpůsobí vrácení ostatních zpět. Může dojít k částečným zápisům.

Příčina: Nástroj pro vytváření API pro data nezabaluje více mutací Cosmos DB do jedné transakční dávky. Na rozdíl od relačních databází, kde se v požadavku provádí více mutací atomicky, jsou mutace v Cosmos DB vydávány nezávisle na sobě. Jedná se o známé omezení sledované v problému GitHubu č. 1621.

Rozlišení: Navrhněte aplikaci tak, aby každou mutaci Cosmos DB zpracovávala jako nezávislou. Pokud je vyžadována atomicita, použijte Cosmos DB SDK přímo s podporou transakční dávky omezenou na položky ve stejném logickém oddílu. Pokud chcete sledovat aktualizace o tom, kdy bude pro Cosmos DB přidána podpora transakčních mutací, sledujte issue na GitHubu.

Název typu GraphQL v souboru schématu neodpovídá konfiguraci entity.

Příznakem: DAB se spustí bez chyby, ale dotazy vrací neočekávané výsledky nebo nesprávný typ, protože název typu GraphQL definovaný ve schema.gql neodpovídá názvu jednotného typu nakonfigurovaného pro entitu v dab-config.json.

Příčina: Tvůrce rozhraní Data API v současné době neověřuje, zda název typu GraphQL v souboru schématu odpovídá názvu typu v jednotném čísle deklarovanému pro entitu. Nesoulad tiše vytváří nekonzistentní schéma. Jedná se o známé omezení sledované v problému GitHubu č. 1556.

Rozlišení: Ručně ověřte, že název typu ve schema.gql (nastavený direktivou @model ) odpovídá jednotné hodnotě v konfiguraci graphql.type entity v dab-config.json. Pokud například dab-config.json deklaruje "jednotné": "Umístění", soubor schématu by měl obsahovat umístění ype @model(name:"Location").

Název typu GraphQL v souboru schématu neodpovídá názvu jednotného typu entity.

Příčina: Nástroj pro vytváření rozhraní Data API v současné době neověřuje, že název direktivy @model v souboru schématu GraphQL odpovídá názvu jednotného typu přiřazeného entitě. Pokud se liší, neshoda nepozorovaně způsobí nesprávné chování schématu. Jedná se o známé omezení sledované v problému GitHubu č. 1556.

Rozlišení: Ručně se ujistěte, že název typu ve schema.gql přesně odpovídá jednotné hodnotě v konfiguraci graphql.type entity v dab-config.json. Pokud například entita definuje "singular": "Location", měl by soubor schématu deklarovat umístění ype @model(name:"Location"). Po provedení změn zachyťte další chyby konfigurace spuštěním příkazu dab.

Výčtové typy v souboru schématu GraphQL způsobují selhání sestavení schématu.

Příznak: DAB se nedaří spustit s HotChocolate.SchemaException: Nelze vyřešit referenci typu ... chyba OrderByInput, když soubor schema.gql služby Cosmos DB definuje typ GraphQL num použitý na poli typu objektu.

Příčina: Tvůrce Data API v současné době nepodporuje typy výčtu GraphQL v souboru schématu Cosmos DB. Při použití výčtu jako typu pole nemůže tvůrce schématu vygenerovat odpovídající typ OrderByInput a vyvolá neošetřenou výjimku. Jedná se o známé omezení sledované v problému GitHubu č. 748.

Rozlišení: Nahraďte pole výčtu jejich skalárními ekvivalenty (například použijte řetězec místo vlastního typu výčtu) ve schema.gql. Použijte ve vrstvě aplikace ověřování výčtu místo v definici schématu DAB.

Typy výčtů ve schématu GraphQL způsobují selhání DAB při spuštění

Příznak: DAB se nespustí s chybou HotChocolate.SchemaException, například Nejde vyřešit odkaz na typ 'None: FooOrderByInput', když soubor schématu GraphQL Cosmos DB definuje typ výčtu používaný v modelu.

Příčina: Tvůrce schématu Data API nesprávně zpracovává výčtové typy GraphQL definované ve souboru schema.gql. Pokud je výčet odkazován jako typ pole v modelu, interní generování typu OrderByInput ho nedokáže vyřešit a způsobí selhání inicializace schématu. Jedná se o známé omezení sledované v problému GitHubu č. 748.

Rozlišení: Vyhněte se definování typů výčtů GraphQL v schema.gql pro entity Cosmos DB. Jako alternativní řešení nahraďte výčtová pole řetězci a vynucujte platné hodnoty na úrovni aplikační vrstvy. Sledujte problém na GitHubu pro aktualizace, kdy bude přidána podpora výčtů.

Mapování polí (aliasy) nejsou podporována pro entity Cosmos DB.

Příznak: Oddíl mapování definovaný pro entitu Cosmos DB ve souboru dab-config.json nemá žádný vliv, protože ve schématu GraphQL se stále zobrazují původní názvy polí místo nakonfigurovaných aliasů.

Příčina: Funkce mapování, která umožňuje zobrazování názvů sloupců databáze pod různými názvy polí v rozhraní API, je implementována pouze pro relační databáze. Entity Cosmos DB v současné době nepodporují mapování polí. Jedná se o známé omezení sledované v problému GitHubu č. 1512.

Rozlišení: Názvy polí používejte přesně tak, jak se zobrazují v dokumentech Cosmos DB. Pokud je potřeba aliasing, použijte ho ve vrstvě klientské aplikace. Sledujte issue na GitHubu pro aktualizace, kdy bude přidána podpora mapování pro Cosmos DB.

Proměnné pro mutace v GraphQL nejsou vyhodnocovány; místo toho jsou ukládány jejich názvy namísto hodnot.

Příznak: GraphQL mutace, která používá proměnné (například createExample(item: { id: , name: })), ukládá názvy proměnných "" a "" v databázi místo skutečných hodnot předaných v datové části proměnných.

Příčina: Tvůrce rozhraní Data API v současné době neřeší odkazy na proměnné GraphQL ve vstupech mutací pro Cosmos DB. Nahrazení proměnné se přeskočí a název literálové proměnné se zapíše jako hodnota pole. Jedná se o známou chybu, která se sleduje v problému GitHubu č. 1482.

Rozlišení: Vložené hodnoty proměnných přímo v těle mutace místo použití proměnných GraphQL. Například nahraďte id: id: "1234". To není ideální pro použití v produkčním prostředí, proto sledujte GitHub issue pro aktualizace, kdy je opraveno zpracování proměnných pro mutace v Cosmos DB.

Typy sjednocení v souboru schématu GraphQL způsobují chybu 500

Příznakem: DaB vrátí stavový kód 500 u všech požadavků GraphQL, když schema.gql definuje sjednocovací typ GraphQL. Spouštěcí protokoly ukazují HotChocolate.SchemaException: Nelze vyřešit odkaz na typ ... OrderByInput.

Příčina: Tvůrce Data API nepodporuje typy sjednocení GraphQL v souboru schématu Cosmos DB. Podobně jako výčtové typy způsobují uniové typy chybu v nástroji pro generování schémat při vytváření vstupních typů pro řazení/filtraci. Jedná se o známou chybu, která se sleduje v problému GitHubu č. 1384.

Rozlišení: Odeberte definice unijních typů ze schématu.gql. Modelujte polymorfní data pomocí jednoho typu objektu s volitelnými poli nebo rozdělte data mezi samostatné entity. Sledujte vývoj na GitHubu pro aktualizace o přidání podpory pro union typy.

Vytvoření mutace selže během provádění, když je ID definováno jako nepovinné ve schématu.

Příznak: Při vytváření mutace se vrátí chyba za běhu, i když schema se zdá být platné. K chybě dochází, protože pole ID nebylo zadané nebo bylo null.

Příčina: Cosmos DB vyžaduje pole id pro každý dokument a používá ho jako část klíče oddílu. Pokud schema.gql deklaruje id jako hodnotu, která může být null (například id: ID místo id: ID!), DAB schéma přijme, ale za běhu při provádění vytvoření mutace selže, pokud je pole vynecháno. Schéma by mělo vynutit nenulovou hodnotu v době ověření schématu, ale v současné době ne. Tato mezera se sleduje v problému s GitHubem č. 1238.

Rozlišení: Vždy deklarujte pole ID jako nenulové ve schématu GraphQL služby Cosmos DB:

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

Zajištění ID: ID! způsobí, že klienti obdrží jasnou chybu na úrovni schématu, pokud je id vynecháno, spíše než neprůhledné selhání za běhu.

Cyklické vztahy GraphQL způsobují výjimku přetečení zásobníku při spuštění

Příznak: DAB se při spuštění chybově ukončí s výjimkou přetečení zásobníku, když schema.gql definuje typy, které vzájemně odkazují v cyklu (například Hráč odkazuje na Hru a Hra odkazuje na Hráče).

Příčina: Tvůrce schématu prochází rekurzivně všechny odkazy na typy, aby se vytvořily vstupní typy pro mutace. Cyklické relace způsobují nekonečné rekurze a vyčerpají zásobník volání. Jedná se o známou chybu, která se sleduje v problému GitHubu č. 746.

Rozlišení: Vyhněte se cyklických odkazům na typy ve schema.gql. Přerušte cyklus odebráním zpětného odkazu z jednoho z typů nebo modelováním relace jako seznamu ID (skalárních polí) místo vnořených typů objektů. Sledujte vlákno na GitHubu pro aktualizace o podpoře cirkulárních vztahů.

Klíč oddílu musí být vždy ID, používání cest k vlastním klíčům oddílů není podporováno.

Příznakem: DAB funguje jenom s kontejnery Cosmos DB, které jako klíč oddílu používají /id. Kontejnery dělené podle jakéhokoli jiného pole (například /userId nebo /category) nelze správně dotazovat ani upravovat.

Příčina: tvůrce Data API rozhraní pevně nastavuje id jako klíč oddílu pro všechny entity Cosmos DB. Neexistuje způsob, jak zadat cestu k vlastnímu oddílovému klíči ani v souboru dab-config.json, ani v souboru schema.gql. Jedná se o známé omezení sledované v problému GitHubu č. 747.

Řešení: Při používání DAB navrhujte nové kontejnery s použitím /id jako klíče oddílu. Pro existující kontejnery s jiným klíčem oddílu není podpora pro DAB momentálně k dispozici. Sledujte problém na GitHubu pro aktualizace, kdy budou přidány konfigurovatelné klíče oddílů.

Dotazování vnořených polí v dokumentu (spojení v položkách) se nepodporuje.

Příznak: Nelze filtrovat ani procházet vlastnosti vnořeného pole v dokumentu Cosmos DB při použití DAB. Dotazy, které by vyžadovaly JOIN v Cosmos DB napříč prvky v poli, nevrátí žádné výsledky nebo vrátí chybu.

Příčina: Data API builder nepodporuje spojení uvnitř dokumentu služby Cosmos DB (označované také jako spojení v položkách), které jsou potřeba k dotazování vnořených polí v jednom dokumentu. Jedná se o známé omezení sledované v problému GitHubu č. 262.

Řešení: Zploštěte vnořená pole do samostatných entit nebo podřízených dokumentů, pokud potřebujete filtrovat jejich obsah. Případně proveďte následné zpracování celého dokumentu ve vrstvě aplikace. Sledujte problém na GitHubu pro aktualizace o přidání podpory propojení v rámci dokumentu.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-04-01