Récupération d’urgence

Ce contenu s’applique à : v4.0 (préversion) | Versions précédentes : v3.1 (GA) v3.0 (GA) v2.1 (GA)

Quand vous créez une ressource Intelligence documentaire dans le portail Azure, vous spécifiez une région. Ensuite, votre ressource et toutes ses opérations restent associées à cette région de serveur Azure. Il est rare, mais pas impossible, de rencontrer un problème réseau qui touche une région entière. Si votre solution doit toujours être disponible, vous devez la concevoir pour qu’elle bascule vers une autre région ou qu’elle répartisse la charge de travail entre deux régions ou plus. Les deux approches nécessitent au moins deux ressources Intelligence documentaire dans différentes régions et la capacité à synchroniser des classifieurs et des modèles personnalisés entre les régions.

L’API de copie autorise ce scénario en vous permettant de copier des classifieurs et des modèles personnalisés d’un compte Intelligence documentaire vers d’autres, qui peuvent exister dans n’importe quelle région géographique prise en charge. Ce guide montre comment utiliser l’API REST de copie avec cURL pour des modèles personnalisés. Vous pouvez également utiliser un service de requête HTTP pour émettre les requêtes.

Remarque

À compter de l’API 2024-07-31-preview, les modèles de classification personnalisés prennent également en charge l’API de copie. Ce guide utilise spécifiquement des modèles personnalisés pour copier des modèles. Pour la copie de modèle de classifieur, suivez ce guide.

Scénarios d’entreprise

Si votre application ou votre entreprise dépend de l’utilisation d’un modèle personnalisé Intelligence documentaire, nous vous recommandons de copier votre modèle vers un autre compte Intelligence documentaire dans une autre région. En cas de panne régionale, vous pouvez alors accéder à votre modèle dans la région où il a été copié.

Prérequis

1. Deux ressources Azure Intelligence documentaire dans différentes régions Azure. Si vous n’en avez pas, accédez au Portail Azure et créez une nouvelle ressource Intelligence documentaire.
2. La clé, l’URL de point de terminaison et l’ID d’abonnement de votre ressource Intelligence documentaire. Ces valeurs se trouvent sous l’onglet Vue d’ensemble de la ressource sur le Portail Azure.

Vue d’ensemble de l’API de copie

Le processus de copie d’un modèle personnalisé se compose des étapes suivantes :

1. Tout d'abord, vous émettez une demande d'autorisation de copie à la ressource cible, c'est-à-dire la ressource qui reçoit le modèle copié. Vous recevez en retour l’URL du modèle cible qui vient d’être créé, qui reçoit le modèle copié.
2. Ensuite, vous envoyez la demande de copie à la ressource source : la ressource qui contient le modèle à copier avec la charge utile (autorisation de copie) retournée par l’appel précédent. Vous recevez une URL que vous pouvez interroger pour suivre la progression de l’opération.
3. Vous utilisez vos informations d’identification de ressource source pour interroger l’URL de progression jusqu’à ce que l’opération soit réussie. Vous pouvez également interroger le nouvel ID de modèle dans la ressource cible pour obtenir l’état du nouveau modèle.

Générer la demande d’autorisation de copie

La requête HTTP suivante obtient l’autorisation de copie de votre ressource cible. Vous devez entrer le point de terminaison et la clé de votre ressource cible en tant qu’en-têtes.

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

Corps de la demande

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

Vous obtenez un code de réponse 200 avec le corps de la réponse qui contient la charge utile JSON requise pour lancer la copie.

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

Démarrer l’opération de copie

La requête HTTP suivante démarre l’opération de copie sur la ressource source. Vous devez entrer le point de terminaison et la clé de votre ressource source en tant qu’URL et en-tête. Notez que l’URL de la demande contient l’ID du modèle source que vous souhaitez copier.

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

Le corps de votre requête est la réponse de l’étape précédente.

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

Vous recevez une réponse 202\Accepted avec un en-tête Operation-Location. Cette valeur est l’URL que vous utilisez pour suivre la progression de l’opération. Copiez-la dans un emplacement temporaire pour l’étape suivante.

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

Notes

