Notfallwiederherstellung

Dieser Inhalt gilt für: Version 3.1 (GA) | Aktuelle Version: Version 4.0 (Vorschau) | Vorherige Versionen: Version 3.0 Version 2.1

Wenn Sie eine Dokument Intelligenz-Ressource im Azure-Portal erstellen, geben Sie eine Region an. Ab diesem Zeitpunkt bleiben Ihre Ressource und alle zugehörigen Vorgänge mit der jeweiligen Azure-Serverregion verknüpft. Es ist selten, aber nicht unmöglich, dass ein Netzwerkproblem auftritt, das eine ganze Region betrifft. Wenn Ihre Lösung immer verfügbar sein muss, dann sollten Sie sie so konzipieren, dass entweder ein Failover in eine andere Region durchgeführt oder die Workload auf zwei oder mehr Regionen verteilt wird. Beide Ansätze setzen voraus, dass mindestens zwei Dokument Intelligenz-Ressourcen in unterschiedlichen Regionen vorliegen und dass es möglich ist, benutzerdefinierte Modelle und Klassifizierer regionsübergreifend zu synchronisieren.

Die Copy API unterstützt dieses Szenario, indem sie Ihnen ermöglicht, benutzerdefinierte Modelle und Klassifizierer von einem Dokument Intelligenz-Konto in andere Konten zu kopieren, die in einer beliebigen unterstützten geografischen Region vorliegen können. Der vorliegende Leitfaden zeigt, wie Sie die REST-API zum Kopieren mit cURL für benutzerdefinierte Modelle verwenden. Sie können auch einen HTTP-Anforderungsdienst verwenden, um die Anforderungen auszugeben.

Hinweis

Ab der 2024-07-31-preview-API unterstützen auch benutzerdefinierte Clasification-Modelle die Copy API. In diesem Leitfaden werden speziell benutzerdefinierte Modelle zum Kopieren von Modellen verwendet. Folgen Sie diesem Leitfaden, um das Klassifizierermodell zu kopieren.

Geschäftsszenarien

Wenn Ihre App oder Ihr Unternehmen von der Verwendung eines benutzerdefinierten Dokument Intelligenz-Modells abhängt, sollten Sie Ihr Modell in ein anderes Dokument Intelligenz-Konto kopieren, das sich in einer anderen Region befindet. Im Falle eines regionalen Ausfalls können Sie auf Ihr Modell in der Region zugreifen, in die das Modell kopiert wurde.

Voraussetzungen

1. Zwei Azure KI Dokument Intelligenz-Ressourcen in unterschiedlichen Azure-Regionen. Wenn Sie diese nicht haben, wechseln Sie zum Azure-Portal und erstellen Sie eine neue Dokument Intelligenz-Ressource.
2. Schlüssel, Endpunkt-URL und Abonnement-ID Ihrer Dokument Intelligenz-Ressource. Sie finden diese Werte im Azure-Portal auf der Registerkarte Übersicht für die Ressource.

Übersicht über die Kopier-API

Der Vorgang zum Kopieren eines benutzerdefinierten Modells umfasst die folgenden Schritte:

1. Zuerst senden Sie eine Autorisierungsanforderung für den Kopiervorgang an die Zielressource, d. h. an die Ressource, die das kopierte Modell erhalten soll. Als Antwort erhalten Sie die URL des neu erstellten Zielmodells, das das kopierte Modell erhalten wird.
2. Als Nächstes senden Sie die Kopieranforderung an die Quellressource – die Ressource, die das zu kopierende Modell mit der Nutzlast (Kopierberechtigung) enthält, die vom vorherigen Aufruf zurückgegeben wurde. Als Antwort erhalten Sie eine URL, über die Sie den Fortschritt des Vorgangs nachverfolgen können.
3. Sie verwenden die Anmeldeinformationen für Ihre Quellressource zum Abfragen der URL zum Fortschritt, bis der Vorgang erfolgreich abgeschlossen wurde. Sie können auch die ID des neuen Modells in der Zielressource abfragen, um den Status des neuen Modells abzurufen.

Generieren einer Autorisierungsanforderung für den Kopiervorgang

Mit der folgenden HTTP-Anforderung wird eine Autorisierung für den Kopiervorgang von Ihrer Zielressource abgerufen. Sie müssen den Endpunkt und den Schlüssel Ihrer Zielressource als Header eingeben.

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}

Anforderungstext

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

Sie erhalten den Antwortcode 200 mit Antworttext, der die JSON-Nutzdaten enthält, die zum Initiieren des Kopiervorgangs erforderlich ist.

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

Starten des Kopiervorgangs

Mit der folgenden HTTP-Anforderung wird der Kopiervorgang für die Quellressource gestartet. Sie müssen den Endpunkt und den Schlüssel Ihrer Quellressource als URL und Header eingeben. Beachten Sie, dass die Anforderungs-URL die Modell-ID des Quellmodells enthält, das Sie kopieren möchten.

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

Der Text Ihrer Anforderung ist die Antwort aus dem vorherigen Schritt.

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

Sie erhalten eine 202\Accepted-Antwort mit einem Operation-Location-Header. Dieser Wert ist die URL, mit der Sie den Fortschritt des Vorgangs nachverfolgen. Kopieren Sie die URL für den nächsten Schritt an einen temporären Speicherort.

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

Hinweis

