Vészhelyreállítás

Ez a tartalom a következőre vonatkozik: v4.0 (előzetes verzió) | Korábbi verziók: v3.1 (GA) v3.0 (GA) v2.1 (GA)

Amikor dokumentumintelligencia-erőforrást hoz létre az Azure Portalon, meg kell adnia egy régiót. Ettől kezdve az erőforrás és annak összes művelete az adott Azure-kiszolgálórégióhoz lesz társítva. Ritka, de nem lehetetlen, ha egy teljes régiót elérő hálózati problémába ütközik. Ha a megoldásnak mindig elérhetőnek kell lennie, azt úgy kell megterveznie, hogy a feladatátvételt másik régióra bontsa, vagy a számítási feladatot két vagy több régió között felossza. Mindkét megközelítéshez legalább két dokumentumintelligencia-erőforrásra van szükség a különböző régiókban, és lehetővé kell tenni az egyéni modellek és osztályozók régiók közötti szinkronizálását.

A Copy API lehetővé teszi ezt a forgatókönyvet azáltal, hogy lehetővé teszi egyéni modellek és osztályozók másolását egy Dokumentumintelligencia-fiókból vagy másba, amelyek bármely támogatott földrajzi régióban létezhetnek. Ez az útmutató bemutatja, hogyan használhatja a REST API másolását cURL-vel egyéni modellekhez. HTTP-kérési szolgáltatással is kiadhatja a kéréseket.

Feljegyzés

Az API-tól kezdve az 2024-07-31-preview egyéni arculati modellek a Copy API-t is támogatják. Ez az útmutató kifejezetten egyéni modelleket használ a modellek másolásához. Az osztályozómodell másolásához kövesse ezt az útmutatót.

Üzleti esetek

Ha az alkalmazás vagy a vállalkozás a Document Intelligence egyéni modelljének használatától függ, javasoljuk, hogy másolja a modellt egy másik régióban lévő dokumentumintelligencia-fiókba. Regionális leállás esetén a modell abban a régióban érhető el, ahol a másolás történt.

Előfeltételek

1. Két Document Intelligence Azure-erőforrás különböző Azure-régiókban. Ha nem rendelkezik velük, lépjen az Azure Portalra, és hozzon létre egy új Dokumentumintelligencia-erőforrást.
2. A dokumentumintelligencia-erőforrás kulcsa, végponti URL-címe és előfizetés-azonosítója. Ezeket az értékeket az erőforrás Áttekintés lapján találja az Azure Portalon.

Az API másolása – áttekintés

Az egyéni modell másolásának folyamata a következő lépésekből áll:

1. Először kiad egy másolás-engedélyezési kérelmet a célerőforrásnak, vagyis a másolt modellt fogadó erőforrásnak. A másolt modellt fogadó újonnan létrehozott célmodell URL-címét kapja vissza.
2. Ezután elküldi a másolási kérelmet a forráserőforrásnak – a másolandó modellt tartalmazó erőforrásnak az előző hívásból visszaadott hasznos adatokkal (másolási engedélyezéssel). Kap egy URL-címet, amelyet lekérdezhet a művelet előrehaladásának nyomon követéséhez.
3. A forráserőforrás hitelesítő adataival lekérdezheti a folyamat URL-címét, amíg a művelet sikeres nem lesz. A célerőforrás új modellazonosítóját is lekérdezheti az új modell állapotának lekéréséhez.

Másolási engedélyezési kérelem létrehozása

A következő HTTP-kérés a célerőforrás másolási engedélyezését kéri le. Fejlécként meg kell adnia a célerőforrás végpontját és kulcsát.

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

Kérés törzse

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

Egy válaszkódot kap a 200 válasz törzsével, amely tartalmazza a másolat indításához szükséges JSON hasznos adatokat.

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

Másolási művelet indítása

A következő HTTP-kérés elindítja a másolási műveletet a forráserőforráson. Url-címként és fejlécként meg kell adnia a forráserőforrás végpontját és kulcsát. Figyelje meg, hogy a kérelem URL-címe tartalmazza a másolni kívánt forrásmodell modellazonosítóját.

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

A kérés törzse az előző lépés válasza.

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

Egy művelet-hely fejlécet tartalmazó választ kap 202\Accepted . Ez az érték a művelet előrehaladásának nyomon követéséhez használt URL-cím. Másolja egy ideiglenes helyre a következő lépéshez.

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

Feljegyzés

