다음을 통해 공유

Azure Data Factory 및 Azure Synapse에서 Azure Cosmos DB 커넥터 문제 해결

  • 아티클

적용 대상: Azure Data Factory Azure Synapse Analytics

팁

기업용 올인원 분석 솔루션인 Microsoft Fabric의 Data Factory를 사용해 보세요. Microsoft Fabric은 데이터 이동부터 데이터 과학, 실시간 분석, 비즈니스 인텔리전스 및 보고에 이르기까지 모든 것을 다룹니다. 무료로 새 평가판을 시작하는 방법을 알아봅니다!

이 문서에서는 Azure Data Factory 및 Azure Synapse의 Azure Cosmos DB 및 Azure Cosmos DB for NoSQL 커넥터와 관련된 일반적인 문제를 해결하기 위한 제안 사항을 제공합니다.

오류 메시지: 요청 크기가 너무 큽니다.

  • 증상: 기본 쓰기 일괄 처리 크기를 사용하여 Azure Cosmos DB로 데이터를 복사할 때 다음과 같은 오류가 표시됩니다. Request size is too large.

  • 원인: Azure Cosmos DB에서는 단일 요청의 크기가 2MB로 제한됩니다. 수식은 요청 크기 = 단일 문서 크기 * 쓰기 일괄 처리 크기입니다. 문서 크기가 큰 경우 기본 동작으로 인해 요청 크기가 너무 커집니다.

  • 해결 방법:
    쓰기 일괄 처리 크기를 조정할 수 있습니다. 복사 작업 싱크에서 쓰기 일괄 처리 크기 값을 줄입니다(기본값은 10000).
    쓰기 일괄 처리 크기 값을 1로 줄여도 작동하지 않으면 Azure Cosmos DB SQL API를 V2에서 V3으로 변경합니다. 이 구성을 완료하려면 다음 두 가지 옵션이 있습니다.

    • 옵션 1: 인증 유형을 서비스 주체, 시스템 할당 관리 ID 또는 사용자 할당 관리 ID로 변경합니다.
    • 옵션 2: 계정 키 인증을 계속 사용하려면 다음 단계를 따릅니다.

      1. Azure Cosmos DB for NoSQL로 연결된 서비스를 만듭니다.

      2. 다음 템플릿을 사용하여 연결된 서비스를 업데이트합니다.

        {
  "name": "<CosmosDbV3>",
  "type": "Microsoft.DataFactory/factories/linkedservices",
  "properties": {
    "annotations": [],
    "type": "CosmosDb",
    "typeProperties": {
      "useV3": true,
      "accountEndpoint": "<account endpoint>",
      "database": "<database name>",
      "accountKey": {
        "type": "SecureString",
        "value": "<account key>"
      }
    }
  }
}

