Ripristino di emergenza

Questo contenuto si applica a:v4.0 (anteprima) | Versioni precedenti:v3.1 (GA)v3.0 (GA)v2.1 (GA)

Quando si crea una risorsa di Document Intelligence nella portale di Azure, si specifica un'area. Da quel momento, la risorsa e tutte le relative operazioni rimangono associate a tale area di Azure specifica. È raro, ma non impossibile, riscontrare un problema di rete che interessa un'intera area. Se una soluzione deve essere sempre disponibile, è necessario progettarla in modo che ne venga eseguito il failover in un'altra area o che il carico di lavoro venga suddiviso tra due o più aree. Entrambi gli approcci richiedono almeno due risorse di Document Intelligence in aree diverse e la possibilità di sincronizzare modelli personalizzati tra aree.

L'API Copia abilita questo scenario consentendo di copiare modelli personalizzati da un account di Document Intelligence o in altri, che possono esistere in qualsiasi area geografica supportata. Questa guida illustra come usare l'API REST Copia con cURL. È anche possibile usare un servizio di richiesta HTTP per inviare le richieste.

Scenari aziendali

Se l'app o l'azienda dipende dall'uso di un modello personalizzato di Document Intelligence, è consigliabile copiare il modello in un altro account di Intelligence documenti in un'altra area. Se si verifica un'interruzione del servizio nell'area, è quindi possibile accedere al modello nell'area in cui è stato copiato.

Prerequisiti

1. Due risorse di Azure di Document Intelligence in aree di Azure diverse. Se non sono disponibili, passare alla portale di Azure e creare una nuova risorsa di Intelligence per i documenti.
2. Chiave, URL endpoint e ID sottoscrizione per la risorsa di Document Intelligence. È possibile trovare questi valori nella scheda Panoramica della risorsa nel portale di Azure.

Panoramica dell'API Copia

Il processo per copiare un modello personalizzato prevede i passaggi seguenti:

1. Prima di tutto si esegue una richiesta di autorizzazione di copia alla risorsa di destinazione, ovvero la risorsa che riceve il modello copiato. Viene restituito l'URL del modello di destinazione appena creato che riceve il modello copiato.
2. Successivamente si invia la richiesta di copia alla risorsa di origine, ovvero la risorsa che contiene il modello da copiare con il payload (autorizzazione di copia) restituito dalla chiamata precedente. Viene restituito un URL su cui è possibile eseguire una query per tenere traccia dello stato di avanzamento dell'operazione.
3. Usare le credenziali della risorsa di origine per eseguire una query sull'URL di stato fino a quando l'operazione non riesce. È anche possibile eseguire una query sul nuovo ID modello nella risorsa di destinazione per ottenere lo stato del nuovo modello.

Generare una richiesta di autorizzazione per la copia

La richiesta HTTP seguente ottiene l'autorizzazione per la copia dalla risorsa di destinazione. È necessario immettere l'endpoint e la chiave della risorsa di destinazione come intestazioni.

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

Testo della richiesta

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

Si riceve un 200 codice di risposta con il corpo della risposta che contiene il payload JSON necessario per avviare 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"
}

Avviare l'operazione di copia

La richiesta HTTP seguente avvia l'operazione di copia nella risorsa di origine. È necessario immettere l'endpoint e la chiave della risorsa di origine come URL e intestazione. Si noti che l'URL della richiesta contiene l'ID modello del modello di origine da copiare.

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

Il corpo della richiesta è costituito dalla risposta del passaggio precedente.

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

Si riceve una 202\Accepted risposta con un'intestazione Operation-Location. Questo valore è l'URL usato per tenere traccia dello stato di avanzamento dell'operazione. Copiarlo in una posizione temporanea per il passaggio successivo.

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

L'API Copia supporta in modo trasparente la funzionalità Chiave di crittografia dell'account/Chiave gestita dal cliente. Questa funzionalità non richiede alcun trattamento speciale, ma si noti che se si esegue la copia tra una risorsa non crittografata in una risorsa crittografata, è necessario includere l'intestazione della richiesta x-ms-forms-copy-degrade: true. Se questa intestazione non è inclusa, l'operazione di copia avrà esito negativo e restituirà un errore DataProtectionTransformServiceError.

