Аварийное восстановление

Это содержимое относится к: версии 4.0 (предварительная версия) | Предыдущие версии: версия 3.1 (GA) версии 3.0 (GA) версии 2.1 (GA)

При создании ресурса аналитики документов в портал Azure укажите регион. После этого ваш ресурс и все его операции связаны с этим конкретным регионом сервера Azure. В редких случаях можно столкнуться с сетевой проблемой, которая затрагивает весь регион. Если решение должно быть доступно всегда, необходимо разработать его таким образом, чтобы выполнялась отработка отказа в другой регион или разделить рабочую нагрузку между двумя или более регионами. Оба подхода требуют по крайней мере двух ресурсов аналитики документов в разных регионах и возможности синхронизации пользовательских моделей и классификаторов между регионами.

API копирования позволяет этому сценарию копировать пользовательские модели и классификаторы из одной учетной записи аналитики документов или в другие, которые могут существовать в любом поддерживаемом географическом регионе. В этом руководстве показано, как использовать REST API копирования с cURL для пользовательских моделей. Вы также можете использовать службу HTTP-запросов для выдачи запросов.

Примечание.

Начиная с API, пользовательские 2024-07-31-preview модели класификации также поддерживают API копирования. В этом руководстве специально используются пользовательские модели для копирования моделей. Для копирования модели классификатора следуйте этому руководству.

Бизнес-сценарии

Если ваше приложение или бизнес зависит от использования пользовательской модели аналитики документов, рекомендуется скопировать модель в другую учетную запись аналитики документов в другом регионе. В случае регионального сбоя можно получить доступ к модели в регионе, куда была скопирована модель.

Необходимые компоненты

1. Два ресурса Azure аналитики документов в разных регионах Azure. Если у вас их нет, перейдите к портал Azure и создайте новый ресурс аналитики документов.
2. Ключ, URL-адрес конечной точки и идентификатор подписки для ресурса Аналитики документов. Эти значения находятся на вкладке Обзор ресурса на портале Azure.

Общие сведения об API копирования

Процесс копирования настраиваемой модели включает следующие этапы.

1. Сначала вы выдаете запрос на авторизацию копирования целевому ресурсу, то есть ресурс, который получает скопированную модель. Вы получите URL-адрес созданной целевой модели, получающей скопированную модель.
2. Затем вы отправляете запрос на копирование исходному ресурсу — ресурсу, содержащему модель, которую необходимо скопировать с помощью полезных данных (авторизация копирования), возвращенных из предыдущего вызова. Вы получите URL-адрес, который можно запросить для отслеживания хода выполнения операции.
3. Учетные данные исходного ресурса используются для запроса URL-адреса хода выполнения, пока операция не будет успешной. Можно также запросить идентификатор новой модели в целевом ресурсе, чтобы получить состояние новой модели.

Создание запроса на авторизацию копирования

Следующий HTTP-запрос получает авторизацию на копирование из целевого ресурса. Необходимо ввести конечную точку и ключ целевого ресурса в качестве заголовков.

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

Текст запроса

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

Вы получаете код ответа с текстом ответа, содержащим полезные 200 данные JSON, необходимые для запуска копии.

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

Запуск операции копирования

Следующий HTTP-запрос запускает операцию копирования в исходном ресурсе. Необходимо ввести конечную точку и ключ исходного ресурса в качестве URL-адреса и заголовка. Обратите внимание, что URL-адрес запроса содержит идентификатор исходной модели, которую необходимо скопировать.

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

Текст запроса — это ответ, полученный на предыдущем шаге.

{
  "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 ответ с заголовком Operation-Location. Это значение является URL-адресом, используемым для отслеживания хода выполнения операции. Скопируйте его во временную папку для следующего шага.

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

Примечание.

API копирования прозрачно поддерживает функцию AEK/CMK. Это не требует специальной обработки, но обратите внимание, что при копировании из незашифрованного ресурса в зашифрованный ресурс необходимо включить заголовок запроса x-ms-forms-copy-degrade: true. Если этот заголовок не включен, операция копирования завершится ошибкой и вернет DataProtectionTransformServiceError.

Отслеживание хода копирования

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

Отслеживание идентификатора целевой модели

Вы также можете использовать Get model API для отслеживания состояния операции, запрашивая целевую модель. Вызовите API с помощью идентификатора целевой модели, скопированного из Generate copy authorization ответа запроса .

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

В тексте ответа отображаются сведения о модели. Состояние модели указано в поле "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

Приведенные ниже фрагменты кода используют cURL для вызова API. Кроме того, необходимо заполнить идентификаторы модели и сведения о подписке, относящиеся к собственным ресурсам.

Создание авторизации копирования

Запросить

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

Успешный ответ

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

Начать операцию копирования

Запросить

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

Успешный ответ

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

Отслеживание хода выполнения операции копирования

API операций GET можно использовать для перечисления всех операций модели документов (успешной, неработоемой или неудачной), связанной с ресурсом аналитики документов. Сведения об операциях сохраняются только в течение 24 часов. Ниже приведен список операций (operationId), которые можно вернуть:

• documentModelBuild
• documentModelCompose
• documentModelCopyTo

Отслеживание идентификатора целевой модели

Если операция выполнена успешно, доступ к модели документа можно получить с помощью api getModel (получить одну модель) или GetModels (получить список моделей).

Распространенные сообщения об ошибках

Ошибка	Разрешение
400/недопустимый запрос с кодом "code:" "1002"	Указывает на ошибку проверки или некорректный запрос на копирование. Распространенные проблемы включают: a) недопустимые или измененные полезные данные copyAuthorization; б) значение срока действия маркера expirationDateTimeTicks (полезные данные copyAuthorization действительны в течение 24 часов); в) недопустимый или неподдерживаемый targetResourceRegion; г) недопустимая или неправильная строка targetResourceId.
Сбой авторизации из-за отсутствия или недопустимого утверждения авторизации.	Происходит при copyAuthorization изменении полезных данных или содержимого copyAuthorization из API. Убедитесь, что полезные данные в точности соответствуют содержимому, возвращенному из предыдущего вызова copyAuthorization.
Не удалось получить метаданные авторизации.	Указывает, что полезные данные copyAuthorization повторно используются с запросом на копирование. Запрос копирования, который успешно завершается, не разрешает дальнейшие запросы, использующие те же copyAuthorization полезные данные. Если вы создаете отдельную ошибку, а затем повторите попытку копирования с той же полезной нагрузкой авторизации, эта ошибка возникает. Решение: создайте новые полезные данные copyAuthorization, а затем повторно выполните запрос на копирование.
Запрос на передачу данных не допускается, так как он снижается до менее безопасной схемы защиты данных.	Возникает при копировании между ресурсом с поддержкой AEK и ресурсом без поддержки AEK. Чтобы разрешить копирование зашифрованной модели в целевой объект как незашифрованный, укажите x-ms-forms-copy-degrade: true заголовок с запросом копирования.
"Не удалось получить сведения о когнитивном ресурсе с идентификатором...".	Означает, что ресурс Azure, указанный параметром targetResourceId, не является допустимым ресурсом Cognitive или не существует. Чтобы устранить эту проблему, проверьте и повторно выполните запрос на копирование. Убедитесь, что ресурс действителен и существует в указанном регионе, например, westus2

Следующие шаги

В этом руководстве вы узнали, как использовать API копирования для резервного копирования пользовательских моделей в дополнительный ресурс Аналитики документов. Затем изучите справочные документы ПО API, чтобы узнать, что еще можно сделать с помощью аналитики документов.

• Справочная документация по REST API