Die Kopier-API unterstützt das Feature AEK/CMK auf transparente Weise. Dies erfordert keine besondere Behandlung, aber beachten Sie, dass Sie beim Kopieren zwischen einer unverschlüsselten Ressource und einer verschlüsselten Ressource den Anforderungsheader x-ms-forms-copy-degrade: true einfügen müssen. Wenn dieser Header nicht enthalten ist, tritt beim Kopiervorgang ein Fehler auf und es wird ein DataProtectionTransformServiceError zurückgegeben.

Nachverfolgen des Kopierfortschritts

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}

Nachverfolgen der Zielmodell-ID

Sie können mit der API GET model auch den Status des Vorgangs abrufen, indem Sie das Zielmodell abfragen. Rufen Sie die API mithilfe der Zielmodell-ID auf, die Sie aus der Generate Copy authorization-Anforderungsantwort kopiert haben.

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

Im Antworttext werden Informationen zum Modell angezeigt. Überprüfen Sie den Status des Modells im Feld "status".

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

Die folgenden Codeschnipsel verwenden cURL, um API-Aufrufe auszuführen. Sie müssen auch die Modell-IDs und die Abonnementinformationen für Ihre eigenen Ressourcen eingeben.

Generieren einer Autorisierung für den Kopiervorgang

Anforderung

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

Erfolgreiche Antwort

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

Starten des Kopiervorgangs

Anforderung

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

Erfolgreiche Antwort

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

Nachverfolgen des Fortschritts des Kopiervorgangs

Sie können mithilfe der API GET operation alle Dokumentmodellvorgänge (erfolgreich, in Bearbeitung oder fehlerhaft) auflisten, die Ihrer Dokument Intelligenz-Ressource zugeordnet sind. Vorgangsinformationen bleiben nur für 24 Stunden erhalten. Im Folgenden finden Sie eine Liste der Vorgänge (operationId), die zurückgegeben werden können:

• documentModelBuild
• documentModelCompose
• documentModelCopyTo

Nachverfolgen der Zielmodell-ID

Wenn der Vorgang erfolgreich war, kann mit den APIs getModel (zum Abrufen eines einzelnen Modells) oder GetModels (zum Abrufen einer Liste von Modellen) auf das Dokumentmodell zugegriffen werden.

Häufige Fehlercodes/Fehlermeldungen

Fehler	Lösung
400/Ungültige Anforderung mit "code:" "1002"	Zeigt einen Validierungsfehler oder eine schlecht formulierte Kopieranforderung an. Zu den häufigen Problemen gehören: a) Ungültige oder geänderte copyAuthorization-Nutzlast. b) Abgelaufener Wert für expirationDateTimeTicks-Token (copyAuthorization-Nutzlast ist 24 Stunden lang gültig). c) Ungültige oder nicht unterstützte targetResourceRegion. d) Ungültige oder fehlerhafte targetResourceId-Zeichenfolge.
Autorisierungsfehler aufgrund fehlender oder ungültiger Autorisierungsansprüche.	Tritt auf, wenn die copyAuthorization-Nutzdaten oder der Inhalt von dem abweicht, was von der copyAuthorization-API zurückgegeben wurde. Stellen Sie sicher, dass die Nutzlast exakt denselben Inhalt hat, der vom früheren copyAuthorization-Aufruf zurückgegeben wurde.
Autorisierungsmetadaten konnten nicht abgerufen werden.	Gibt an, dass die copyAuthorization-Nutzlast mit einer Kopieranforderung wiederverwendet wird. Eine erfolgreiche Kopieranforderung lässt keine weiteren Anforderungen zu, die dieselben copyAuthorization-Nutzdaten verwenden. Wenn Sie einen separaten Fehler auslösen und später die Kopie mit denselben Autorisierungsnutzdaten erneut versuchen, wird dieser Fehler ausgelöst. Die Lösung besteht darin, eine neue copyAuthorization-Nutzlast zu generieren und dann die Kopieranforderung neu zu erstellen.
Die Anforderung einer Datenübertragung ist unzulässig, da durch sie eine Herabstufung auf ein weniger sicheres Datenschutzsystem durchgeführt wird.	Tritt auf, wenn zwischen einer für AEK aktivierten Ressource und einer nicht für AEK aktivierten Ressource kopiert wird. Um das Kopieren des verschlüsselten Modells zum Ziel als „unverschlüsselt“ zu gestatten, geben Sie den x-ms-forms-copy-degrade: true-Header mit der Kopieranforderung an.
„Es konnten keine Informationen zur Cognitive-Ressource mit der betreffenden ID abgerufen werden.“	Gibt an, dass die mit targetResourceId angegebene Azure-Ressource keine gültige Cognitive-Ressource oder nicht vorhanden ist. Um dieses Problem zu beheben, überprüfen Sie den Kopierauftrag und stellen ihn erneut aus. Stellen Sie sicher, dass die Ressource gültig und in der angegebenen Region (z. B. westus2) vorhanden ist.

Nächste Schritte

In diesem Leitfaden haben Sie erfahren, wie Sie die Kopier-API zum Sichern Ihrer benutzerdefinierten Modelle in einer sekundären Dokument Intelligenz-Ressource verwenden. Sehen Sie sich als Nächstes die API-Referenzdokumentation an, um sich über weitere Möglichkeiten bei der Verwendung von Dokument Intelligenz zu informieren.

• Referenzdokumentation zur Rest-API