Recuperação após desastre

Este conteúdo aplica-se a: v4.0 (GA) | Versões anteriores: v3.1 (GA) v3.0 (GA) v2.1 (GA)

Ao criar um recurso de Inteligência Documental no portal do Azure, você especifica uma região. A partir de então, seu recurso e todas as suas operações permanecem associados a essa região específica do servidor do Azure. É raro, mas não impossível, encontrar um problema de rede que atinge uma região inteira. Se a sua solução precisa estar sempre disponível, deve projetá-la para failover noutra região ou dividir a carga de trabalho entre duas ou mais regiões. Ambas as abordagens exigem pelo menos dois recursos de Document Intelligence em regiões diferentes e a capacidade de sincronizar modelos e classificadores personalizados entre regiões.

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

Nota

O modelo de classificação personalizada da API 2024-11-30 (GA) suporta a API de cópia. Este guia usa especificamente modelos personalizados para copiar modelos. Para a cópia do modelo do classificador, siga o guia do classificador personalizado.

Cenários de negócio

Se seu aplicativo ou empresa depender do uso de um modelo personalizado de Document Intelligence, recomendamos que você copie seu modelo para outra conta de Document Intelligence em outra região. Se ocorrer uma interrupção regional, você poderá acessar seu modelo na região onde ele foi copiado.

Pré-requisitos

1. Dois recursos do Azure Document Intelligence em regiões diferentes do Azure. Se não os tiver, aceda ao portal do Azure e crie um novo recurso de Inteligência Documental.
2. A chave, o URL do ponto de extremidade e o ID da assinatura do seu recurso de Document Intelligence. Você pode encontrar esses valores na guia Visão geral do recurso no portal do Azure.

Copiar visão geral da API

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 recebe o modelo copiado. Você recebe de volta a URL do modelo de destino recém-criado que recebe o modelo copiado.
2. Em seguida, você envia a solicitação de cópia para o recurso de origem — o recurso que contém o modelo a ser copiado com a carga (autorização de cópia) retornada da chamada anterior. Você recebe de volta uma URL que pode consultar para acompanhar o progresso da operação.
3. Você usa suas credenciais de recurso de origem para consultar a URL de progresso até que a operação seja bem-sucedida. Você também pode consultar a ID do novo modelo no recurso de destino para obter o status do novo modelo.

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

A solicitação HTTP a seguir obtém autorização de cópia do recurso de destino. Você precisa inserir o ponto de extremidade e a chave do 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 do pedido

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

Você recebe um código de 200 resposta com o corpo da resposta que contém a carga JSON necessária 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 url e cabeçalho. Observe que a URL da solicitação contém a ID do modelo de origem que você deseja copiar.

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

O corpo do seu pedido é a resposta do passo 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 202\Accepted resposta com um cabeçalho Operation-Location. Esse valor é a URL que você usa para acompanhar o progresso da operação. Copie-o para um local temporário 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

Nota

A API de cópia suporta de forma transparente o recurso AEK/CMK . Isso não requer nenhum tratamento especial, mas observe que, se você estiver copiando entre um recurso não criptografado para um recurso criptografado, precisará incluir o cabeçalho x-ms-forms-copy-degrade: trueda solicitação. Se esse cabeçalho não estiver incluído, a operação de cópia falhará e retornará um DataProtectionTransformServiceErrorarquivo .

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

Rastreie o ID do modelo de destino

Você também pode usar a Get model API para controlar o status da operação consultando o modelo de destino. Chame a API usando o ID do modelo de destino que você copiou da Generate copy authorization resposta da solicitação .

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 no "status" campo o status do modelo.

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":[]}}

Código de exemplo cURL

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

Gerar autorização de cópia

Pedir

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

Pedir

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

Acompanhe o progresso da operação de cópia

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

• documentModelBuild
• documentModelCompose
• documentModelCopyTo

Rastreie o ID do modelo de destino

Se a operação foi bem-sucedida, o modelo de documento pode 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 / Mau Pedido com "code:" "1002"	Indica erro de validação ou solicitação de cópia mal formada. Os problemas comuns incluem: a) Carga útil inválida ou modificada copyAuthorization . b) Valor expirado para expirationDateTimeTicks token (copyAuthorization a carga útil é válida por 24 horas). c) Inválido ou não suportado targetResourceRegion. d) String inválida ou malformada targetResourceId .
Falha de autorização devido a reclamações de autorização ausentes ou inválidas.	Ocorre quando a carga útil ou o copyAuthorization conteúdo é modificado a copyAuthorization partir da API. Certifique-se de que a carga útil é o mesmo conteúdo exato que foi retornado da chamada anterior copyAuthorization .
Não foi possível recuperar metadados de autorização.	Indica que a copyAuthorization carga está sendo reutilizada com uma solicitação de cópia. Uma solicitação de cópia bem-sucedida não permite outras solicitações que usem a mesma copyAuthorization carga útil. Se você gerar um erro separado e mais tarde tentar novamente a cópia com a mesma carga útil de autorização, esse erro será gerado. A resolução é gerar uma nova copyAuthorization carga útil e, em seguida, reemitir a solicitação de cópia.
A solicitação de transferência de dados não é permitida, pois faz downgrade para um esquema de proteção de dados menos seguro.	Ocorre ao copiar entre um AEK recurso habilitado para um recurso não AEK habilitado. Para permitir a cópia do modelo criptografado para o destino como não criptografado, especifique x-ms-forms-copy-degrade: true o cabeçalho com a solicitação de cópia.
"Não foi possível buscar informações para o recurso cognitivo com ID...".	Indica que o targetResourceId recurso do Azure indicado pelo não é um recurso cognitivo válido ou não existe. Para resolver esse problema, verifique e reemita a solicitação de cópia. Verifique se o recurso é válido e existe na região especificada, como, por exemplo, westus2

Próximos passos

Neste guia, você aprendeu como usar a API de cópia para fazer backup de seus modelos personalizados em um recurso secundário de 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