Azure Cosmos DB 문제 해결

데이터 API 작성기에서 일반적인 Azure Cosmos DB 에뮬레이터, 연결 및 스키마 구성 문제에 대한 솔루션입니다.

자주 묻는 질문

DAB의 Azure Cosmos DB 지원은 무엇인가요?

Data API Builder는 Azure Cosmos DB를 NoSQL 백 엔드로 지원합니다. DAB는 Azure Cosmos DB .NET SDK를 사용하여 Cosmos DB에 연결하고 엔터티를 GraphQL 형식으로 노출합니다. Cosmos DB에 대한 REST 지원을 사용할 수 없습니다. 모든 쿼리는 GraphQL 엔드포인트를 통해 제공됩니다.

DAB는 Cosmos DB에서 어떤 API를 사용하나요?

DAB는 NoSQL API(이전의 SQL API)용 Azure Cosmos DB를 사용합니다. MongoDB, Gremlin 및 Table과 같은 다른 Cosmos DB API는 지원되지 않습니다. Azure Cosmos DB for NoSQL API를 사용하여 Cosmos DB 계정이 생성되었는지 확인합니다.

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 에뮬레이터를 시작합니다. 에뮬레이터의 데이터 탐색기 페이지에 표시되는 https://localhost:8081/_explorer/index.html에서 AccountEndpoint=https://localhost:8081/를 사용하는 연결 문자열과 올바른 에뮬레이터 키를 확인합니다.

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 재정의는 로컬 개발에 권장되는 해결 방법입니다.

OBO(On-Behalf-Of) 인증이 지원되지 않습니다.

증상: Azure Cosmos DB 지원 DAB 인스턴스에 대한 OBO(On-Behalf-Of) 인증 구성이 실패하거나 토큰이 예상대로 전달되지 않습니다.

원인: OBO 인증은 현재 SQL Server 및 Azure SQL에 대해서만 지원됩니다. Azure Cosmos DB에 대한 지원은 아직 구현되지 않았습니다. 이는 GitHub 문제 #3159에서 추적되는 알려진 제한 사항입니다.

해상도: Cosmos DB 계정 키 또는 관리 ID와 같은 지원되는 인증 방법을 사용합니다. OBO 지원이 SQL Server가 아닌 데이터베이스로 확장되는 경우 업데이트에 대한 GitHub 문제를 따릅니다.

Cosmos DB에서 필터 내의 GraphQL이 실패함

증상: Cosmos DB로 지원되는 엔터티에 대해 In 연산자를 사용하는 GraphQL 쿼리는 introspection을 통해 스키마에 나타나더라도, 알 수 없는 프레디케이트 연산 IN을 빌드할 수 없어 런타임에 실패합니다.

원인: in 연산자는 IdFilterInput 및 StringFilterInput에 대해 생성된 GraphQL 스키마에 노출되지만 기본 Cosmos DB 필터 변환 논리는 이를 구현하지 않습니다. 스키마와 쿼리 실행기 간의 이러한 불일치는 GitHub 문제 #3061에서 추적된 알려진 버그입니다.

해결책: GraphQL 쿼리를 Cosmos DB 엔터티에 사용할 때는 in 연산자를 사용하지 마십시오. 대신 다음 해결 방법 중 하나를 사용합니다.

고정된 작은 값 목록에서 여러 개의 식이나 + q로 대체하십시오.
알려진 ID 목록으로 쿼리할 때 여러 포인트 읽기 별칭(item_by_pk)을 사용합니다.
더 광범위한 결과 집합을 검색한 후 클라이언트 쪽을 필터링합니다.

Cosmos DB에는 집계가 지원되지 않습니다.

