Odzyskiwanie po awarii

Ta zawartość dotyczy: v4.0 (wersja zapoznawcza) | Poprzednie wersje: v3.1 (GA) v3.0 (GA) v2.1 (GA)

Podczas tworzenia zasobu analizy dokumentów w witrynie Azure Portal należy określić region. Od tego czasu zasób i wszystkie jego operacje pozostają skojarzone z tym konkretnym regionem serwera platformy Azure. Problem z siecią, który dotyczy całego regionu, zdarza się rzadko, ale nie jest niemożliwy. Jeśli rozwiązanie musi być zawsze dostępne, należy zaprojektować je w trybie pracy awaryjnej, w innym regionie lub podzielić obciążenie między co najmniej dwa regiony. Oba podejścia wymagają co najmniej dwóch zasobów analizy dokumentów w różnych regionach oraz możliwość synchronizowania niestandardowych modeli i klasyfikatorów między regionami.

Interfejs API kopiowania umożliwia korzystanie z tego scenariusza, umożliwiając kopiowanie modeli niestandardowych i klasyfikatorów z jednego konta analizy dokumentów lub do innych, które mogą istnieć w dowolnym obsługiwanym regionie geograficznym. W tym przewodniku pokazano, jak używać interfejsu API REST kopiowania z biblioteką cURL dla modeli niestandardowych. Możesz również użyć usługi żądań HTTP do wystawiania żądań.

Uwaga

Począwszy od interfejsu 2024-07-31-preview API, niestandardowe modele klasyfikowania obsługują również interfejs API kopiowania. W tym przewodniku użyto specjalnie modeli niestandardowych do kopiowania modeli. Aby uzyskać kopię modelu klasyfikatora, postępuj zgodnie z tym przewodnikiem.

Scenariusze biznesowe

Jeśli aplikacja lub firma zależy od użycia niestandardowego modelu analizy dokumentów, zalecamy skopiowanie modelu do innego konta analizy dokumentów w innym regionie. Jeśli wystąpi awaria regionalna, możesz uzyskać dostęp do modelu w regionie, w którym został skopiowany.

Wymagania wstępne

1. Dwa zasoby platformy Azure analizy dokumentów w różnych regionach świadczenia usługi Azure. Jeśli ich nie masz, przejdź do witryny Azure Portal i utwórz nowy zasób analizy dokumentów.
2. Klucz, adres URL punktu końcowego i identyfikator subskrypcji zasobu analizy dokumentów. Te wartości można znaleźć na karcie Przegląd zasobu w witrynie Azure Portal.

Omówienie interfejsu API kopiowania

Proces kopiowania modelu niestandardowego składa się z następujących kroków:

1. Najpierw należy wysłać żądanie autoryzacji kopiowania do zasobu docelowego — czyli zasób, który odbiera skopiowany model. Otrzymasz z powrotem adres URL nowo utworzonego modelu docelowego, który odbiera skopiowany model.
2. Następnie wyślesz żądanie kopiowania do zasobu źródłowego — zasób zawierający model, który ma zostać skopiowany z ładunku (autoryzacja kopiowania) zwróconego z poprzedniego wywołania. Otrzymasz z powrotem adres URL, którego można wykonać zapytanie w celu śledzenia postępu operacji.
3. Poświadczenia zasobu źródłowego służą do wykonywania zapytań dotyczących adresu URL postępu do momentu pomyślnego wykonania operacji. Możesz również wykonać zapytanie dotyczące nowego identyfikatora modelu w zasobie docelowym, aby uzyskać stan nowego modelu.

Generowanie żądania autoryzacji kopiowania

Następujące żądanie HTTP pobiera autoryzację kopiowania z zasobu docelowego. Musisz wprowadzić punkt końcowy i klucz zasobu docelowego jako nagłówki.

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

Treść żądania

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

Otrzymasz kod odpowiedzi z treścią 200 odpowiedzi zawierającą ładunek JSON wymagany do zainicjowania kopii.

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

Uruchamianie operacji kopiowania

Następujące żądanie HTTP uruchamia operację kopiowania w zasobie źródłowym. Musisz wprowadzić punkt końcowy i klucz zasobu źródłowego jako adres URL i nagłówek. Zwróć uwagę, że adres URL żądania zawiera identyfikator modelu modelu źródłowego, który chcesz skopiować.

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

Treść żądania to odpowiedź z poprzedniego 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"
}

202\Accepted Otrzymasz odpowiedź z nagłówkiem Operation-Location. Ta wartość to adres URL używany do śledzenia postępu operacji. Skopiuj go do lokalizacji tymczasowej w następnym kroku.

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

Uwaga