L’API Copy prend en charge de manière transparente la fonctionnalité AEK/CMK. L’opération ne nécessite aucun traitement spécial, mais notez que si vous copiez une ressource non chiffrée dans une ressource chiffrée, vous devez inclure l’en-tête de demande x-ms-forms-copy-degrade: true. Si cet en-tête n’est pas inclus, l’opération de copie échoue et retourne une erreur DataProtectionTransformServiceError.

Suivre la progression de la copie

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

Suivre l’ID de modèle cible

Vous pouvez également utiliser l’API Get model pour suivre l’état de l’opération en interrogeant le modèle cible. Appelez l’API à l’aide de l’ID de modèle cible que vous avez copié à partir de la réponse de la requête Generate copy authorization.

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

Dans le corps de la réponse, vous voyez des informations sur le modèle. Vérifiez l’état du modèle dans le champ "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":[]}}

Exemple de code cURL

Les extraits de code suivants utilisent cURL pour effectuer des appels d’API. Vous devez toujours renseigner les ID de modèle et les informations d’abonnement propres à vos ressources.

Générer l’autorisation de copie

Requête

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

Réponse correcte

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

Commencer l’opération de copie

Requête

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

Réponse correcte

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

Suivre la progression de l’opération de copie

Vous pouvez utiliser l’API Obtenir les opérations pour répertorier toutes les opérations de modèle de document (réussies, en cours ou ayant échoué) associées à votre ressource Intelligence documentaire. Les informations d’opération sont conservées uniquement pendant 24 heures. Voici une liste des opérations (operationId) qui peuvent être retournées :

• documentModelBuild
• documentModelCompose
• documentModelCopyTo

Suivre l’ID de modèle cible

Si l’opération a réussi, le modèle de document est accessible à l’aide des API getModel (obtenir un modèle unique) ou GetModels (obtenir une liste de modèles).

Messages de code d’erreur courants

Error	Résolution
400 / Requête incorrecte avec "code:" "1002"	Indique une erreur de validation ou un format de requête de copie incorrect. Les problèmes courants sont les suivants : a) charge utile copyAuthorization non valide ou modifiée. b) valeur expirée pour le jeton expirationDateTimeTicks (la charge utile copyAuthorization est valide pendant 24 heures). c) valeur targetResourceRegion non valide ou non prise en charge. d) chaîne targetResourceId non valide ou incorrecte.
Échec d’autorisation en raison de revendications d’autorisation manquantes ou non valides.	Cette erreur s’affiche si le contenu ou la charge utile copyAuthorization varie par rapport à l’API copyAuthorization. Vérifiez que la charge utile est exactement identique à celle retournée par l’appel copyAuthorization précédent.
Impossible de récupérer les métadonnées d’autorisation.	Indique que la charge utile copyAuthorization est réutilisée avec une demande de copie. Une demande de copie qui aboutit n’autorise aucune autre demande utilisant la même charge utile copyAuthorization. Si une erreur se produit et que vous relancez ultérieurement la copie avec la même charge utile d’autorisation, cette erreur est générée. La solution consiste à générer une nouvelle charge utile copyAuthorization puis à émettre à nouveau la demande de copie.
La demande de transfert de données n’est pas autorisée, car elle passe à un schéma de protection des données moins sécurisé.	Se produit lors de la copie d’une ressource AEK activée vers une ressource AEK non activée. Pour autoriser la copie d’un modèle chiffré vers la cible en tant que modèle non chiffré, spécifiez l’en-tête x-ms-forms-copy-degrade: true dans la requête de copie.
"Couldn’t fetch information for Cognitive resource with ID...".	Indique que la ressource Azure spécifiée par targetResourceId n’est pas une ressource Cognitive valide ou n’existe pas. Pour résoudre ce problème, vérifiez et réexécutez la requête de copie. Ensure the resource is valid and exists in the specified region, such as, westus2

Étapes suivantes

Dans ce guide, vous avez appris à utiliser l’API de copie pour sauvegarder vos modèles personnalisés dans une ressource Intelligence documentaire secondaire. Explorez à présent la documentation de référence sur les API pour voir ce que vous pouvez faire d’autre avec Intelligence documentaire.

• Documentation de référence sur l’API REST