A Copy API transzparensen támogatja az AEK/CMK funkciót. Ehhez nincs szükség speciális kezelésre, de vegye figyelembe, hogy ha titkosítatlan erőforrás között másol egy titkosított erőforrást, a kérés fejlécét x-ms-forms-copy-degrade: trueis tartalmaznia kell. Ha ez a fejléc nem szerepel a fájlban, a másolási művelet sikertelen lesz, és visszaad egy DataProtectionTransformServiceError.

Másolási folyamat nyomon követése

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

A célmodell azonosítójának nyomon követése

Az API-val Get model a célmodell lekérdezésével is nyomon követheti a művelet állapotát. Hívja meg az API-t a kérés válaszából Generate copy authorization lemásolt célmodell-azonosítóval.

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

A válasz törzsében a modell információi láthatók. Ellenőrizze a "status" modell állapotát a mezőben.

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-mintakód

Az alábbi kódrészletek a cURL használatával kezdeményeznek API-hívásokat. Meg kell adnia a saját erőforrásaira vonatkozó modellazonosítókat és előfizetési adatokat is.

Másolási engedélyezés létrehozása

Kérelem

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

Sikeres válasz

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

Másolási művelet indítása

Kérelem

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

Sikeres válasz

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

Másolási művelet előrehaladásának nyomon követése

A GET műveleti API-val listázhatja a dokumentumintelligencia-erőforráshoz társított összes (sikeres, folyamatban lévő vagy sikertelen) dokumentummodell-műveletet. A műveleti adatok csak 24 óráig maradnak meg. Íme a visszaadható műveletek (operationId) listája:

• documentModelBuild
• documentModelCompose
• documentModelCopyTo

A célmodell azonosítójának nyomon követése

Ha a művelet sikeres volt, a dokumentummodell a getModel (egyetlen modell lekérése) vagy a GetModels (modellek listájának lekérése) API-k használatával érhető el.

Gyakori hibaüzenetek

Hiba	Resolution (Osztás)
400 / Hibás kérés a "code:" "1002"	Érvényesítési hibát vagy hibásan formázott másolási kérelmet jelez. Gyakori problémák a következők: a) Érvénytelen vagy módosított copyAuthorization hasznos adatok. b) A jogkivonat lejárt értéke expirationDateTimeTicks (copyAuthorization a hasznos adatok 24 órán át érvényesek). c) Érvénytelen vagy nem támogatott targetResourceRegion. d) Érvénytelen vagy hibásan formázott sztring targetResourceId .
Hiányzó vagy érvénytelen engedélyezési jogcímek miatti engedélyezési hiba.	A hasznos adatok vagy tartalmak API-ból való copyAuthorization módosításakor copyAuthorization fordul elő. Győződjön meg arról, hogy a hasznos adatok pontosan megegyeznek a korábbi copyAuthorization hívásból visszaadott tartalommal.
Nem sikerült lekérni az engedélyezési metaadatokat.	Azt jelzi, hogy a copyAuthorization hasznos adatok másolási kéréssel újra felhasználhatók. A sikeres másolási kérések nem teszik lehetővé az azonos copyAuthorization hasznos adatokat használó további kéréseket. Ha külön hibát jelez, és később újra megkísérli a másolatot ugyanazzal az engedélyezési hasznos adattal, a hiba megjelenik. A megoldás egy új copyAuthorization hasznos adat létrehozása, majd a másolási kérelem újbóli kiadása.
Az adatátviteli kérelem nem engedélyezett, mivel kevésbé biztonságos adatvédelmi sémára vált.	Ez akkor fordul elő, ha egy AEK engedélyezett erőforrás közötti másolás nem AEK engedélyezett erőforrásba történik. Ha titkosítatlanként szeretné engedélyezni a titkosított modell másolását a célra, adja meg x-ms-forms-copy-degrade: true a fejlécet a másolási kérelemmel.
"Nem sikerült beolvasni a Cognitive-erőforrás adatait azonosítóval...".	Azt jelzi, hogy a megadott Azure-erőforrás targetResourceId nem érvényes Cognitive-erőforrás, vagy nem létezik. A probléma megoldásához ellenőrizze és újból kiadja a másolási kérelmet. Ellenőrizze, hogy az erőforrás érvényes-e, és létezik-e a megadott régióban, például: westus2

Következő lépések

Ebben az útmutatóban megtanulta, hogyan készíthet biztonsági másolatot az egyéni modellekről egy másodlagos dokumentumintelligencia-erőforrásra a Copy API használatával. Ezután ismerkedjen meg az API referenciadokumentumaival, és nézze meg, mit tehet még a Dokumentumintelligencia használatával.

• REST API-referenciadokumentáció