오류 메시지: 고유 인덱스 제약 조건 위반

  • 증상: Azure Cosmos DB로 데이터를 복사할 때 다음과 같은 오류가 표시됩니다.

    Message=Partition range id 0 | Failed to import mini-batch. Exception was Message: {"Errors":["Encountered exception while executing function. Exception = Error: {\"Errors\":[\"Unique index constraint violation.\"]}...

  • 원인: 가능한 원인은 두 가지입니다.

    • 원인 1: 쓰기 동작으로 Insert를 사용한 경우, 이 오류는 원본 데이터에 ID가 동일한 행 또는 개체가 있음을 의미합니다.
    • 원인 2: 쓰기 동작으로 Upsert를 사용했고 컨테이너에 대해 다른 고유 키를 설정한 경우, 이 오류는 원본 데이터에 ID는 서로 다르지만 정의된 고유 키에 대해 값이 같은 행 또는 개체가 있음을 의미합니다.

  • 해결 방법:

    • 원인 1의 경우 쓰기 동작으로 Upsert를 설정합니다.
    • 원인 2의 경우 각 문서의 정의된 고유 키 값이 서로 다른지 확인합니다.

오류 메시지: 요청 비율이 높습니다.

  • 증상: Azure Cosmos DB로 데이터를 복사할 때 다음과 같은 오류가 표시됩니다.

    Type=Microsoft.Azure.Documents.DocumentClientException, Message=Message: {"Errors":["Request rate is large"]}

  • 원인: 사용된 RU(요청 단위)의 개수가 Azure Cosmos DB에 구성된 사용 가능한 RU의 개수보다 큽니다. Azure Cosmos DB가 RU를 계산하는 방법을 알아보려면 Azure Cosmos DB의 요청 단위를 참조하세요.

  • 해결 방법: 다음 두 가지 방법 중 하나를 시도해 봅니다.

    • Azure Cosmos DB에서 ‘컨테이너 RU’의 개수를 늘립니다. 이 솔루션을 사용하면 복사 작업 성능이 개선되지만 Azure Cosmos DB에서 더 많은 비용이 발생합니다.
    • writeBatchSize를 더 작은 값으로 줄이고(예: 1000) parallelCopies를 더 작은 값으로 줄입니다(예: 1). 이 솔루션을 사용하면 복사 실행 성능이 줄어들지만 Azure Cosmos DB에서 더 많은 비용이 발생하지 않습니다.

열 매핑에서 열이 누락됨

  • 증상: Azure Cosmos DB에 대해 열 매핑을 위한 스키마를 가져올 때 일부 열이 누락됩니다.

  • 원인: Azure Data Factory 및 Synapse 파이프라인은 처음 10개의 Azure Cosmos DB 문서에서 스키마를 유추합니다. 일부 문서 열 또는 속성이 값을 포함하지 않을 경우 스키마를 감지하지 못하여 스키마가 표시되지 않습니다.

  • 해결 방법: 다음 코드에 나와 있는 것처럼 쿼리를 수정하여 결과 세트에 열 값이 빈 값으로 표시되도록 할 수 있습니다. (처음 10개의 문서에서 impossible 열이 누락되었다고 가정합니다.) 또는 매핑을 위한 열을 수동으로 추가할 수 있습니다.

    select c.company, c.category, c.comments, (c.impossible??'') as impossible from c

오류 메시지: 읽기 권한자의 GuidRepresentation은 CSharpLegacy입니다.

  • 증상: Azure Cosmos DB MongoAPI 또는 MongoDB에서 UUID(Universally Unique Identifier) 필드가 있는 데이터를 복사할 때 다음과 같은 오류가 표시됩니다.

    Failed to read data via MongoDB client., Source=Microsoft.DataTransfer.Runtime.MongoDbV2Connector,Type=System.FormatException, Message=The GuidRepresentation for the reader is CSharpLegacy which requires the binary sub type to be UuidLegacy not UuidStandard.,Source=MongoDB.Bson,’“,

  • 원인: BSON(이진 JSON)에서 UUID를 표현하는 방법에는 UuidStardard와 UuidLegacy, 이렇게 두 가지가 있습니다. 기본적으로 UuidLegacy는 데이터를 읽는 데 사용됩니다. MongoDB의 UUID 데이터가 UuidStandard인 경우 오류가 발생합니다.

  • 해결 방법: MongoDB 연결 문자열에서 uuidRepresentation=standard 옵션을 추가합니다. 자세한 내용은 MongoDB 연결 문자열을 참조하세요.

오류 코드: CosmosDbSqlApiOperationFailed

  • 메시지: CosmosDbSqlApi operation Failed. ErrorMessage: %msg;.

  • 원인: CosmosDbSqlApi 작업에서 문제가 발생했습니다. 이는 특히 NoSQL 커넥터용 Azure Cosmos DB에 적용됩니다.

  • 권장 사항: 오류 세부 정보를 확인하려면 Azure Cosmos DB 도움말 문서를 참조하세요. 추가 도움이 필요한 경우 Azure Cosmos DB 팀으로 문의하세요.

오류 코드: CosmosDbSqlApiPartitionKeyExceedStorage

  • 메시지: The size of data each logical partition can store is limited, current partitioning design and workload failed to store more than the allowed amount of data for a given partition key value.

  • 원인: 각 논리 파티션의 데이터 크기가 제한되어 있고 파티션 키가 논리 파티션의 최대 크기에 도달했습니다.

  • 권장 사항: Azure Cosmos DB 파티션 디자인을 확인합니다. 자세한 내용은 논리 파티션을 참조하세요.

관련 콘텐츠

자세한 문제 해결 도움말은 다음 리소스를 참조하세요.