Freigeben über


Notfallwiederherstellung

Dieser Inhalt gilt für: Häkchen Version 4.0 (Vorschau) | Vorherige Versionen: Blaues Häkchen Version 3.1 (GA) Blaues Häkchen Version 3.0 (GA) Blaues Häkchen Version 2.1 (GA)

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

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

Dieser Inhalt gilt für: Häkchen Version 2.1 | Neueste Version: Blaues Häkchen Version 4.0 (Vorschau)

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://<your-resource-endpoint>/documentintelligence/documentModels:authorizeCopy?api-version=2024-02-29-preview
Ocp-Apim-Subscription-Key: {<your-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 https://<your-resource-endpoint>/documentintelligence/documentModels/{modelId}:copyTo?api-version=2024-02-29-preview
Ocp-Apim-Subscription-Key: {<your-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://<your-resource-endpoint>.cognitiveservices.azure.com/documentintelligence/operations/{operation-id}?api-version=2024-02-29-preview

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://<your-resource-endpoint>.cognitiveservices.azure.com/documentintelligence/operations/{<operation-id>}?api-version=2024-02-29-preview
Ocp-Apim-Subscription-Key: {<your-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-resource-endpoint>/documentintelligence/documentModels/{modelId}?api-version=2024-02-29-preview" -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-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}'
}"

Erfolgreiche Antwort

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

Starten des Kopiervorgangs

Anforderung

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

Erfolgreiche Antwort

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

Nachverfolgen des Fortschritts des Kopiervorgangs

Sie können mithilfe der API Vorgang abrufen 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.

Ü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.

Übersicht über das Kopiermodell

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.

Generieren einer Autorisierungsanforderung

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

POST https://{TARGET_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/v2.1/custom/models/copyAuthorization
Ocp-Apim-Subscription-Key: {TARGET_FORM_RECOGNIZER_RESOURCE_KEY}

Sie erhalten eine 201\Created-Antwort mit einem modelId-Wert im Textkörper. Diese Zeichenfolge ist die ID des neu erstellten (leeren) Modells. Die API benötigt das accessToken zum Kopieren der Daten in diese Ressource, und der expirationDateTimeTicks-Wert repräsentiert den Ablauf des Tokens. Speichern Sie sämtliche dieser Werte an einem sicheren Speicherort.

HTTP/1.1 201 Created
Location: https://{TARGET_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/v2.1/custom/models/33f4d42c-cd2f-4e74-b990-a1aeafab5a5d
{"modelId":"<your model ID>","accessToken":"<your access token>","expirationDateTimeTicks":637233481531659440}

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 Ressource als Header eingeben. Beachten Sie, dass die Anforderungs-URL die Modell-ID des Quellmodells enthält, das Sie kopieren möchten.

POST https://{SOURCE_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/v2.1/custom/models/<your model ID>/copy HTTP/1.1
Ocp-Apim-Subscription-Key: {SOURCE_FORM_RECOGNIZER_RESOURCE_KEY}

Der Textkörper Ihrer Anforderung muss das folgende Format aufweisen. Sie müssen die Ressourcen-ID und den Regionsnamen Ihrer Zielressource eingeben. Sie finden Ihre Ressourcen-ID auf der Registerkarte Eigenschaften Ihrer Ressource im Azure-Portal. Den Namen der Region finden Sie auf der Registerkarte Schlüssel und Endpunkt. Außerdem benötigen Sie die Modell-ID, das Zugriffstoken und den Ablaufwert aus dem vorherigen Schritt.

{
   "targetResourceId": "{TARGET_AZURE_FORM_RECOGNIZER_RESOURCE_ID}",  
   "targetResourceRegion": "{TARGET_AZURE_FORM_RECOGNIZER_RESOURCE_REGION_NAME}",
   "copyAuthorization": {"modelId":"<your model ID>","accessToken":"<your access token>","expirationDateTimeTicks":637233481531659440}
}

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_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/v2.1/custom/models/eccc3f13-8289-4020-ba16-9f1d1374e96f/copyresults/02989ba8-1296-499f-aaf4-55cfff41b8f1

Hinweis

Die Kopier-API unterstützt das Feature AEK/CMK auf transparente Weise. Dieser Vorgang erfordert keine besondere Vorgehensweise, 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 Vorgangsfortschritts

Verfolgen Sie den Fortschritt des Vorgangs, indem Sie die API GET copy model result für den Quellressourcenendpunkt abrufen.

GET https://{SOURCE_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/v2.1/custom/models/eccc3f13-8289-4020-ba16-9f1d1374e96f/copyresults/02989ba8-1296-499f-aaf4-55cfff41b8f1 HTTP/1.1
Ocp-Apim-Subscription-Key: {SOURCE_FORM_RECOGNIZER_RESOURCE_KEY}

Die Antwort richtet sich nach dem Status des Vorgangs. Suchen Sie im JSON-Textkörper nach dem Feld "status". Wenn Sie diesen API-Aufruf in einem Skript automatisieren, empfehlen wir, den Vorgang einmal pro Sekunde abzufragen.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"status":"succeeded","createdDateTime":"2020-04-23T18:18:01.0275043Z","lastUpdatedDateTime":"2020-04-23T18:18:01.0275048Z","copyResult":{}}

Nachverfolgen des Vorgangsstatus mit „modelID“

Sie können mit der API GET custom model auch den Status des Vorgangs abrufen, indem Sie das Zielmodell abfragen. Rufen Sie diese API unter Verwendung der Zielmodell-ID ab, die Sie im ersten Schritt kopiert haben.

GET https://{TARGET_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/v2.1/custom/models/33f4d42c-cd2f-4e74-b990-a1aeafab5a5d HTTP/1.1
Ocp-Apim-Subscription-Key: {TARGET_FORM_RECOGNIZER_RESOURCE_KEY}

Im Antworttext sind Informationen zum Modell enthalten. Ü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-Codebeispiele

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

curl -i -X POST "https://{TARGET_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/v2.1/custom/models/copyAuthorization" -H "Ocp-Apim-Subscription-Key: {TARGET_FORM_RECOGNIZER_RESOURCE_KEY}" 

Starten des Kopiervorgangs

curl -i -X POST "https://{TARGET_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/v2.1/custom/models/copyAuthorization" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {TARGET_FORM_RECOGNIZER_RESOURCE_KEY}" --data-ascii "{ \"targetResourceId\": \"{TARGET_AZURE_FORM_RECOGNIZER_RESOURCE_ID}\",   \"targetResourceRegion\": \"{TARGET_AZURE_FORM_RECOGNIZER_RESOURCE_REGION_NAME}\", \"copyAuthorization\": "{\"modelId\":\"33f4d42c-cd2f-4e74-b990-a1aeafab5a5d\",\"accessToken\":\"1855fe23-5ffc-427b-aab2-e5196641502f\",\"expirationDateTimeTicks\":637233481531659440}"}"

Nachverfolgen des Kopierfortschritts

curl -i GET "https://<SOURCE_FORM_RECOGNIZER_RESOURCE_ENDPOINT>/formrecognizer/v2.1/custom/models/{SOURCE_MODELID}/copyResults/{RESULT_ID}" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {SOURCE_FORM_RECOGNIZER_RESOURCE_KEY}"

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.

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.