Haveriberedskap

Det här innehållet gäller för: v4.0 (förhandsversion) | Tidigare versioner: v3.1 (GA) v3.0 (GA) v2.1 (GA)

När du skapar en dokumentinformationsresurs i Azure-portalen anger du en region. Från och med då förblir din resurs och alla dess åtgärder associerade med den specifika Azure-serverregionen. Det är ovanligt, men inte omöjligt, att stöta på ett nätverksproblem som drabbar en hel region. Om din lösning alltid måste vara tillgänglig bör du ställa in den på redundansväxling till en annan region eller dela upp arbetsbelastningen mellan två eller flera regioner. Båda metoderna kräver minst två dokumentinformationsresurser i olika regioner och möjligheten att synkronisera anpassade modeller mellan regioner.

Kopierings-API:et aktiverar det här scenariot genom att låta dig kopiera anpassade modeller från ett dokumentinformationskonto eller till andra, som kan finnas i valfri geografisk region som stöds. Den här guiden visar hur du använder COPY REST API med cURL. Du kan också använda en HTTP-begärandetjänst för att utfärda begäranden.

Affärsscenarier

Om din app eller ditt företag är beroende av användningen av en anpassad dokumentinformationsmodell rekommenderar vi att du kopierar din modell till ett annat dokumentinformationskonto i en annan region. Om ett regionalt avbrott inträffar kan du komma åt din modell i den region där den kopierades.

Förutsättningar

1. Två Document Intelligence Azure-resurser i olika Azure-regioner. Om du inte har dem går du till Azure-portalen och skapar en ny dokumentinformationsresurs.
2. Nyckeln, slutpunkts-URL:en och prenumerations-ID:t för dokumentinformationsresursen. Du hittar dessa värden på resursens översiktsflik i Azure-portalen.

Översikt över kopierings-API

Processen för att kopiera en anpassad modell består av följande steg:

1. Först utfärdar du en begäran om kopieringsauktorisering till målresursen, dvs. den resurs som tar emot den kopierade modellen. Du får tillbaka URL:en för den nyligen skapade målmodellen som tar emot den kopierade modellen.
2. Sedan skickar du kopieringsbegäran till källresursen – resursen som innehåller modellen som ska kopieras med nyttolasten (kopieringsauktorisering) som returnerades från föregående anrop. Du får tillbaka en URL som du kan fråga för att spåra förloppet för åtgärden.
3. Du använder dina källresursautentiseringsuppgifter för att köra frågor mot förlopps-URL:en tills åtgärden har slutförts. Du kan också fråga det nya modell-ID:t i målresursen för att få status för den nya modellen.

Generera begäran om kopieringsauktorisering

Följande HTTP-begäran hämtar kopieringsauktorisering från målresursen. Du måste ange slutpunkten och nyckeln för målresursen som rubriker.

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

Begärandetext

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

Du får en 200 svarskod med svarstexten som innehåller den JSON-nyttolast som krävs för att initiera kopian.

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

Starta kopieringsåtgärden

Följande HTTP-begäran startar kopieringsåtgärden på källresursen. Du måste ange slutpunkten och nyckeln för källresursen som URL och rubrik. Observera att begärande-URL:en innehåller modell-ID:t för den källmodell som du vill kopiera.

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

Brödtexten i din begäran är svaret från föregående steg.

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

Du får ett 202\Accepted svar med rubriken Åtgärd-plats. Det här värdet är den URL som du använder för att spåra förloppet för åtgärden. Kopiera den till en tillfällig plats för nästa steg.

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

Kommentar

Kopierings-API:et stöder transparent funktionen AEK/CMK . Detta kräver ingen särskild behandling, men observera att om du kopierar mellan en okrypterad resurs till en krypterad resurs måste du inkludera begärandehuvudet x-ms-forms-copy-degrade: true. Om det här huvudet inte ingår misslyckas kopieringsåtgärden och returnerar en DataProtectionTransformServiceError.

Spåra kopieringsstatus

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

Spåra målmodell-ID:t

Du kan också använda API:et Hämta modell för att spåra åtgärdens status genom att fråga målmodellen. Anropa API:et med hjälp av målmodell-ID:t som du kopierade från svaret generera kopieringsauktoriseringsbegäran .

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

I svarstexten ser du information om modellen. "status" Kontrollera status för modellen i fältet.

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

Följande kodfragment använder cURL för att göra API-anrop. Du måste också fylla i modell-ID:t och prenumerationsinformationen som är specifik för dina egna resurser.

Generera kopieringsauktorisering

Begär

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

Lyckat svar

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

Påbörja kopieringsåtgärden

Begär

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

Lyckat svar

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

Spåra kopieringsåtgärdens förlopp

Du kan använda API:et För att hämta åtgärd för att lista alla dokumentmodellåtgärder (lyckades, pågår eller misslyckades) som är associerade med dokumentinformationsresursen. Åtgärdsinformationen finns bara kvar i 24 timmar. Här är en lista över de åtgärder (operationId) som kan returneras:

• documentModelBuild
• documentModelCompose
• documentModelCopyTo

Spåra målmodell-ID:t

Om åtgärden lyckades kan dokumentmodellen nås med hjälp av API:erna getModel (hämta en enda modell) eller GetModels (hämta en lista över modeller).

Vanliga felmeddelanden

Fel	Åtgärd
400/Felaktig begäran med "code:" "1002"	Anger valideringsfel eller felaktig kopieringsbegäran. Vanliga problem är: a) Ogiltig eller ändrad copyAuthorization nyttolast. b) Utgånget värde för expirationDateTimeTicks token (copyAuthorization nyttolasten är giltig i 24 timmar). c) Ogiltigt eller stöds targetResourceRegioninte . d) Ogiltig eller felaktigt formaterad targetResourceId sträng.
Auktoriseringsfel på grund av saknade eller ogiltiga auktoriseringsanspråk.	Inträffar när copyAuthorization nyttolasten eller innehållet ändras från API:et copyAuthorization . Kontrollera att nyttolasten är exakt samma innehåll som returnerades från det tidigare copyAuthorization anropet.
Det gick inte att hämta auktoriseringsmetadata.	Anger att nyttolasten copyAuthorization återanvänds med en kopieringsbegäran. En kopieringsbegäran som lyckas tillåter inte ytterligare begäranden som använder samma copyAuthorization nyttolast. Om du skapar ett separat fel och senare försöker kopiera igen med samma auktoriseringsnyttolast genereras det här felet. Lösningen är att generera en ny copyAuthorization nyttolast och sedan återutge kopieringsbegäran.
Dataöverföringsbegäran tillåts inte eftersom den nedgraderas till ett mindre säkert dataskyddsschema.	Inträffar vid kopiering mellan en AEK aktiverad resurs till en resurs som inte AEK är aktiverad. Om du vill tillåta kopiering av krypterad modell till målet som okrypterad anger du x-ms-forms-copy-degrade: true sidhuvud med kopieringsbegäran.
"Det gick inte att hämta information för kognitiv resurs med ID...".	Anger att Azure-resursen targetResourceId som anges av inte är en giltig kognitiv resurs eller inte finns. Lös problemet genom att verifiera och återutge kopieringsbegäran. Kontrollera att resursen är giltig och finns i den angivna regionen, till exempel westus2

Nästa steg

I den här guiden har du lärt dig hur du använder API:et Kopiera för att säkerhetskopiera dina anpassade modeller till en sekundär dokumentinformationsresurs. Utforska sedan API-referensdokumenten för att se vad mer du kan göra med Dokumentinformation.

• Referensdokumentation för REST API