Recuperação de desastre

Esse conteúdo se aplica a: v4.0 (versão prévia) | Versões prévias: v3.1 (GA) v3.0 (GA) v2.1 (GA)

Ao criar um recurso do Document Intelligence no portal do Azure, você especifica uma região. Desse momento em diante, o recurso e todas as operações dele permanecem associados àquela região de servidor do Azure. É raro, mas não impossível, que um problema de rede atinja toda uma região. Se a sua solução precisa estar sempre disponível, você deve criá-la para fazer failover em outra região ou dividir a carga de trabalho entre duas ou mais regiões. Ambas as abordagens exigem pelo menos dois recursos da Informação de Documentos em diferentes regiões e a capacidade de sincronizar modelos personalizados e classificadores entre regiões.

A API de cópia habilita esse cenário, permitindo que você copie modelos personalizados e classificadores de uma conta da Informação de Documentos ou para outras, que podem existir em qualquer região geográfica com suporte. Este guia mostra como usar a API REST de cópia com cURL para modelos personalizados. Você também pode usar um serviço de solicitação HTTP para emitir as solicitações.

Observação

A partir da API 2024-07-31-preview, os modelos de classificação personalizados também dão suporte à API de cópia. Este guia usa especificamente modelos personalizados para copiar modelos. Para copiar o modelo de classificador, siga este guia.

Cenários de negócios

Se seu aplicativo ou negócio depende do uso de um modelo personalizado do Document Intelligence, recomendamos que você copie seu modelo para outra conta do Document Intelligence em outra região. Dessa forma, se ocorrer uma interrupção regional, você poderá acessar seus dados na região para onde os dados foram copiados.

Pré-requisitos

1. Dois recursos do Document Intelligence do Azure em diferentes regiões do Azure. Se você não os tiver, acesse o portal do Azure e crie um novo recurso do Document Intelligence.
2. A chave, o URL do ponto de extremidade e a ID da assinatura do seu recurso do Document Intelligence. Esses valores estão disponíveis na guia Visão geral do recurso, no portal do Azure.

Visão geral da API de cópia

O processo para copiar um modelo personalizado consiste nas seguintes etapas:

1. Primeiro, você emite uma solicitação de autorização de cópia para o recurso de destino, ou seja, o recurso que receberá o modelo copiado. Você recebe de volta o URL do modelo de destino recém-criado que receberá o modelo copiado.
2. Em seguida, você envia a solicitação de cópia para o recurso de origem, que é o recurso contendo o modelo a ser copiado com o conteúdo (autorização de cópia) retornado da chamada anterior. Você recebe de volta um URL que pode consultar para acompanhar o andamento da operação.
3. Você usa suas credenciais de recurso de origem para consultar o URL de progresso até que a operação seja bem-sucedida. Você também pode consultar a nova ID do modelo no recurso de destino para ver o status do novo modelo.

Gerar solicitação de autorização de cópia

A solicitação HTTP a seguir obtém a autorização de cópia do recurso de destino. Você precisa inserir o ponto de extremidade e a chave do seu recurso de destino como cabeçalhos.

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

Corpo da solicitação

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

Você recebe um código de resposta 200 com corpo de resposta que contém o conteúdo JSON necessário para iniciar a cópia.

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

Iniciar operação de cópia

A solicitação HTTP a seguir inicia a operação de cópia no recurso de origem. Você precisa inserir o ponto de extremidade e a chave do seu recurso de origem como o URL e cabeçalho. Observe que a URL da solicitação contém a ID do modelo de origem que você quer copiar.

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

O corpo da solicitação é a resposta da etapa anterior.

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

Você recebe uma resposta 202\Accepted com um cabeçalho Operação-Local. Esse valor é o URL que você usa para acompanhar o progresso da operação. Copie o valor em uma localização temporária para a próxima etapa.

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

Observação

