Recuperación ante desastres

Este contenido se aplica a: v3.1 (GA) | Última versión: v4.0 (versión preliminar) | Versiones anteriores: v3.0 v2.1

Cuando se crea un recurso de Documento de inteligencia en Azure Portal, se especifica una región. Desde ese momento, el recurso y todas sus operaciones permanecen asociadas a esa región concreta del servidor de Azure. No suele ser habitual, aunque tampoco imposible, encontrar un problema de red que afecte a toda una región. Si la solución debe estar siempre disponible, debe diseñarla para que conmute por error en otra región o divida la carga de trabajo entre dos o más regiones. Ambos enfoques requieren al menos dos recursos de Documento de inteligencia en distintas regiones y la capacidad de sincronizar modelos y clasificadores personalizados entre regiones.

La API de copia admite este escenario, ya que permite copiar modelos y clasificadores personalizados de una cuenta de Documento de inteligencia o en otras, que pueden existir en cualquier región geográfica compatible. En esta guía se muestra cómo usar la API REST de copia con cURL para modelos personalizados. También puede usar un servicio de solicitud HTTP para emitir las solicitudes.

Nota:

A partir de la API 2024-07-31-preview, los modelos de clasificación personalizados también admiten la API de copia. En esta guía se usan específicamente modelos personalizados para copiar modelos. Para la copia del modelo clasificador, siga esta guía.

Escenarios empresariales

Si su aplicación o empresa dependen del uso de un modelo personalizado de Documento de inteligencia, se recomienda copiar el modelo a otra cuenta de Documento de inteligencia en otra región. Si se produce una interrupción regional, puede acceder al modelo en la región donde se copió.

Requisitos previos

1. Dos recursos de Documento de inteligencia de Azure en diferentes regiones de Azure. Si no los tiene, vaya a Azure Portal y cree un nuevo recurso de Documento de inteligencia.
2. La clave, la dirección URL del punto de conexión y el identificador de suscripción para el recurso de Documento de inteligencia. Puede encontrar estos valores en la pestaña Información general del recurso en Azure Portal.

Introducción a la API de copia

El proceso de copia de un modelo personalizado consta de los siguientes pasos:

1. En primer lugar, emita una solicitud de autorización de copia en el recurso de destino; es decir, el recurso que recibe el modelo copiado. Obtendrá la dirección URL del modelo de destino que se acaba de crear, que recibe el modelo copiado.
2. A continuación, envíe la solicitud de copia al recurso de origen: el recurso que contiene el modelo que se va a copiar con la carga (autorización de copia) devuelta desde la llamada anterior. Obtendrá una dirección URL que puede consultar para realizar el seguimiento del progreso de la operación.
3. Usará las credenciales del recurso de origen para consultar la dirección URL de progreso hasta que la operación finalice correctamente. También puede consultar el nuevo identificador del modelo en el recurso de destino para obtener el estado del nuevo modelo.

Generación de la solicitud de autorización de copia

La siguiente solicitud HTTP obtiene la autorización de copia del recurso de destino. Debe especificar el punto de conexión y la clave del recurso de destino como encabezados.

POST https://{TARGET_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/documentModels:authorizeCopy?api-version=2024-02-29-preview
Ocp-Apim-Subscription-Key: {TARGET_FORM_RECOGNIZER_RESOURCE_KEY}

Cuerpo de la solicitud

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

Obtendrá un código de respuesta 200 con el cuerpo de la respuesta que contiene la carga JSON necesaria para iniciar la copia.

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

Inicio de la operación de copia

La siguiente solicitud HTTP inicia la operación de copia en el recurso de origen. Debe especificar el punto de conexión y la clave del recurso de origen como URL y encabezado. Observe que la dirección URL de la solicitud contiene el identificador de modelo del modelo de origen que desea copiar.

POST {{source-endpoint}}formrecognizer/documentModels/{model-to-be-copied}:copyTo?api-version=2023-07-31
Ocp-Apim-Subscription-Key: {SOURCE_FORM_RECOGNIZER_RESOURCE_KEY}

El cuerpo de la solicitud será la respuesta del paso 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"
}

Recibe una respuesta 202\Accepted con un encabezado Operation-Location. Este valor es la dirección URL que se usa para realizar el seguimiento del progreso de la operación. Cópielo en una ubicación temporal para el siguiente paso.

HTTP/1.1 202 Accepted
Operation-Location: https://{source-resource}.cognitiveservices.azure.com/formrecognizer/operations/{operation-id}?api-version=2023-07-31

Nota

La API de copia admite de forma transparente la característica AEK/CMK. No se requiere ningún tratamiento especial, pero tenga en cuenta que si va a copiar de un recurso sin cifrar a un recurso cifrado, debe incluir el encabezado de solicitud x-ms-forms-copy-degrade: true. Si no se incluye este encabezado, se producirá un error en la operación de copia y se devolverá el error DataProtectionTransformServiceError.

