Zotavení po havárii

Tento obsah se vztahuje na: v4.0 (GA) | Předchozí verze: v3.1 (GA) v3.0 (GA) v2.1 (GA)

Při vytváření prostředku Document Intelligence na webu Azure Portal zadáte oblast. Od tého dne zůstane váš prostředek a všechny jeho operace přidružené k dané konkrétní oblasti serveru Azure. Je vzácné, ale ne nemožné, aby se vyskytl problém se sítí, který zasáhne celou oblast. Pokud musí být vaše řešení vždy k dispozici, měli byste jej navrhnout tak, aby bylo možné buď převzít služby při selhání do jiné oblasti, nebo rozdělit pracovní zátěž mezi dvě či více oblastí. Oba přístupy vyžadují alespoň dva prostředky Document Intelligence v různých oblastech a schopnost synchronizovat vlastní modely a klasifikátory napříč oblastmi.

Rozhraní API pro kopírování umožňuje tento scénář tím, že umožňuje kopírovat vlastní modely a klasifikátory z jednoho účtu Document Intelligence nebo do jiných, které mohou existovat v libovolné podporované geografické oblasti. V této příručce se dozvíte, jak používat rozhraní REST API pro kopírování s cURL pro vlastní modely. K vydání požadavků můžete také použít službu požadavku HTTP.

Poznámka:

Vlastní klasifikační model rozhraní API 2024-11-30 (GA) podporuje rozhraní API pro kopírování. Tato příručka konkrétně používá vlastní modely ke kopírování modelů. V případě kopírování klasifikátoru postupujte podle pokynů k trénování vlastního průvodce klasifikátorem.

Obchodní scénáře

Pokud vaše aplikace nebo firma závisí na použití vlastního modelu Document Intelligence, doporučujeme model zkopírovat do jiného účtu Document Intelligence v jiné oblasti. Pokud dojde k výpadku oblasti, můžete k modelu přistupovat v oblasti, ve které byl zkopírovaný.

Požadavky

1. Dva prostředky Azure Document Intelligence v různých oblastech Azure Pokud je nemáte, přejděte na web Azure Portal a vytvořte nový prostředek Document Intelligence.
2. Klíč, adresa URL koncového bodu a ID předplatného vašeho prostředku Document Intelligence. Tyto hodnoty najdete na kartě Přehled prostředku na webu Azure Portal.

Přehled rozhraní API pro kopírování

Proces kopírování vlastního modelu se skládá z následujících kroků:

1. Nejprve vydáte žádost o autorizaci kopírování cílovému prostředku – to znamená prostředek, který obdrží zkopírovaný model. Obdržíte zpět adresu URL nově vytvořeného cílového modelu, která obdrží zkopírovaný model.
2. Dále odešlete požadavek na kopírování do zdrojového prostředku – prostředek obsahující model, který se má zkopírovat s datovou částí (autorizací kopírování) vrácenou z předchozího volání. Obdržíte zpět adresu URL, na kterou můžete dotazovat, abyste mohli sledovat průběh operace.
3. Přihlašovací údaje ke zdrojovému prostředku slouží k dotazování na adresu URL průběhu, dokud nebude operace úspěšná. Můžete také zadat dotaz na nové ID modelu v cílovém prostředku, abyste získali stav nového modelu.

Generování žádosti o autorizaci kopírování

Následující požadavek HTTP získá autorizaci kopírování z cílového prostředku. Jako hlavičky musíte zadat koncový bod a klíč cílového prostředku.

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

Text požadavku

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

Obdržíte 200 kód odpovědi s textem odpovědi, který obsahuje datovou část JSON potřebnou k zahájení kopírování.

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

Spuštění operace kopírování

Následující požadavek HTTP spustí operaci kopírování zdrojového prostředku. Jako adresu URL a hlavičku musíte zadat koncový bod a klíč zdrojového prostředku. Všimněte si, že adresa URL požadavku obsahuje ID modelu zdrojového modelu, který chcete zkopírovat.

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

Text vaší žádosti je odpověď z předchozího kroku.

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

Obdržíte odpověď s hlavičkou 202\Accepted Operation-Location. Tato hodnota je adresa URL, kterou používáte ke sledování průběhu operace. Zkopírujte ho do dočasného umístění pro další krok.

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

Poznámka:

Rozhraní API pro kopírování transparentně podporuje funkci AEK/CMK . To nevyžaduje žádné zvláštní zacházení, ale mějte na paměti, že pokud kopírujete mezi nešifrovaným prostředkem na šifrovaný prostředek, musíte zahrnout hlavičku x-ms-forms-copy-degrade: truepožadavku . Pokud tato hlavička není zahrnuta, operace kopírování selže a vrátí hodnotu DataProtectionTransformServiceError.

Sledování průběhu kopírování

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

Sledování ID cílového modelu

Pomocí rozhraní API můžete také Get model sledovat stav operace dotazováním cílového modelu. Volání rozhraní API pomocí ID cílového modelu, které jste zkopírovali z Generate copy authorization odpovědi požadavku .

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

V těle odpovědi se zobrazí informace o modelu. "status" Zkontrolujte stav modelu v poli.

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

Ukázkový kód cURL

Následující fragmenty kódu používají cURL k volání rozhraní API. Musíte také vyplnit ID modelu a informace o předplatném specifické pro vaše vlastní prostředky.

Vygenerovat autorizaci kopírování

Požádat

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

Úspěšná odpověď

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

Zahájení operace kopírování

Požádat

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

Úspěšná odpověď

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

Sledování průběhu operace kopírování

Pomocí rozhraní API operace GET můžete zobrazit seznam všech operací modelu dokumentu (úspěšných, probíhajících nebo neúspěšných) přidružených k vašemu prostředku Document Intelligence. Informace o operaci se uchovávají pouze po dobu 24 hodin. Tady je seznam operací (operationId), které se dají vrátit:

• documentModelBuild
• documentModelCompose
• documentModelCopyTo

Sledování ID cílového modelu

Pokud byla operace úspěšná, je možné k modelu dokumentu získat přístup pomocí rozhraní getModel (získat jeden model) nebo rozhraní API GetModels (získat seznam modelů).

Běžné chybové zprávy

Chyba	Rozlišení
400 / Chybný požadavek s "code:" "1002"	Označuje chybu ověření nebo špatně vytvořený požadavek na kopírování. Mezi běžné problémy patří: a) Neplatná nebo upravená copyAuthorization datová část. b) Hodnota expirationDateTimeTicks tokenu vypršela (copyAuthorization datová část je platná po dobu 24 hodin). c) Neplatné nebo nepodporované targetResourceRegion. d) Neplatný nebo poškozený targetResourceId řetězec.
Selhání autorizace kvůli chybějícím nebo neplatným deklaracím autorizace	Nastane, když copyAuthorization se datová část nebo obsah změní z copyAuthorization rozhraní API. Ujistěte se, že datová část je stejný přesný obsah, který se vrátil z předchozího copyAuthorization volání.
Metadata autorizace se nepovedlo načíst.	Označuje, že datová copyAuthorization část se opakovaně používá s žádostí o kopírování. Požadavek na kopírování, který bude úspěšný, neumožňuje žádné další žádosti, které používají stejnou datovou copyAuthorization část. Pokud vyvoláte samostatnou chybu a později zkusíte kopii zopakovat se stejnou autorizační datovou částí, zobrazí se tato chyba. Řešením je vygenerovat novou copyAuthorization datovou část a pak znovu vytvořit požadavek na kopírování.
Žádost o přenos dat není povolená, protože je downgraduje na méně zabezpečené schéma ochrany dat.	Nastane při kopírování mezi povoleným prostředkem AEK do nepovoleným AEK prostředkem. Pokud chcete povolit kopírování šifrovaného modelu do cíle jako nešifrované, zadejte x-ms-forms-copy-degrade: true hlavičku s požadavkem na kopírování.
Nepodařilo se načíst informace o kognitivním prostředku s ID....	Označuje, že prostředek Azure označený tímto prostředkem targetResourceId není platný nebo neexistuje. Pokud chcete tento problém vyřešit, ověřte a znovu spusťte žádost o kopírování. Ujistěte se, že je prostředek platný a existuje v zadané oblasti, například: westus2

Další kroky

V této příručce jste zjistili, jak pomocí rozhraní API pro kopírování zálohovat vlastní modely do sekundárního prostředku Document Intelligence. Dále prozkoumejte referenční dokumentaci k rozhraní API a podívejte se, co dalšího můžete dělat s funkcí Document Intelligence.

• Referenční dokumentace k rozhraní REST API