A API de cópia dá suporte de maneira transparente ao recurso AEK/CMK. Isso não requer tratamento especial, mas, ao copiar algo de um recurso não criptografado para um recurso criptografado, você precisa incluir o cabeçalho da solicitação x-ms-forms-copy-degrade: true. Se esse cabeçalho não for incluído, a operação de cópia falhará com o erro DataProtectionTransformServiceError.

Acompanhar o progresso da cópia

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

Acompanhar a ID do modelo de destino

Você também pode usar a API Get model para consultar o modelo de destino a fim de acompanhar o status da operação. Chame a API usando a ID do modelo de destino copiada para baixo da resposta de Generate copy authorization request.

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

No corpo da resposta, você vê informações sobre o modelo. Verifique o status do modelo no campo "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":[]}}

Exemplo de código do cURL

Os trechos de código a seguir usam cURL para fazer chamadas à API. Você também precisa preencher as IDs de modelo e as informações de assinatura específicas para seus próprios recursos.

Gerar autorização de cópia

Solicitação

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}'
}"

Resposta bem-sucedida

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

Iniciar operação de cópia

Solicitação

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}'
}"

Resposta bem-sucedida

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

Acompanhar o andamento da operação de cópia

Você pode usar a API GET operation para listar todas as operações de modelo de documento (com sucesso, em andamento ou com falha) associadas ao seu recurso da Informação de Documentos. As informações de operação persistem apenas por 24 horas. Aqui está uma lista das operações (operationId) que podem ser retornadas:

• documentModelBuild
• documentModelCompose
• documentModelCopyTo

Acompanhar a ID do modelo de destino

Se a operação tiver sido bem-sucedida, o modelo de documento poderá ser acessado usando as APIs getModel (obter um único modelo) ou GetModels (obter uma lista de modelos).

Mensagens de código de erro comuns

Erro	Resolução
400/Solicitação inválida com "code:" "1002"	Indica erro de validação ou solicitação de cópia malformada. Problemas comuns incluem: a) conteúdo de copyAuthorization inválido ou modificado. b) Expiração do valor do token expirationDateTimeTicks (o conteúdo de copyAuthorization é válido por 24 horas). c) targetResourceRegion inválido ou sem suporte. d) Cadeia de caracteres targetResourceId inválida ou malformada.
Falha de autorização devido a solicitações de autorização ausentes ou inválidas.	Ocorre quando o conteúdo copyAuthorization ou o conteúdo é modificado na API copyAuthorization. O conteúdo precisa ser exatamente igual ao que foi retornado na chamada a copyAuthorization anterior.
Não foi possível recuperar metadados de autorização.	Indica que o conteúdo de copyAuthorization está sendo reutilizado com uma solicitação de cópia. Uma solicitação de cópia bem-sucedida não permite mais solicitações que usem o mesmo conteúdo copyAuthorization. Se ocorrer um erro separado e depois você tentar novamente a cópia com o mesmo conteúdo de autorização, esse erro será gerado. A resolução é gerar um novo conteúdo de copyAuthorization e emitir novamente a solicitação de cópia.
A solicitação de transferência de dados não é permitida, pois faz o downgrade para um esquema de proteção de dados menos seguro.	Ocorre quando você copia algo de um recurso com o AEK habilitado para um recurso sem o AEK habilitado. Para permitir a cópia do modelo criptografado para o destino como não criptografado, especifique o cabeçalho x-ms-forms-copy-degrade: true com a solicitação de cópia.
“Não foi possível buscar informações para o recurso cognitivo com a ID...”.	Indica que o recurso do Azure indicado pelo targetResourceId não é um recurso cognitivo válido ou não existe. Para resolver esse problema, verifique e emita novamente a solicitação de cópia. Verifique se o recurso é válido e existe na região especificada, como, westus2

Próximas etapas

Neste guia, você aprendeu a usar a API de cópia para fazer backup de seus modelos personalizados em um recurso secundário do Document Intelligence. Em seguida, explore os documentos de referência da API para ver o que mais você pode fazer com o Document Intelligence.

• Documentação de referência da API REST