Seguimiento del progreso de la copia

GET https://{source-resource}.cognitiveservices.azure.com/formrecognizer/operations/{operation-id}?api-version=2023-07-31
Ocp-Apim-Subscription-Key: {SOURCE_FORM_RECOGNIZER_RESOURCE_KEY}

Seguimiento del id. del modelo de destino

También puede usar la API GET model para realizar un seguimiento del estado de la operación consultando el modelo de destino. Llame a la API mediante el id. del modelo de destino que copió de la respuesta a la solicitud Generate Copy authorization.

GET https://{YOUR-ENDPOINT}/formrecognizer/documentModels/{modelId}?api-version=2023-07-31" -H "Ocp-Apim-Subscription-Key: <YOUR-KEY>

En el cuerpo de la respuesta, verá información sobre el modelo. Compruebe el estado del modelo en el 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":[]}}

Código de ejemplo de cURL

En los fragmentos de código siguientes se usa cURL para realizar las llamadas API. También debe rellenar los identificadores de modelo y la información de suscripción correspondientes a sus propios recursos.

Generación de autorización de copia

Solicitud

curl -i -X POST "{YOUR-ENDPOINT}formrecognizer/documentModels:authorizeCopy?api-version=2023-07-31"
-H "Content-Type: application/json"
-H "Ocp-Apim-Subscription-Key: <YOUR-KEY>"
--data-ascii "{
  'modelId': '{modelId}',
  'description': '{description}'
}"

Respuesta correcta

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

Comienzo de la operación de copia

Solicitud

curl -i -X POST "{YOUR-ENDPOINT}/formrecognizer/documentModels/{modelId}:copyTo?api-version=2023-07-31"
-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}'
}"

Respuesta correcta

HTTP/1.1 202 Accepted
Operation-Location: https://{source-resource}.cognitiveservices.azure.com/formrecognizer/operations/{operation-id}?api-version=2023-07-31

Seguimiento del progreso de la operación de copia

Puede usar la API GET operation para enumerar todas las operaciones del modelo de documento (correctas, en curso o con errores) asociadas al recurso de Documento de inteligencia. La información de la operación solo se conserva durante 24 horas. Esta es una lista de las operaciones (operationId) que se pueden devolver:

• documentModelBuild
• documentModelCompose
• documentModelCopyTo

Seguimiento del id. del modelo de destino

Si la operación se realizó correctamente, se puede acceder al modelo de documento mediante las API getModel (obtener un único modelo) o GetModels (obtener una lista de modelos).

Mensajes comunes de código de error

Error	Resolución
400/Solicitud incorrecta con "code:" "1002"	Indica un error de validación o una solicitud de copia con formato incorrecto. Entre los problemas habituales se incluyen: a) Una carga copyAuthorization no válida o modificada. b) Un valor expirado para el token expirationDateTimeTicks (la carga copyAuthorization es válida durante 24 horas). c) targetResourceRegion no válido o no admitido. d) Cadena targetResourceId no válida o con el formato incorrecto.
Error de autorización debido a notificaciones de autorización que faltan o no son válidas.	Se produce cuando se modifica la carga o el contenido de copyAuthorization de la API de copyAuthorization. Asegúrese de que la carga tenga exactamente el mismo contenido que devolvió la llamada copyAuthorization anterior.
No se pudieron recuperar los metadatos de autorización.	Indica que la carga de copyAuthorization se está usando de nuevo con una solicitud de copia. Una solicitud de copia que se realiza correctamente no permite que otras solicitudes usen la misma carga de copyAuthorization. Si genera un error independiente y, posteriormente, intenta de nuevo la copia con la misma carga de autorización, se genera este error. La resolución consiste en generar una nueva carga de copyAuthorization y, a continuación, volver a emitir la solicitud de copia.
No se permite la solicitud de transferencia de datos, ya que cambia a una versión anterior de un esquema de protección de datos menos seguro.	Se produce cuando se realiza una copia entre un recurso con AEK habilitado y un recurso que no tiene AEK habilitado. Para permitir que se copie el modelo de cifrado al destino como uno sin cifrar, especifique el encabezado x-ms-forms-copy-degrade: true con la solicitud de copia.
"No se pudo obtener información del recurso de Cognitive con el id...".	Indica que el recurso de Azure señalado por targetResourceId no es un recurso de Cognitive válido o no existe. Para resolver este problema, compruebe y vuelva a emitir la solicitud de copia. Asegúrese de que el recurso sea válido y exista en la región especificada, como westus2

Pasos siguientes

En esta guía, ha obtenido información sobre cómo usar la API de copia para realizar una copia de seguridad de los modelos personalizados en un recurso de Documento de inteligencia secundario. A continuación, consulte los documentos de referencia de la API para ver qué más puede hacer con Documento de inteligencia.

• Documentación de referencia de API REST