재해 복구

이 콘텐츠의 적용 대상은 다음과 같습니다.v4.0(미리 보기) | 이전 버전:v3.1(GA)v3.0(GA)v2.1(GA)

Azure portal에서 문서 인텔리전스 리소스를 만들 때 지역을 지정합니다. 그때부터 리소스와 모든 작업이 해당 특정 Azure 서버 지역과 연결된 상태를 유지합니다. 전체 지역에 적용되는 네트워크 문제가 발생하는 것은 드물지만 불가능한 것도 아닙니다. 솔루션을 항상 사용할 수 있어야 하는 경우, 다른 지역으로 장애 조치(failover)하거나 둘 이상의 지역 간에 워크로드를 분할하도록 설계해야 합니다. 두 접근 방식 모두 서로 다른 지역에 있는 두 개 이상의 문서 인텔리전스 리소스와 지역 간에 사용자 지정 모델을 동기화하는 기능이 필요합니다.

복사 API를 사용하면 하나의 문서 인텔리전스 계정에서 사용자 지정 모델을 복사하거나 지원되는 모든 지역에 존재할 수 있는 다른 계정으로 사용자 지정 모델을 복사할 수 있으므로 이 시나리오가 가능해집니다. 이 가이드에서는 cURL과 함께 복사 REST API를 사용하는 방법을 보여 줍니다. HTTP 요청 서비스를 사용하여 요청을 실행할 수도 있습니다.

비즈니스 시나리오

앱이나 비즈니스가 문서 인텔리전스 사용자 지정 모델 사용에 의존하는 경우 모델을 다른 지역의 다른 문서 인텔리전스 계정에 복사하는 것이 좋습니다. 지역 가동 중단이 발생하는 경우 모델이 복사된 지역에 있는 모델에 액세스할 수 있습니다.

필수 조건

1. 서로 다른 Azure 지역에 있는 두 개의 문서 인텔리전스 Azure 리소스입니다. 해당 리소스가 없으면 Azure portal로 이동하여 새 문서 인텔리전스 리소스를 생성하세요.
2. 문서 인텔리전스 리소스에 대한 키, 엔드포인트 URL 및 구독 ID입니다. Azure Portal의 리소스 개요 탭에서 이러한 값을 찾을 수 있습니다.

복사 API 개요

사용자 지정 모델을 복사하는 프로세스는 다음 단계로 구성됩니다.

1. 먼저 대상 리소스, 즉 복사된 모델을 수신하는 리소스에 복사 인증 요청을 발행합니다. 복사된 모델을 수신하는 새로 생성된 대상 모델의 URL을 다시 받습니다.
2. 그런 다음, 이전 호출에서 반환된 페이로드(복사 권한 부여)를 사용하여 복사할 모델을 포함하는 리소스인 원본 리소스에 복사 요청을 보냅니다. 작업 진행률을 추적하기 위해 쿼리할 수 있는 URL을 다시 받습니다.
3. 작업이 성공할 때까지 원본 리소스 자격 증명을 사용하여 진행률 URL을 쿼리합니다. 또한 대상 리소스의 새 모델 ID를 쿼리하여 새 모델의 상태를 가져올 수도 있습니다.

복사 권한 부여 요청 생성

다음 HTTP 요청은 대상 리소스에서 복사 권한 부여를 가져옵니다. 대상 리소스의 엔드포인트와 키를 헤더로 입력해야 합니다.

POST https://<your-resource-endpoint>/documentintelligence/documentModels:authorizeCopy?api-version=2024-02-29-preview
Ocp-Apim-Subscription-Key: {<your-key>}

요청 본문

{
  "modelId": "target-model-name",
  "description": "Copied from SCUS"
}

복사를 시작하는 데 필요한 JSON 페이로드가 포함된 응답 본문과 함께 200 응답 코드를 수신합니다.

{
  "targetResourceId": "/subscriptions/{targetSub}/resourceGroups/{targetRG}/providers/Microsoft.CognitiveServices/accounts/{targetService}",
  "targetResourceRegion": "region",
  "targetModelId": "target-model-name",
  "targetModelLocation": "model path",
  "accessToken": "access token",
  "expirationDateTime": "timestamp"
}

