Azure Cosmos DB のトラブルシューティング

データ API ビルダーでの Azure Cosmos DB エミュレーター、接続、およびスキーマ構成に関する一般的な問題の解決策。

一般的な質問

DAB での Azure Cosmos DB サポートとは

データ API ビルダーは、NoSQL バックエンドとして Azure Cosmos DB をサポートしています。 DAB は、Azure Cosmos DB .NET SDK を使用して Cosmos DB に接続し、GraphQL 型としてエンティティを公開します。 Cosmos DB の REST サポートは利用できません。すべてのクエリは GraphQL エンドポイントを介して処理されます。

DAB は Cosmos DB でどのような API を使用しますか?

DAB では、Azure Cosmos DB for NoSQL API (旧称 SQL API) が使用されます。 MongoDB、Gremlin、Table などの他の Cosmos DB API はサポートされていません。 Azure Cosmos DB for NoSQL API を使用して Cosmos DB アカウントが作成されていることを確認します。

Cosmos DB エミュレーターはサポートされていますか?

Yes. Azure Cosmos DB エミュレーターは、ローカル開発でサポートされています。接続文字列をエミュレーターの既定のエンドポイント ( AccountEndpoint=https://localhost:8081/;AccountKey=<emulator-key>;) に設定します。 DAB が接続する前に、開発マシンでエミュレーターの自己署名証明書を信頼する必要があります。

一般的な問題

エミュレーター証明書が信頼されていません

症状： DAB は、SSL または証明書検証エラーでエミュレーターに接続できません。

原因： Azure Cosmos DB エミュレーターでは、オペレーティングシステムで既定で信頼されていない自己署名証明書が使用されます。

解像度： エミュレーター証明書を https://localhost:8081/_explorer/emulator.pem からローカルコンピューターの信頼されたルート証明書ストアにエクスポートしてインストールします。 Windows で証明書ファイルを開き、 信頼されたルート証明機関 > ローカルコンピューターにインストールします。証明書をインストールした後、DAB を再起動します。

エミュレーターに接続できない

症状： DAB が The remote name could not be resolved: 'localhost' で開始できないか、ポート 8081を指す接続拒否エラーが発生しました。

原因： エミュレーターが実行されていないか、接続文字列内のエンドポイントまたはアカウントキーが正しくありません。

解像度： [スタート] メニューから、またはエミュレーターの実行可能ファイルを実行して、Azure Cosmos DB エミュレーターを起動します。接続文字列で AccountEndpoint=https://localhost:8081/ と正しいエミュレーターキーが使用されていることを確認します。これは、エミュレーターのデータエクスプローラーページに https://localhost:8081/_explorer/index.htmlに表示されます。

GraphQL スキーマファイルが見つかりません

症状： DAB は、 Schema file not found や graphql-schema path is invalidなどのエラーで開始できません。

原因：graphql.schemaのdab-config.json パスは、存在しないファイル、または正しくない相対パスを使用しているファイルを指しています。

解像度： スキーマファイルが、 dab-config.jsonで指定されたパスに存在するかどうかを確認します。パスは、構成ファイルの場所に対する相対パスです。 dab initで--cosmosdb_nosql-schemaを実行して正しいスキーマパスで構成を再生成し、その場所に.gqlまたは.graphqlファイルが存在することを確認します。

クエリから空の結果が返される

症状： コンテナーにデータがある場合でも、GraphQL クエリは空のリストを返します。

原因： エンティティ構成のコンテナー名またはパーティションキーパスが実際の Cosmos DB コンテナーと一致しないか、データベース名が正しくありません。

解像度：sourceでエンティティのdab-config.json値を確認し、それが正確なコンテナー名と一致する (大文字と小文字が区別されます) ことを確認します。 databaseのdata-source フィールドが Cosmos DB データベース名と一致するかどうかを確認します。 Azure portal で、アカウントの データエクスプローラー を開き、データベースとコンテナーの名前を確認します。

Linux エミュレーターで直接モードの TCP 接続が失敗する

症状： AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1 が設定されている場合でも、Docker で Cosmos DB Linux エミュレーターに接続すると DAB がハングまたはタイムアウトします。接続の再試行中に要求が停止します。

原因： DAB は現在 ConnectionMode.Direct をハードコードしています。これにより、Cosmos SDK は物理パーティションエンドポイント (172.17.0.2:1025010255 など) を検出し、それらに対する TCP 接続を開きます。ホストコンピューターから、これらのコンテナーアドレスに到達できません。ゲートウェイモードでは、すべてのトラフィックが単一の HTTPS エンドポイント (エミュレーターのポート 8081) 経由でルーティングされ、問題が完全に回避されます。これは、 GitHub の問題 #3401 で追跡されている既知の制限です。

解像度： エミュレーターコンテナーの起動時に AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1 に設定します。これにより、エミュレーターはそのアドレスとして 127.0.0.1 をアドバタイズし、検出されたエンドポイントにホストから到達可能になります。 DAB でゲートウェイモードを構成できるようになるまで、IP オーバーライドはローカル開発に推奨される回避策です。

On-Behalf-Of (OBO) 認証はサポートされていません

症状： Azure Cosmos DB ベースの DAB インスタンスに対するオンBehalf-Of (OBO) 認証の構成が失敗するか、トークンが想定どおりに転送されません。

原因： OBO 認証は現在、SQL Server と Azure SQL でのみサポートされています。 Azure Cosmos DB のサポートはまだ実装されていません。これは、 GitHub の問題 #3159 で追跡されている既知の制限です。

解像度： Cosmos DB アカウントキーやマネージド ID など、サポートされている認証方法を使用します。 OBO サポートが SQL Server 以外のデータベースに拡張される場合の更新については、GitHub の問題に従ってください。

Cosmos DB でフィルター内の GraphQL が失敗する

症状： Cosmos DB にバックアップされているエンティティに対して in 演算子を使用する GraphQL クエリが、実行時に "Cannot build unknown predicate operation IN" というエラーで失敗します。これは、イントロスペクションを通じてスキーマに表示されている場合でも発生します。

原因： in 演算子は、IdFilterInput と StringFilterInput の生成された GraphQL スキーマで公開されますが、基になる Cosmos DB フィルター変換ロジックでは実装されません。スキーマとクエリ実行プログラムのこの不一致は、 GitHub の問題 #3061 で追跡されている既知のバグです。

解像度： Cosmos DB エンティティに対する GraphQL クエリでは in 演算子を使用しないでください。代わりに、次のいずれかの回避策を使用してください。

小さい固定値リストの場合は、複数の式または + q 式に置き換えます。
既知の ID の一覧でクエリを実行するときは、複数のポイント読み取りエイリアス (item_by_pk) を使用します。
より広範な結果セットを取得した後、クライアント側をフィルター処理します。

Cosmos DB では集計はサポートされていません

症状： Cosmos DB でサポートされるエンティティに対する GraphQL 集計クエリ (カウント、合計、vg など) が失敗するか、スキーマで使用できません。

原因： データ API ビルダーでは現在、Azure Cosmos DB の集計操作はサポートされていません。集計はリレーショナルデータベースでのみ使用できます。これは、 GitHub の問題 #2849 で追跡されている既知の制限です。

解像度： 現時点では、DAB 内に回避策はありません。結果セットを取得した後にクライアント側で集計を実行するか、Cosmos DB の組み込みクエリ API を集計操作に直接使用します。 GitHub のイシューをフォローして更新情報を受け取ってください。

複数形 (リスト) クエリを無効にして、ポイント読み取りのみを適用することはできません

症状： クライアントは、Cosmos DB エンティティに対して広範なアイテム一覧クエリを発行し、高いリクエストユニット (RU) を消費していますが、本当の目的はitem_by_pk経由のポイント読み取りのみを許可することです。

原因： 現在、データ API ビルダーには、複数のクエリを抑制し、エンティティを読み取り専用に制限する構成オプションは用意されていません。これは、 GitHub の問題 #2433 で追跡されている既知の制限です。

解像度： 部分的な回避策として、エンティティのアクセス許可のリストアクションを制限して、リストクエリを発行できるロールを制限します。スキーマからの複数形クエリ型の完全な抑制はまだサポートされていません。

階層パーティションキー (MultiHash) はサポートされていません

症状： 階層パーティションキー (複数のパーティションキーパス) を使用する Cosmos DB コンテナーに対する変更は、エラーで失敗します。パーティションキー定義で指定された 'kind' 値 'MultiHash' は無効です。 [ハッシュ] パーティションの種類を選択してください。

原因： データ API ビルダーでは、単一キー (ハッシュ) パーティションキー定義のみがサポートされます。階層パーティションキー (MultiHash) で構成されたコンテナーはサポートされていません。これは、 GitHub の問題 #1733 で追跡されている既知の制限です。

解像度： 現時点では、DAB 内に回避策はありません。可能であれば、1 つのパーティションキーを使用するようにコンテナーを再設計します。データモデルで階層パーティションキーが必要な場合は、マルチハッシュのサポートが追加されたときの更新に関する GitHub の問題に従ってください。

MultiHash パーティションキーはサポートされていません

症状： 階層 (マルチハッシュ) パーティションキーを使用する Cosmos DB コンテナーに対するミューテーションは、パーティションキー定義で指定された 'kind' 値 'MultiHash' が無効であるため失敗します。 [ハッシュ] パーティションの種類を選択してください。

原因： データ API ビルダーでは、Azure Cosmos DB の単一値ハッシュパーティションキーのみがサポートされます。階層パーティションキー (MultiHash) で構成されたコンテナー (/TenantId、/EntityType、/EntityId など) はサポートされていません。これは、 GitHub の問題 #1733 で追跡されている既知の制限です。

解像度： 現時点では、DAB 内に回避策はありません。代わりに、1 つのハッシュパーティションキーを持つコンテナーを使用してください。階層的パーティション分割が必要な場合は、MultiHash パーティションキーのサポートが追加されたときに、コンテナーを再構築するか、GitHub の問題に従って更新することを検討してください。

Cosmos DB で複数の変異がアトミックではない

症状： Cosmos DB エンティティに対して 1 つの要求で複数の GraphQL 変更が送信された場合、1 つの変更の失敗は他の変更をロールバックしません。部分的な書き込みが発生する可能性があります。

原因： データ API ビルダーは、トランザクションバッチ内で複数の Cosmos DB の変更をラップしません。要求内の複数の変更がアトミックに実行されるリレーショナルデータベースとは異なり、Cosmos DB の変更は個別に発行されます。これは、 GitHub の問題 #1621 で追跡されている既知の制限です。

解像度： 各 Cosmos DB の変異を独立として扱うようにアプリケーションを設計します。アトミック性が必要な場合は、トランザクションバッチのサポートで直接 Cosmos DB SDK を使用します。スコープは同じ論理パーティション内の項目です。 Cosmos DB にトランザクション変異サポートが追加される際の更新については、GitHub のイシューをフォローしてください。

スキーマファイル内の GraphQL 型名がエンティティ構成と一致しない

症状： DAB はエラーなしで開始しますが、schema.gql で定義されている GraphQL 型名が、dab-config.jsonのエンティティに対して構成された単一の型名と一致しないため、クエリは予期しない結果または間違った型を返します。

原因： データ API ビルダーでは現在、スキーマファイル内の GraphQL 型名がエンティティに対して宣言された単一の型名と一致することを検証していません。不一致が発生すると、一貫性のないスキーマが生成されます。これは、 GitHub の問題 #1556 で追跡されている既知の制限です。

解像度： schema.gql の型名 ( @model ディレクティブを使用して設定) が、dab-config.jsonのエンティティの graphql.type 構成の単数形の値と一致することを手動で確認します。たとえば、dab-config.json で "singular": "Location" が宣言されている場合、スキーマファイルには ype Location @model(name:"Location") が含まれている必要があります。

スキーマファイル内の GraphQL 型名がエンティティの単数型名と一致しない

原因： データ API ビルダーでは現在、GraphQL スキーマファイル内の @model ディレクティブ名がエンティティに設定されている単一の型名と一致することを検証していません。異なる場合、不一致がひそかに誤ったスキーマ動作を引き起こします。これは、 GitHub の問題 #1556 で追跡されている既知の制限です。

解像度： schema.gql の型名が、dab-config.jsonのエンティティの graphql.type 構成の単数形の値と正確に一致することを手動で確認します。たとえば、エンティティで "singular": "Location" が定義されている場合、スキーマファイルは ype Location @model(name:"Location") を宣言する必要があります。変更を加えて他の構成エラーをキャッチした後、dab validate を実行します。

GraphQL スキーマファイル内の列挙型が原因でスキーマビルドエラーが発生する

症状： DAB が HotChocolate.SchemaException で開始できない: 型参照を解決できません...Cosmos DB schema.gql ファイルでオブジェクト型フィールドで使用される GraphQL の数値型が定義されている場合の OrderByInput エラー。

原因： データ API ビルダーでは現在、Cosmos DB スキーマファイルの GraphQL 列挙型はサポートされていません。列挙型がフィールド型として使用されている場合、スキーマビルダーは対応する OrderByInput 型を生成できず、ハンドルされない例外をスローします。これは、 GitHub の問題 #748 で追跡されている既知の制限です。

解像度： schema.gql では、列挙型フィールドをスカラーに相当するもの (カスタム列挙型の代わりに String を使用するなど) に置き換えます。 DAB スキーマ定義ではなく、アプリケーションレイヤーで列挙型の検証を適用します。

GraphQL スキーマの列挙型により、起動時に DAB が失敗する

症状： DAB は、Cosmos DB GraphQL スキーマファイルでモデルに使用される列挙型を定義すると、'None: FooOrderByInput' という型参照を解決できないという HotChocolate.SchemaException エラーによって開始できません。

原因： データ API ビルダーのスキーマビルダーは、schema.gql で定義されている GraphQL 列挙型を正しく処理しません。列挙型がモデルのフィールド型として参照されている場合、内部の OrderByInput 型の生成が失敗し、スキーマの初期化がクラッシュします。これは、 GitHub の問題 #748 で追跡されている既知の制限です。

解像度： Cosmos DB エンティティの schema.gql で GraphQL 列挙型を定義しないでください。回避策として、列挙型フィールドを String に置き換え、アプリケーションレイヤーで有効な値を適用します。列挙型のサポートが追加されたときの更新については、GitHub の問題に従ってください。

Cosmos DB エンティティではフィールドマッピング (エイリアス) はサポートされていません

症状： dab-config.json の Cosmos DB エンティティに対して定義されたマッピングセクションでは、構成されたエイリアスではなく、元のフィールド名が GraphQL スキーマで引き続き公開される影響はありません。

原因： API 内の異なるフィールド名の下にデータベース列名を公開できるマッピング機能は、リレーショナルデータベースに対してのみ実装されます。 Cosmos DB エンティティは現在、フィールドマッピングをサポートしていません。これは、 GitHub の問題 #1512 で追跡されている既知の制限です。

解像度： フィールド名は、Cosmos DB ドキュメントに表示されるとおりに使用します。エイリアスが必要な場合は、クライアントアプリケーションレイヤーに適用します。 Cosmos DB のマッピングサポートが追加されたときの更新については、GitHub の問題に従ってください。

GraphQL ミューテーション変数は、値の代わりに格納される解決された変数名ではありません

症状： 変数 (例: createExample(item: { id: , name: })) を使用する GraphQL の変更では、ariables ペイロードで渡された実際の値ではなく、変数名 "" と "" がデータベースに格納されます。

原因： データ API ビルダーは現在、Cosmos DB の変更入力の GraphQL 変数参照を解決していません。変数の置換はスキップされ、リテラル変数名はフィールド値として書き込まれます。これは、 GitHub の問題 #1482 で追跡されている既知のバグです。

解像度： GraphQL 変数を使用する代わりに、変更本文で変数値を直接インライン化します。たとえば、id: を id: "1234" に置き換えます。これは運用環境での使用には適していないため、Cosmos DB の変更に対して変数処理が修正された場合の更新については、GitHub の問題に従ってください。

GraphQL スキーマファイルのユニオン型が 500 エラーを発生させる

症状： schema.gql で GraphQL 共用体型が定義されている場合、DAB は、すべての GraphQL 要求に対して 500 状態コードを返します。起動ログには、HotChocolate.SchemaException: 型参照を解決できません...OrderByInput。

原因： データ API ビルダーは、Cosmos DB スキーマファイルの GraphQL 共用体型をサポートしていません。列挙型と同様に、共用体型を使用すると、並べ替え/フィルター入力型を生成するときにスキーマビルダーが失敗します。これは、 GitHub の問題 #1384 で追跡されている既知のバグです。

解像度： schema.gql から共用体の型定義を削除します。オプションのフィールドを持つ単一のオブジェクト型を使用してポリモーフィックなデータをモデル化するか、データを個別のエンティティに分割します。ユニオンタイプのサポートが追加されるときの更新については、GitHub のイシューをフォローしてください。

ID がスキーマで null 許容として定義されている場合、実行時に変更の作成が失敗する

症状： スキーマが有効な場合でも、作成の変更によってランタイムエラーが返されます。このエラーは、id フィールドが指定されなかったか、null であったために発生します。

原因： Cosmos DB では、すべてのドキュメントの ID フィールドが必要であり、パーティションキーの一部として使用されます。 schema.gql で id が null 許容として宣言されている場合 (たとえば、id: ID! ではなく id: ID!)、DAB はスキーマを受け入れますが、作成時の変更でフィールドが省略されると実行時に失敗します。スキーマは、スキーマ検証時に null 以外を適用する必要がありますが、現在は適用されません。このギャップは、 GitHub の問題 #1238 で追跡されています。

解像度： Cosmos DB GraphQL スキーマでは、常に id フィールドを null 以外として宣言します。

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

IDの確保: ID! ID が省略されると、クライアントが非透過的なランタイムエラーを受け取る代わりに、明確なスキーマレベルのエラーが発生します。

GraphQL の循環リレーションシップにより、起動時にスタックオーバーフロー例外が発生する

症状： schema.gql がサイクル内で相互に参照する型を定義すると (たとえば、プレイヤーがゲームを参照し、ゲームが Player を参照する) 場合、起動時にスタックオーバーフロー例外が発生して DAB がクラッシュします。

原因： スキーマビルダーは、すべての型参照を再帰的に追跡して、変更入力型を生成します。循環リレーションシップによって無限再帰が発生し、呼び出し履歴が使い果たされます。これは、 GitHub の問題 #746 で追跡されている既知のバグです。

解像度： schema.gql での循環型参照を避けます。いずれかの型からバックリファレンスを削除してサイクルを中断するか、入れ子になったオブジェクト型ではなく ID (スカラーフィールド) のリストとしてリレーションシップをモデル化します。循環リレーションシップのサポートについての更新は、GitHub イシューをフォローしてください。

パーティションキーは常にidであり、カスタムパーティションキーパスはサポートされていません。

症状： DAB は、パーティションキーとして /id を使用する Cosmos DB コンテナーでのみ機能します。他のフィールド (/userId や /category など) でパーティション分割されたコンテナーは、クエリを実行したり、正しく変更したりできません。

原因： データ API ビルダーは、すべての Cosmos DB エンティティのパーティションキーとして ID をハードコーディングします。 dab-config.json または schema.gql でカスタムパーティションキーパスを指定する方法はありません。これは、 GitHub の問題 #747 で追跡されている既知の制限です。

解像度： DAB を使用する場合は、パーティションキーとして /id を使用して新しいコンテナーを設計します。パーティションキーが異なる既存のコンテナーの場合、DAB は現在サポートされていません。構成可能なパーティションキーが追加されたときの更新については、GitHub の問題に従ってください。

ドキュメント内の入れ子になった配列のクエリ (項目内結合) はサポートされていません

症状： DAB を使用して Cosmos DB ドキュメント内の入れ子になった配列プロパティをフィルター処理または走査することはできません。配列要素間で Cosmos DB JOIN を必要とするクエリでは、結果もエラーも返されません。

原因： データ API ビルダーでは、Cosmos DB のドキュメント内結合 (アイテム内結合とも呼ばれます) はサポートされていません。これは、1 つのドキュメント内の入れ子になった配列に対してクエリを実行するために必要です。これは、 GitHub の問題 #262 で追跡されている既知の制限です。

解像度： 内容をフィルター処理する必要がある場合は、入れ子になった配列を個別のエンティティまたは子ドキュメントにフラット化します。または、アプリケーションレイヤーで完全なドキュメントの後処理を実行します。ドキュメント内結合サポートが追加される更新を確認するには、GitHub の課題をフォローしてください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-04-01