Monitorare lo stato della copia

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

Monitorare l'ID modello di destinazione

È anche possibile usare l'API Get model per monitorare lo stato dell'operazione eseguendo una query sul modello di destinazione. Chiamare l'API usando l'ID modello di destinazione copiato dalla risposta Genera una richiesta di autorizzazione per la copia.

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

Nel corpo della risposta sono visualizzate informazioni sul modello. Controllare il campo "status" per lo stato del modello.

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

Codice di esempio cURL

I frammenti di codice seguenti usano cURL per effettuare chiamate API. È anche necessario compilare gli ID modello e le informazioni sulle sottoscrizioni specifiche per le proprie risorse.

Generare l'autorizzazione per la copia

Richiedi

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

Risposta con esito positivo

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

Avviare l'operazione di copia

Richiedi

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

Risposta con esito positivo

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

Monitorare lo stato dell'operazione di copia

È possibile usare l'API Get operation per elencare tutte le operazioni del modello di documento (riuscite, in corso o non riuscite) associate alla risorsa di Intelligence documenti. Le informazioni sulle operazioni vengono conservate solo per 24 ore. Ecco un elenco delle operazioni (operationId) che possono essere restituite:

• documentModelBuild
• documentModelCompose
• documentModelCopyTo

Monitorare l'ID modello di destinazione

Se l'operazione ha esito positivo, è possibile accedere al modello di documento usando le API getModel (recupera un singolo modello) o GetModels (recupera un elenco di modelli).

Messaggi e codici errore comuni

Error	Risoluzione
400/Richiesta non valida con "code:" "1002"	Indica un errore di convalida o una richiesta di copia non valida. I problemi comuni includono: a) Payload copyAuthorization non valido o modificato. b) Valore scaduto per il token expirationDateTimeTicks (il payload copyAuthorization è valido per 24 ore). c) Area targetResourceRegion non valida o non supportata. d) Stringa targetResourceId non valida.
Errore di autorizzazione a causa di attestazioni di autorizzazione mancanti o non valide.	Si verifica quando il payload o il copyAuthorization contenuto viene modificato dall'API copyAuthorization . Assicurarsi che il payload includa lo stesso contenuto esatto restituito dalla chiamata copyAuthorization precedente.
Impossibile recuperare i metadati di autorizzazione.	Indica che il payload copyAuthorization viene riutilizzato con una richiesta di copia. Una richiesta di copia che ha esito positivo non consente ulteriori richieste che usano lo stesso copyAuthorization payload. Se si genera un errore separato e successivamente si ritenta la copia con lo stesso payload di autorizzazione, viene generato questo errore. Per risolvere il problema è necessario generare un nuovo payload copyAuthorization e quindi eseguire nuovamente la richiesta di copia.
La richiesta di trasferimento dei dati non è consentita perché effettua il downgrade a uno schema di protezione dei dati meno sicuro.	Si verifica durante la copia tra una risorsa abilitata per AEK a una risorsa non abilitata per AEK. Per consentire la copia del modello crittografato nella destinazione come modello non crittografato, specificare l'intestazione x-ms-forms-copy-degrade: true con la richiesta di copia.
"Non è stato possibile recuperare informazioni per la risorsa Servizi cognitivi con ID...".	Indica che la risorsa di Azure indicata da targetResourceId non è una risorsa Servizi cognitivi valida o non esiste. Per risolvere questo problema, verificare e riemettere nuovamente la richiesta di copia. Assicurarsi che la risorsa sia valida ed esista nell'area specificata, ad esempio westus2

Passaggi successivi

In questa guida si è appreso come usare l'API Copia per eseguire il backup dei modelli personalizzati in una risorsa secondaria di Document Intelligence. Esplorare quindi la documentazione di riferimento sulle API per visualizzare le altre operazioni che è possibile eseguire con Document Intelligence.

• Documentazione di riferimento delle API REST