복사 작업 시작

다음 HTTP 요청은 원본 리소스에 대한 복사 작업을 시작합니다. 원본 리소스의 엔드포인트와 키를 URL과 헤더로 입력해야 합니다. 요청 URL에는 복사하려는 원본 모델의 모델 ID가 포함되어 있습니다.

POST https://<your-resource-endpoint>/documentintelligence/documentModels/{modelId}:copyTo?api-version=2024-02-29-preview
Ocp-Apim-Subscription-Key: {<your-key>}

요청 본문은 이전 단계의 응답입니다.

{
  "targetResourceId": "/subscriptions/{targetSub}/resourceGroups/{targetRG}/providers/Microsoft.CognitiveServices/accounts/{targetService}",
  "targetResourceRegion": "region",
  "targetModelId": "target-model-name",
  "targetModelLocation": "model path",
  "accessToken": "access token",
  "expirationDateTime": "timestamp"
}

Operation-Location 헤더를 포함하는 202\Accepted 응답을 받습니다. 이 값은 작업 진행률을 추적하는 데 사용하는 URL입니다. 다음 단계를 위해 임시 위치에 복사합니다.

HTTP/1.1 202 Accepted
Operation-Location: https://<your-resource-endpoint>.cognitiveservices.azure.com/documentintelligence/operations/{operation-id}?api-version=2024-02-29-preview

참고 항목

복사 API는 AEK/CMK 기능을 투명하게 지원합니다. 이를 위해 특별한 처리가 필요하지는 않지만 암호화되지 않은 리소스를 암호화된 리소스로 복사하는 경우 요청 헤더 x-ms-forms-copy-degrade: true를 포함해야 합니다. 이 헤더가 포함되지 않은 경우 복사 작업이 실패하고 DataProtectionTransformServiceError를 반환합니다.

복사 진행률 추적

GET https://<your-resource-endpoint>.cognitiveservices.azure.com/documentintelligence/operations/{<operation-id>}?api-version=2024-02-29-preview
Ocp-Apim-Subscription-Key: {<your-key>}

대상 모델 ID 추적

또한 모델 가져오기 API를 통해 대상 모델을 쿼리하여 작업 상태를 추적할 수 있습니다. 복사 권한 부여 생성 요청 응답에서 복사한 대상 모델 ID를 사용하여 API를 호출합니다.

GET https://<your-resource-endpoint>/documentintelligence/documentModels/{modelId}?api-version=2024-02-29-preview" -H "Ocp-Apim-Subscription-Key: <your-key>

응답 본문에는 모델에 대한 정보가 표시됩니다. "status" 필드에서 모델 상태를 확인합니다.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"modelInfo":{"modelId":"33f4d42c-cd2f-4e74-b990-a1aeafab5a5d","status":"ready","createdDateTime":"2020-02-26T16:59:28Z","lastUpdatedDateTime":"2020-02-26T16:59:34Z"},"trainResult":{"trainingDocuments":[{"documentName":"0.pdf","pages":1,"errors":[],"status":"succeeded"},{"documentName":"1.pdf","pages":1,"errors":[],"status":"succeeded"},{"documentName":"2.pdf","pages":1,"errors":[],"status":"succeeded"},{"documentName":"3.pdf","pages":1,"errors":[],"status":"succeeded"},{"documentName":"4.pdf","pages":1,"errors":[],"status":"succeeded"}],"errors":[]}}

cURL 샘플 코드

다음 코드 조각은 cURL을 사용하여 API 호출을 수행합니다. 또한 자신의 리소스와 관련된 모델 ID 및 구독 정보를 입력해야 합니다.

복사 권한 부여 생성

요청

curl -i -X POST "<your-resource-endpoint>/documentintelligence/documentModels:authorizeCopy?api-version=2024-02-29-preview"
-H "Content-Type: application/json"
-H "Ocp-Apim-Subscription-Key: <YOUR-KEY>"
--data-ascii "{
  'modelId': '{modelId}',
  'description': '{description}'
}"

성공적인 응답

{
  "targetResourceId": "string",
  "targetResourceRegion": "string",
  "targetModelId": "string",
  "targetModelLocation": "string",
  "accessToken": "string",
  "expirationDateTime": "string"
}