증상: Cosmos DB 지원 엔터티에 대한 GraphQL 집계 쿼리(예: count, sum 또는 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 내에서는 해결 방법이 없습니다. 가능하면 단일 파티션 키를 사용하도록 컨테이너를 다시 디자인합니다. 데이터 모델에서 계층적 파티션 키가 필요한 경우 다중 해시 지원이 추가되는 경우 업데이트에 대한 GitHub 문제를 따릅니다.

다중 해시 파티션 키는 지원되지 않습니다.

증상: 계층적(다중 해시) 파티션 키를 사용하는 Cosmos DB 컨테이너에 대한 변경이 실패하고 파티션 키 정의에 지정된 'kind' 값 'MultiHash'가 잘못되었습니다. '해시' 파티션 유형을 선택하세요.

원인: 데이터 API 작성기에서는 Azure Cosmos DB에 대한 단일 값 해시 파티션 키만 지원합니다. 계층적 파티션 키(MultiHash)로 구성된 컨테이너(예: /TenantId, /EntityType, /EntityId)는 지원되지 않습니다. 이는 GitHub 문제 #1733에서 추적되는 알려진 제한 사항입니다.

해상도: 현재 DAB 내에서는 해결 방법이 없습니다. 대신 단일 해시 파티션 키가 있는 컨테이너를 사용합니다. 계층적 분할이 필요한 경우 컨테이너를 재구성하거나 MultiHash 파티션 키 지원이 추가되는 경우 업데이트에 대한 GitHub 문제를 따르는 것이 좋습니다.

Cosmos DB에서 여러 돌연변이가 원자성이 아닙니다.

증상: Cosmos DB 엔터티에 대한 단일 요청에서 여러 GraphQL 돌연변이가 전송되는 경우 한 돌연변이의 실패가 다른 돌연변이를 롤백하지 않습니다. 부분 쓰기가 발생할 수 있습니다.

원인: 데이터 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의 형식 이름이 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 유효성 검사를 실행하여 다른 구성 오류를 잡습니다.

GraphQL 스키마 파일의 열거형 형식으로 인해 스키마 빌드 실패가 발생합니다.

증상: DAB가 HotChocolate.SchemaException으로 시작하지 못했습니다. 형식 참조를 확인할 수 없습니다. ... Cosmos DB schema.gql 파일이 개체 형식 필드에 사용되는 GraphQL num 형식을 정의하는 경우 OrderByInput 오류가 발생합니다.

원인: 데이터 API 작성기에서는 현재 Cosmos DB 스키마 파일에서 GraphQL 열거형 형식을 지원하지 않습니다. 열거형이 필드 형식으로 사용되는 경우 스키마 작성기는 해당 OrderByInput 형식을 생성할 수 없으며 처리되지 않은 예외를 throw합니다. 이는 GitHub 문제 #748에서 추적되는 알려진 제한 사항입니다.

해상도: schema.gql에서 열거형 필드를 해당 스칼라 등가물(예: 사용자 지정 열거형 형식 대신 String 사용)으로 바꿉니다. DAB 스키마 정의가 아닌 애플리케이션 계층에 열거형 유효성 검사를 적용합니다.

GraphQL 스키마의 열거형 형식으로 인해 시작 시 DAB가 실패합니다.

증상: Cosmos DB GraphQL 스키마 파일이 모델에 사용되는 열거형 형식을 정의할 때 형식 참조 '없음: FooOrderByInput'을 확인할 수 없음과 같은 HotChocolate.SchemaException 오류로 DAB가 시작되지 않습니다.

원인: 데이터 API 작성기 스키마 작성기에서 schema.gql에 정의된 GraphQL 열거형 형식을 올바르게 처리하지 않습니다. 열거형이 모델의 필드 형식으로 참조되면 내부 OrderByInput 형식 생성이 이를 해결하지 못하고 스키마 초기화가 중단됩니다. 이는 GitHub 문제 #748에서 추적되는 알려진 제한 사항입니다.

해결책: Cosmos DB 엔터티에 대해 schema.gql에서 GraphQL enum 형식을 정의하지 마십시오. 해결 방법으로 열거형 필드를 String으로 바꾸고 애플리케이션 계층에서 유효한 값을 적용합니다. 열거형 지원이 추가되는 시점의 업데이트를 위한 GitHub 이슈를 팔로우하세요.

Cosmos DB 엔터티에는 필드 매핑(별칭)이 지원되지 않습니다.

증상: dab-config.json 파일에서 Cosmos DB 엔터티에 대해 정의된 매핑 섹션이 효과가 없으며, 구성된 별칭 대신 원래 필드 이름이 GraphQL 스키마에 여전히 노출됩니다.

원인: API의 다른 필드 이름 아래에 데이터베이스 열 이름을 노출할 수 있는 매핑 기능은 관계형 데이터베이스에 대해서만 구현됩니다. Cosmos DB 엔터티는 현재 필드 매핑을 지원하지 않습니다. 이는 GitHub 문제 #1512에서 추적되는 알려진 제한 사항입니다.

해상도: 필드 이름은 Cosmos DB 문서에 표시된 대로 정확하게 사용합니다. 별칭이 필요한 경우 클라이언트 애플리케이션 계층에 적용합니다. Cosmos DB에 대한 매핑 지원이 추가될 때의 변경 사항은 GitHub 이슈를 통해 확인하세요.

GraphQL 변형 변수는 값 대신 저장된 변수 이름이 확인되지 않습니다.

증상: 변수를 사용하는 GraphQL 변형(예: createExample(item: { id: , name: }))은 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가 스키마에서 nullable로 정의되면 런타임에 변경 만들기가 실패합니다.

증상: 만들기 변형은 스키마가 유효한 것처럼 보이는 경우에도 런타임 오류를 반환합니다. ID 필드가 제공되지 않았거나 null이므로 오류가 발생합니다.

원인: Cosmos DB는 모든 문서에 대한 ID 필드가 필요하며 파티션 키의 일부로 사용합니다. schema.gql이 id를 nullable로 선언하는 경우(예: 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이 주기에서 서로를 참조하는 형식을 정의할 때(예: 플레이어가 게임을 참조하고 게임이 플레이어를 참조하는 경우) 스택 오버플로 예외로 시작 시 DAB가 충돌합니다.

원인: 스키마 작성기에서는 모든 형식 참조를 재귀적으로 안내하여 변형 입력 형식을 생성합니다. 순환 관계로 인해 무한 재귀가 발생하고 호출 스택이 소진됩니다. 이는 GitHub 문제 #746에서 추적된 알려진 버그입니다.

해상도: schema.gql에서 순환 형식 참조를 사용하지 않습니다. 형식 중 하나에서 백 참조를 제거하여 주기를 중단하거나 관계를 중첩된 개체 형식이 아닌 ID(스칼라 필드) 목록으로 모델링합니다. 순환 관계가 지원되는 경우에 대한 업데이트는 GitHub 문제를 따릅니다.

파티션 키는 항상 id이며, 커스텀 파티션 키 경로는 지원되지 않습니다.

증상: DAB는 /id를 파티션 키로 사용하는 Cosmos DB 컨테이너에서만 작동합니다. 다른 필드(예: /userId 또는 /category)로 분할된 컨테이너는 올바르게 쿼리하거나 변경할 수 없습니다.

원인: 데이터 API 작성기 하드 코드 ID는 모든 Cosmos DB 엔터티의 파티션 키로 지정됩니다. dab-config.json 또는 schema.gql에서 사용자 지정 파티션 키 경로를 지정할 수 있는 방법은 없습니다. 이는 GitHub 문제 #747에서 추적되는 알려진 제한 사항입니다.

해상도: DAB를 사용할 때 /id를 파티션 키로 사용하여 새 컨테이너를 디자인합니다. 다른 파티션 키를 사용하는 기존 컨테이너의 경우 DAB는 현재 지원되지 않습니다. 구성 가능한 파티션 키가 추가되는 경우 업데이트에 대한 GitHub 문제를 따릅니다.

문서 내에서 중첩된 배열 쿼리(항목 내 조인)는 지원되지 않습니다.

증상: DAB를 사용하여 Cosmos DB 문서 내에서 중첩된 배열 속성을 필터링하거나 트래버스할 수 없습니다. 배열 요소 간에 Cosmos DB JOIN이 필요한 쿼리는 결과나 오류를 반환하지 않습니다.

원인: 데이터 API 작성기에서는 단일 문서 내에서 중첩된 배열을 쿼리하는 데 필요한 Cosmos DB 문서 내 조 인(항목 내 조인이라고도 함)을 지원하지 않습니다. 이는 GitHub 문제 #262에서 추적되는 알려진 제한 사항입니다.

해상도: 콘텐츠를 필터링해야 하는 경우 중첩된 배열을 별도의 엔터티 또는 자식 문서로 평면화합니다. 또는 애플리케이션 계층에서 전체 문서의 사후 처리를 수행합니다. 문서 내 조인 지원이 추가될 경우 업데이트는 GitHub 이슈를 확인하세요.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-04-01