Herstel na noodgeval

Deze inhoud is van toepassing op: v3.1 (GA) | Nieuwste versie: v4.0 (preview) | Vorige versies: v3.0 v2.1

Wanneer u een Document Intelligence-resource maakt in Azure Portal, geeft u een regio op. Vanaf dat tijdstip blijven uw resource en alle bijbehorende bewerkingen gekoppeld aan die specifieke Azure-serverregio. Het is zeldzaam, maar niet onmogelijk, om een netwerkprobleem te krijgen dat een hele regio raakt. Als uw oplossing altijd beschikbaar moet zijn, moet u deze ontwerpen om een failover uit te voeren in een andere regio of om de workload tussen twee of meer regio's te splitsen. Beide benaderingen vereisen ten minste twee Document Intelligence-resources in verschillende regio's en de mogelijkheid om aangepaste modellen en classificaties te synchroniseren tussen regio's.

Met de copy-API kunt u dit scenario inschakelen door aangepaste modellen en classificaties te kopiëren van één Document Intelligence-account of naar andere, die in elke ondersteunde geografische regio kunnen bestaan. Deze handleiding laat zien hoe u de Copy REST API gebruikt met cURL voor aangepaste modellen. U kunt ook een HTTP-aanvraagservice gebruiken om de aanvragen uit te geven.

Notitie

Vanaf de 2024-07-31-preview API ondersteunen aangepaste clasification-modellen ook de Copy-API. In deze handleiding wordt specifiek gebruikgemaakt van aangepaste modellen om modellen te kopiëren. Volg deze handleiding voor het kopiëren van classificatiemodellen.

Bedrijfsscenario's

Als uw app of bedrijf afhankelijk is van het gebruik van een aangepast Document Intelligence-model, raden we u aan uw model te kopiëren naar een ander Document Intelligence-account in een andere regio. Als er een regionale storing optreedt, hebt u toegang tot uw model in de regio waar het is gekopieerd.

Vereisten

1. Twee Document Intelligence Azure-resources in verschillende Azure-regio's. Als u deze niet hebt, gaat u naar Azure Portal en maakt u een nieuwe Document Intelligence-resource.
2. De sleutel, eindpunt-URL en abonnements-id voor uw Document Intelligence-resource. U vindt deze waarden op het tabblad Overzicht van de resource in Azure Portal.

Api-overzicht kopiëren

Het proces voor het kopiëren van een aangepast model bestaat uit de volgende stappen:

1. Eerst geeft u een kopieerautorisatieaanvraag uit aan de doelresource. Dat wil gezegd, de resource die het gekopieerde model ontvangt. U ontvangt de URL van het zojuist gemaakte doelmodel dat het gekopieerde model ontvangt.
2. Vervolgens verzendt u de kopieeraanvraag naar de bronresource: de resource die het model bevat dat moet worden gekopieerd met de nettolading (autorisatie voor kopiëren) die is geretourneerd uit de vorige aanroep. U ontvangt een URL die u kunt opvragen om de voortgang van de bewerking bij te houden.
3. U gebruikt de bronresourcereferenties om een query uit te voeren op de voortgangs-URL totdat de bewerking is geslaagd. U kunt ook een query uitvoeren op de nieuwe model-id in de doelresource om de status van het nieuwe model op te halen.

Autorisatieaanvraag voor kopiëren genereren

Met de volgende HTTP-aanvraag wordt kopieerautorisatie van uw doelresource opgehaald. U moet het eindpunt en de sleutel van uw doelresource invoeren als headers.

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}

Aanvraagtekst

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

U ontvangt een 200 antwoordcode met de antwoordtekst die de JSON-nettolading bevat die nodig is om de kopie te initiëren.

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

Kopieerbewerking starten

Met de volgende HTTP-aanvraag wordt de kopieerbewerking voor de bronresource gestart. U moet het eindpunt en de sleutel van uw bronresource invoeren als url en header. U ziet dat de aanvraag-URL de model-id bevat van het bronmodel dat u wilt kopiëren.

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

De hoofdtekst van uw aanvraag is het antwoord van de vorige stap.

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

U ontvangt een 202\Accepted antwoord met een operation-location-header. Deze waarde is de URL die u gebruikt om de voortgang van de bewerking bij te houden. Kopieer deze naar een tijdelijke locatie voor de volgende stap.

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

Notitie