Interfejs API kopiowania w sposób niewidoczny obsługuje funkcję AEK/CMK . Nie wymaga to żadnego specjalnego traktowania, ale należy pamiętać, że jeśli kopiujesz między niezaszyfrowanym zasobem do zaszyfrowanego zasobu, musisz dołączyć nagłówek x-ms-forms-copy-degrade: trueżądania . Jeśli ten nagłówek nie zostanie dołączony, operacja kopiowania zakończy się niepowodzeniem i zwróci wartość DataProtectionTransformServiceError.

Śledzenie postępu kopiowania

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

Śledzenie identyfikatora modelu docelowego

Możesz również użyć interfejsu Get model API do śledzenia stanu operacji, wykonując zapytanie względem modelu docelowego. Wywołaj interfejs API przy użyciu identyfikatora modelu docelowego skopiowanego z Generate copy authorization odpowiedzi na żądanie .

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

W treści odpowiedzi zobaczysz informacje o modelu. "status" Sprawdź pole stanu modelu.

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

Przykładowy kod cURL

Poniższe fragmenty kodu używają biblioteki cURL do tworzenia wywołań interfejsu API. Należy również wypełnić identyfikatory modelu i informacje o subskrypcji specyficzne dla własnych zasobów.

Generowanie autoryzacji kopiowania

Zażądaj

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

Pomyślna odpowiedź

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

Rozpocznij operację kopiowania

Zażądaj

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

Pomyślna odpowiedź

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

Śledzenie postępu operacji kopiowania

Interfejs API operacji GET umożliwia wyświetlenie listy wszystkich operacji modelu dokumentów (zakończonych powodzeniem, w toku lub niepowodzeniem) skojarzonych z zasobem analizy dokumentów. Informacje o operacji są utrwalane tylko przez 24 godziny. Oto lista operacji (operationId), które można zwrócić:

• documentModelBuild
• documentModelCompose
• documentModelCopyTo

Śledzenie identyfikatora modelu docelowego

Jeśli operacja zakończyła się pomyślnie, dostęp do modelu dokumentów można uzyskać przy użyciu modelu getModel (pobierz pojedynczy model) lub interfejsów API GetModels (pobierz listę modeli).

Typowe komunikaty o kodzie błędu

Błąd	Rozwiązanie
400 / Nieprawidłowe żądanie z "code:" "1002"	Wskazuje błąd weryfikacji lub nieprawidłowe sformułowane żądanie kopiowania. Typowe problemy to: a) Nieprawidłowy lub zmodyfikowany copyAuthorization ładunek. b) Wygasła wartość tokenu expirationDateTimeTicks (copyAuthorization ładunek jest ważny przez 24 godziny). c) Nieprawidłowy lub nieobsługiwany targetResourceRegion. d) Nieprawidłowy lub źle sformułowany targetResourceId ciąg.
Niepowodzenie autoryzacji z powodu braku lub nieprawidłowych oświadczeń autoryzacji.	Występuje, gdy copyAuthorization ładunek lub zawartość jest modyfikowana z interfejsu copyAuthorization API. Upewnij się, że ładunek jest tą samą zawartością, która została zwrócona z wcześniejszego copyAuthorization wywołania.
Nie można pobrać metadanych autoryzacji.	Wskazuje, że copyAuthorization ładunek jest ponownie używany z żądaniem kopiowania. Żądanie kopiowania, które powiedzie się, nie zezwala na dalsze żądania używające tego samego copyAuthorization ładunku. Jeśli zostanie zgłoszony oddzielny błąd, a później ponowisz próbę skopiowania z tym samym ładunkiem autoryzacji, ten błąd zostanie zgłoszony. Rozwiązaniem jest wygenerowanie nowego copyAuthorization ładunku, a następnie ponowne utworzenie żądania kopiowania.
Żądanie transferu danych nie jest dozwolone, ponieważ obniża poziom do mniej bezpiecznego schematu ochrony danych.	Występuje podczas kopiowania między włączonym zasobem AEK do zasobu, który nie AEK jest włączony. Aby zezwolić na kopiowanie zaszyfrowanego modelu do obiektu docelowego jako niezaszyfrowanego, określ x-ms-forms-copy-degrade: true nagłówek z żądaniem kopiowania.
"Nie można pobrać informacji dla zasobu Poznawczego o identyfikatorze...".	Wskazuje, że zasób platformy Azure wskazany przez targetResourceId element nie jest prawidłowym zasobem Poznawczym lub nie istnieje. Aby rozwiązać ten problem, sprawdź i ponownie prześlij żądanie kopiowania. Upewnij się, że zasób jest prawidłowy i istnieje w określonym regionie, na przykład westus2

Następne kroki

W tym przewodniku przedstawiono sposób użycia interfejsu API kopiowania do tworzenia kopii zapasowych modeli niestandardowych w pomocniczym zasobie analizy dokumentów. Następnie zapoznaj się z dokumentacją referencyjną interfejsu API, aby zobaczyć, co jeszcze można zrobić za pomocą analizy dokumentów.

• Dokumentacja referencyjna interfejsu API REST