복사 작업 시작

요청

curl -i -X POST "<your-resource-endpoint>/documentintelligence/documentModels/{modelId}:copyTo?api-version=2024-02-29-preview"
-H "Content-Type: application/json"
-H "Ocp-Apim-Subscription-Key: <YOUR-KEY>"
--data-ascii "{
  'targetResourceId': '{targetResourceId}',
  'targetResourceRegion': {targetResourceRegion}',
  'targetModelId': '{targetModelId}',
  'targetModelLocation': '{targetModelLocation}',
  'accessToken': '{accessToken}',
  'expirationDateTime': '{expirationDateTime}'
}"

성공적인 응답

HTTP/1.1 202 Accepted
Operation-Location: https://<your-resource-endpoint>.cognitiveservices.azure.com/documentintelligence/operations/{operation-id}?api-version=2024-02-29-preview

복사 작업 진행률 추적

작업 가져오기 API를 사용하면 문서 인텔리전스 리소스와 관련된 모든 문서 모델 작업(성공, 진행 중 또는 실패)을 나열할 수 있습니다. 작업 정보는 24시간 동안만 유지됩니다. 다음은 반환할 수 있는 작업(operationId)의 목록입니다.

• documentModelBuild
• documentModelCompose
• documentModelCopyTo

대상 모델 ID 추적

작업이 성공한 경우 getModel(단일 모델 가져오기) 또는 GetModels(모델 목록 가져오기) API를 사용하여 문서 모델에 액세스할 수 있습니다.

일반적인 오류 코드 메시지

오류	해결
400 / 잘못된 요청("code:" "1002")	유효성 검사 오류 또는 잘못된 형식의 복사 요청을 나타냅니다. 일반적인 문제는 다음과 같습니다. a) 잘못되었거나 수정된 copyAuthorization 페이로드. b) expirationDateTimeTicks 토큰의 만료된 값(copyAuthorization 페이로드는 24시간 동안 유효). c) 잘못되었거나 지원되지 않는 targetResourceRegion. d) 잘못되었거나 형식이 잘못된 targetResourceId 문자열.
승인 요청이 누락되거나 잘못되어 승인이 실패했습니다.	copyAuthorization 페이로드 또는 콘텐츠가 copyAuthorization API에서 수정되면 발생합니다. 페이로드가 이전 copyAuthorization 호출에서 반환된 것과 똑같은 내용인지 확인합니다.
인증 메타데이터를 검색할 수 없습니다.	copyAuthorization 페이로드가 복사 요청에 재사용되고 있음을 나타냅니다. 성공한 복사 요청은 동일한 copyAuthorization 페이로드를 사용하는 추가 요청을 허용하지 않습니다. 별도의 오류가 발생하고 나중에 동일한 인증 페이로드로 복사를 다시 시도하면 이 오류가 발생합니다. 해결 방법은 새 copyAuthorization 페이로드를 생성한 다음, 복사 요청을 다시 실행하는 것입니다.
보안 수준이 낮은 데이터 보호 체계로 다운그레이드되므로 데이터 전송 요청이 허용되지 않습니다.	AEK가 설정된 리소스와 AEK가 설정되지 않은 리소스 간에 복사하는 경우에 발생합니다. 암호화된 모델을 암호화되지 않은 모델로 대상에 복사하는 것을 허용하려면 복사 요청이 있는 x-ms-forms-copy-degrade: true 헤더를 지정합니다.
"ID의 인지 리소스에 대한 정보를 가져올 수 없습니다.”	targetResourceId로 표시된 Azure 리소스가 유효한 Cognitive 리소스가 아니거나 존재하지 않음을 나타냅니다. 이 문제를 해결하려면 복사 요청을 확인하고 다시 실행하세요. 리소스가 올바르며 지정된 지역(예: westus2)에 있는지 확인

다음 단계

이 가이드에서는 Copy API를 사용하여 사용자 지정 모델을 보조 문서 인텔리전스 리소스에 백업하는 방법을 배웠습니다. 다음으로 API 참조 문서를 탐색하여 문서 인텔리전스로 수행할 수 있는 다른 작업을 알아보세요.

• REST API 참조 설명서