De Copy-API biedt transparante ondersteuning voor de functie AEK/CMK . Dit vereist geen speciale behandeling, maar houd er rekening mee dat als u kopieert tussen een niet-versleutelde resource naar een versleutelde resource, u de aanvraagheader x-ms-forms-copy-degrade: truemoet opnemen. Als deze header niet is opgenomen, mislukt de kopieerbewerking en retourneert u een DataProtectionTransformServiceError.

Voortgang van kopiëren bijhouden

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}

De doelmodel-id bijhouden

U kunt de GET model API ook gebruiken om de status van de bewerking bij te houden door een query uit te voeren op het doelmodel. Roep de API aan met behulp van de doelmodel-id die u uit het Generate Copy authorization aanvraagantwoord hebt gekopieerd.

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

In de hoofdtekst van het antwoord ziet u informatie over het model. Controleer het "status" veld op de status van het model.

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

cURL-voorbeeldcode

De volgende codefragmenten gebruiken cURL om API-aanroepen te maken. U moet ook de model-id's en abonnementsgegevens invullen die specifiek zijn voor uw eigen resources.

Autorisatie voor kopiëren genereren

Aanvragen

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

Geslaagde reactie

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

Bewerking Kopiëren starten

Aanvragen

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

Geslaagde reactie

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

Voortgang van kopieerbewerking bijhouden

U kunt de GET operation API gebruiken om alle documentmodelbewerkingen (geslaagd, uitgevoerd of mislukt) weer te geven die zijn gekoppeld aan uw Document Intelligence-resource. Bewerkingsgegevens blijven slechts 24 uur bestaan. Hier volgt een lijst met de bewerkingen (operationId) die kunnen worden geretourneerd:

• documentModelBuild
• documentModelCompose
• documentModelCopyTo

De doelmodel-id bijhouden

Als de bewerking is geslaagd, kan het documentmodel worden geopend met behulp van het getModel (één model ophalen) of GetModels -API's (een lijst met modellen ophalen).

Veelvoorkomende foutberichten

Error	Oplossing
400 / Ongeldige aanvraag met "code:" "1002"	Geeft een validatiefout of ongeldig gevormde kopieaanvraag aan. Veelvoorkomende problemen zijn: a) Ongeldige of gewijzigde copyAuthorization nettolading. b) Verlopen waarde voor expirationDateTimeTicks token (copyAuthorization nettolading is 24 uur geldig). c) Ongeldig of niet ondersteund targetResourceRegion. d) Ongeldige of ongeldige targetResourceId tekenreeks.
Autorisatiefout vanwege ontbrekende of ongeldige autorisatieclaims.	Treedt op wanneer de copyAuthorization nettolading of inhoud wordt gewijzigd vanuit de copyAuthorization API. Zorg ervoor dat de nettolading dezelfde exacte inhoud is die is geretourneerd uit de eerdere copyAuthorization aanroep.
Kan geen autorisatiemetagegevens ophalen.	Geeft aan dat de copyAuthorization nettolading opnieuw wordt gebruikt met een kopieaanvraag. Een kopieeraanvraag die slaagt, staat geen verdere aanvragen toe die dezelfde copyAuthorization nettolading gebruiken. Als u een afzonderlijke fout genereert en u de kopie later opnieuw probeert uit te voeren met dezelfde autorisatiepayload, wordt deze fout gegenereerd. De oplossing is om een nieuwe copyAuthorization nettolading te genereren en vervolgens de kopieeraanvraag opnieuw uit te voeren.
De aanvraag voor gegevensoverdracht is niet toegestaan omdat deze downgradet naar een minder veilig schema voor gegevensbeveiliging.	Treedt op bij het kopiëren tussen een AEK ingeschakelde resource naar een niet-ingeschakelde AEK resource. Als u het versleutelde model naar het doel wilt kopiëren als niet-versleuteld, geeft u x-ms-forms-copy-degrade: true de header op met de kopieeraanvraag.
'Kan geen informatie ophalen voor cognitive resource met id...'.	Geeft aan dat de Azure-resource die wordt aangegeven door de targetResourceId resource geen geldige Cognitive-resource is of niet bestaat. U kunt dit probleem oplossen door de kopieeraanvraag te verifiëren en opnieuw uit te voeren. Zorg ervoor dat de resource geldig is en bestaat in de opgegeven regio, zoals westus2

Volgende stappen

In deze handleiding hebt u geleerd hoe u de Copy-API gebruikt om een back-up te maken van uw aangepaste modellen naar een secundaire Document Intelligence-resource. Bekijk vervolgens de API-referentiedocumenten om te zien wat u nog meer kunt doen met Document Intelligence.

• REST API-referentiedocumentatie