針對常見 Azure Cosmos DB 模擬器、連接性及 Data API 建構器架構設定問題的解決方案。
常見問題
Azure Cosmos DB 在 DAB 中的支援是什麼？
Data API 建構器支援 Azure Cosmos DB 作為 NoSQL 後端。 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）。 其他 Cosmos DB API 如 MongoDB、Gremlin 和 Table 則不被支援。 請確保您的 Cosmos DB 帳號是使用 Azure Cosmos DB for NoSQL API 建立的。
Cosmos DB 模擬器有支援嗎？
是的。 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 foundgraphql-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 入口網站中，打開帳號 的資料總管 ，確認資料庫和容器名稱。
直接模式 TCP 連線在 Linux 模擬器中會失敗
症狀： 即使設定為 AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1，DAB 在 Docker 中連接 Cosmos DB Linux 模擬器時仍然會無回應或超時。 請求在連線重試時會卡住。
原因： 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 覆蓋作為替代方案。
不支援開啟Behalf-Of（OBO）認證
症狀：設定以 Azure Cosmos DB 做為後端的 DAB 實例時，代理人（On-Behalf-Of, OBO）認證失敗，或令牌未如預期地轉發。
原因： OBO 認證目前僅支援 SQL Server 和 Azure SQL。 Azure Cosmos DB 的支援尚未實作。 這是 GitHub issue #3159 中追蹤的已知限制。
解決： 使用支援的認證方式，例如 Cosmos DB 帳號金鑰或管理身份。 請關注 GitHub 公告，了解何時 OBO 支援擴展至非 SQL Server 資料庫的最新消息。
在 Cosmos DB 中，GraphQL 在過濾器中失敗
症狀： 使用 in 運算子對 Cosmos DB 支援的實體進行 GraphQL 查詢，執行時會失敗，並顯示錯誤訊息：無法建立未知的謂詞操作 IN，儘管在結構中透過內省顯示有 in。
原因： in 運算子在產生的 GraphQL 架構中公開於 IdFilterInput 與 StringFilterInput，但底層的 Cosmos DB 濾波器轉換邏輯並未實作此運算子。 這種結構與查詢執行器之間的不匹配是 GitHub issue #3061 中追蹤的已知錯誤。
解決： 避免在 GraphQL 對 Cosmos DB 實體查詢中使用 in 運算子。 改用以下其中一個變通方法：
- 將 "in" 替換為多個或 + q 表達式，以表示小型且固定的值列表。
- 在查詢已知 ID 清單時，使用多個點讀別名（item_by_pk）。
- 取得更廣泛的結果集後，進行客戶端篩選。
Cosmos DB 不支援聚合
症狀： 在 Cosmos DB 支援的實體上執行 GraphQL 聚合查詢（例如 count、sum 或 vg）會失敗或無法在綱要中提供。
原因： Data API 建構器目前不支援 Azure Cosmos DB 的聚合操作。 聚合僅適用於關聯式資料庫。 這是 GitHub issue #2849 中追蹤的已知限制。
解決： 目前 DAB 內沒有解決方法。 取得結果集後，可以在客戶端執行聚合，或直接使用 Cosmos DB 內建的查詢 API 進行聚合操作。 請追蹤 GitHub issue 以獲取最新消息。
複數（清單）查詢無法被停用以強制只執行點讀取
症狀： 當客戶端的意圖是只允許透過 item_by_pk 進行點讀取時，可以對 Cosmos 資料庫實體發出廣泛的項目清單查詢，耗費大量 RU。
原因： Data API 建構器目前尚未提供設定選項來抑制複數查詢並限制實體僅進行點讀取。 這是 GitHub issue #2433 中追蹤的已知限制。
解決： 作為部分變通方法，限制實體權限中的清單動作，限制哪些角色可以發出清單查詢。 目前尚未支援從結構中完全抑制複數查詢型態。
不支援階層分割鍵（MultiHash）
症狀： 對使用階層分割金鑰（多條分區金鑰路徑）的 Cosmos DB 容器進行突變時，會因錯誤而失敗。分割金鑰定義中指定的「kind」值「MultiHash」無效。 請選擇「雜湊」分割類型。
原因： Data API 建構器僅支援單鍵（雜湊）分割區金鑰定義。 不支援配置為階層分割鍵（MultiHash）的容器。 這是 GitHub issue #1733 中追蹤的已知限制。
解決： 目前 DAB 內沒有解決方法。 如果可能，重新設計容器以使用單一分割鍵。 如果您的資料模型需要階層式分割鍵，請參考 GitHub 問題頁面以獲取新增多重雜湊支援時間的更新。
不支援 MultiHash 雜湊分區鍵
症狀： 使用階層式（多雜湊）分割鍵的 Cosmos DB 容器進行突變時，因為在分割鍵定義中指定的「kind」值「MultiHash」無效而失敗。 請選擇「雜湊(Hash)」分割類型。
原因： Data API 建構器僅支援 Azure Cosmos DB 的單一值雜湊分割金鑰。 不支援使用階層分割鍵（MultiHash）配置的容器，例如 /TenantId、/EntityType、/EntityId。 這是 GitHub issue #1733 中追蹤的已知限制。
解決： 目前 DAB 內沒有解決方法。 請改用一個只有單一雜湊分割鍵的容器。 若需要階層分割，請考慮重組容器或追蹤 GitHub 問題，了解何時加入 MultiHash 分割金鑰支援。
多重突變在 Cosmos 資料庫中並非原子級的
症狀： 當單一請求中對 Cosmos DB 實體發送多個 GraphQL 變異時，若其中一個變異失效，不會回復其他變異。 部分寫入可能會發生。
原因： Data API 建構器不會將多個 Cosmos DB 變異包裝成交易批次。 與關聯式資料庫不同，後者請求中的多個突變會以原子方式執行，Cosmos DB 的變異則是獨立發出的。 這是 GitHub issue #1621 中追蹤的已知限制。
解決： 設計你的應用程式，將每個 Cosmos DB 突變視為獨立。 如果需要原子性，請直接使用 Cosmos DB SDK 的交易批次支援，並將範圍限定在同一邏輯分割區內的項目。 請關注 GitHub issue 以獲取 Cosmos DB 何時加入交易型突變支援的最新消息。
結構檔案中的 GraphQL 類型名稱與實體設定不符
症狀： DAB 開始時無錯誤，但查詢會回傳意外結果或錯誤型別，因為 schema.gql 中定義的 GraphQL 型別名稱與 dab-config.json中實體所設定的單數型別名稱不符。
原因： Data API 建構器目前無法驗證結構檔案中的 GraphQL 型別名稱是否與該實體宣告的單數型別名稱相符。 不匹配會悄然產生不一致的圖式。 這是 GitHub issue #1556 中追蹤的已知限制。
解決： 手動驗證 schema.gql 中的型別名稱（透過 @model 指令設定）是否與實體 graphql.type 配置中的奇數值相符 dab-config.json。 例如，如果 dab-config.json 宣告「單數」：「Location」，結構檔案中應該包含 ype Location @model(name：「Location」。
結構檔案中的 GraphQL 類型名稱與實體單數類型名稱不符
症狀： DAB 開始時無錯誤，但查詢會回傳意外結果或錯誤型別，因為 schema.gql 中定義的 GraphQL 型別名稱與 dab-config.json中實體所設定的單數型別名稱不符。
原因： Data API 建構器目前無法驗證 GraphQL 結構檔案中的指令名稱是否 @model 與該實體的單數型別名稱相符。 當兩者不同時，不匹配會悄然產生錯誤的模式行為。 這是 GitHub issue #1556 中追蹤的已知限制。
解決： 手動確保 schema.gql 中的型別名稱與實體的 dab-config.json 中 graphql.type 配置中的單一值完全一致。 例如，如果實體定義「單數」為「Location」，結構檔應該宣告 ype Location @model(name：「Location」。 在做了修改後執行 dab 驗證，以捕捉其他設定錯誤。
GraphQL 架構檔案中的枚舉型別會導致結構建置失敗
症狀： DAB 因為 HotChocolate.SchemaException 而無法啟動：無法解析型別參考...當 Cosmos DB 的 schema.gql 檔案在物件類型欄位定義中使用 GraphQL 數值型時，會發生 OrderByInput 錯誤。
原因： Data API 建構器目前不支援 Cosmos DB 架構檔中的 GraphQL 列舉型別。 當列舉被用作欄位類型時，架構建構器無法產生對應的 OrderByInput 類型，並拋出一個未處理的例外。 這是 GitHub issue #748 中追蹤的已知限制。
解決： 在 schema.gql 中，將列舉欄位替換為其純量等價物（例如，使用 String 代替自訂的列舉型別）。 在你的應用層套用枚舉驗證，而不是在 DAB 架構定義中。
GraphQL 架構中的列舉型別會導致 DAB 在啟動時失敗
症狀： 當 Cosmos DB GraphQL 架構檔案定義了一個模型所使用的枚舉型別時，DAB 在啟動時會遇到 HotChocolate.SchemaException 錯誤，例如無法解析型別參考 'None： FooOrderByInput'。
原因： Data API 建構器的結構建構器無法正確處理 schema.gql 定義的 GraphQL 列舉型別。 當列舉被以模型中的欄位類型參考時，內部的 OrderByInput 類型生成無法被解析，導致架構初始化當掉。 這是 GitHub issue #748 中追蹤的已知限制。
解決： 避免在 schema.gql 中為 Cosmos DB 實體定義列舉型別。 作為一個變通方法，將列舉欄位替換為 String，並在應用層強制執行有效值。 請持續關注 GitHub issue 以獲取對於新增列舉支援的更新。
Cosmos DB 實體不支援欄位映射（別名）
症狀： 在 dab-config.json 中為 Cosmos DB 實體定義的映射區段沒有發揮作用，原始欄位名稱而非設定的別名，仍然會在 GraphQL 架構中暴露出來。
原因： 映射功能允許在 API 中以不同欄位名稱暴露資料庫欄位名稱，僅實作於關聯式資料庫。 Cosmos DB 實體目前不支援欄位映射。 這是 GitHub issue #1512 中追蹤的已知限制。
解決： 欄位名稱請完全按照 Cosmos DB 文件中出現的方式使用。 如果需要別名，請在用戶端應用層套用。 請關注 GitHub issue 以獲取 Cosmos DB 地圖支援何時加入的最新消息。
GraphQL 的變異變數並非被解析的變數名稱所儲存，而非值
症狀： 使用變數的 GraphQL 變異（例如 createExample（item： { id： ， name： }））會在資料庫中儲存變數名稱「」和「」，而非 ariables payload 中傳遞的實際值。
原因： Data API 建構器目前無法解析 Cosmos DB 變異輸入中的 GraphQL 變數參考。 會跳過變數替換，並將變數的字面名稱寫成欄位值。 這是 GitHub issue #1482 中追蹤的已知錯誤。
解決： 直接將變數值內嵌在突變本體中，而非使用 GraphQL 變數。 例如，將 id： 替換為 id：「1234」。 這對生產環境來說並不理想，請參考 GitHub issue 以獲取 Cosmos DB 變異變數處理修正的更新。
GraphQL 架構檔案中的聯合型別會造成 500 錯誤
症狀： 當 schema.gql 定義 GraphQL 聯合型別時，DAB 會對所有 GraphQL 請求回傳 500 的狀態碼。 啟動日誌顯示 HotChocolate.SchemaException：無法解析型別參考 ...OrderByInput。
原因： Data API 建構器在 Cosmos DB 架構檔案中不支援 GraphQL 聯集型別。 和 enum 類型一樣，union 類型會導致結構建構器在產生排序/篩選輸入類型時失敗。 這是 GitHub issue #1384 中追蹤的已知錯誤。
解決： 移除 schema.gql 中的聯合型別定義。 使用單一物件類型並搭配可選欄位來建模多型性資料，或將資料拆分到不同的實體。 請追蹤 GitHub issue 以獲取何時加入工會類型支援的最新消息。
當 id 在結構中被定義為可空時，Create 變異在執行時會失敗
症狀： Create 突變會回傳執行時錯誤，儘管結構看起來有效。 錯誤發生是因為 id 欄位未被提供或為空。
原因： Cosmos DB 要求每份文件都必須有 id 欄位，並將其作為分割鍵的一部分使用。 如果 schema.gql 宣告 id 為可空（例如 id： ID 而非 id： ID！），DAB 會接受該架構，但在執行時當 create 變異省略該欄位時會失敗。 架構在結構驗證時應該強制執行非空，但目前尚未執行。 這個缺口在 GitHub 第 #1238 號有追蹤。
解決： 在你的 Cosmos DB GraphQL 架構中，務必將 id 欄位宣告為非空：
graphql type MyEntity @model(name: "MyEntity") { id: ID! ... }
確認身分：身分證！ 若漏掉 ID，用戶端會收到明顯的結構層級錯誤，而非不透明的執行時失敗。
循環 GraphQL 關係會在啟動時造成堆疊溢位異常
症狀： 當 schema.gql 定義彼此在週期中互相引用的型別（例如 Player 參考 Game，Game 參考 Player）時，DAB 會因堆疊溢位例外而當機。
原因： 結構建構器會以遞迴方式走訪所有型別參考，以產生突變輸入型別。 循環關係會導致無限遞迴，耗盡呼叫堆疊。 這是 GitHub issue #746 中追蹤的已知錯誤。
解決： 避免在 schema.gql 中使用循環型別引用。 透過移除其中一個型別的回溯參考來打破這個循環，或將關係建模為 ID（純量欄位）清單，而非巢狀物件型別。 請持續關注 GitHub issue 以獲取循環關係何時被支援的最新消息。
分割區金鑰始終是 id，自訂分割金鑰路徑不被支援
症狀： DAB 只適用於使用 /id 作為分割鍵的 Cosmos DB 容器。 容器若被其他欄位（例如 /userID 或 /category）分割，則無法被正確查詢或變異。
原因： Data API 建構器硬編碼 id 作為所有 Cosmos DB 實體的分割鍵。 無論是在 dab-config.json 還是 schema.gql 中，都無法指定自訂分割鍵路徑。 這是 GitHub issue #747 中追蹤的已知限制。
解決： 使用 DAB 時，設計新的容器，分割鍵為 /id。 對於具有不同分割鍵的現有容器，目前不支援 DAB。 請參考 GitHub issue 以獲取可配置分割區金鑰新增時間的最新資訊。
不支援查詢文件內巢狀陣列（項目內連接）
症狀： 你無法在 Cosmos DB 文件中使用 DAB 過濾或遍歷巢狀陣列中的屬性。 需要跨陣列元素進行 Cosmos DB JOIN 的查詢可能會無法返回結果或會出錯。
原因： Data API 建構器不支援 Cosmos DB 的文件內連接 （亦稱為項目內連結），而這些連接是查詢單一文件中巢狀陣列所必需的。 這是 GitHub issue #262 中追蹤的已知限制。
解決： 如果需要篩選，可以將巢狀陣列壓扁成獨立實體或子文件。 或者，在你的應用程式層中對完整文件進行後處理。 請追蹤 GitHub issue 以獲取關於文件內部連接支援何時新增的最新消息。