Анализ пакетной аналитики документов

API пакетного анализа позволяет выполнять массовую обработку до 10 000 документов с помощью одного запроса. Вместо анализа документов по одному и отслеживания соответствующих идентификаторов запросов вы можете одновременно анализировать коллекцию документов, таких как счета, кредитные документы или пользовательские документы. Входные документы должны храниться в контейнере хранилища BLOB-объектов Azure. После обработки документов API записывает результаты в указанный контейнер хранилища.

Ограничения пакетного анализа

Максимальное количество файлов документов, которые могут находиться в одном пакетном запросе, составляет 10 000.
Результаты пакетной операции сохраняются в течение 24 часов после завершения. Состояние пакетной операции больше не доступно через 24 часа после завершения пакетной обработки. Входные документы и соответствующие файлы результатов остаются в предоставленных контейнерах хранилища.

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

Активная подписка Azure. Если у вас нет подписки Azure, создайте ее бесплатно.
Ресурс Azure аналитики документов: после получения подписки Azure создайте ресурс аналитики документов на портале Azure. Вы можете использовать бесплатную ценовую категорию (F0), чтобы попробовать службу. После развертывания ресурса выберите "Перейти к ресурсу" , чтобы получить ключ и конечную точку. Вам потребуется ключ ресурса и конечная точка для подключения приложения к службе аналитики документов. Эти значения также можно найти на странице "Ключи" и "Конечная точка " на портале Azure.
Учетная запись хранилища Azure Blob. Создайте два контейнера в учетной записи хранения BLOB-объектов Azure для исходных и результирующих файлов:
- Исходный контейнер: в этом контейнере вы отправляете файлы документов для анализа.
- Контейнер результатов: это контейнер, где хранятся результаты из API пакетного анализа.

Авторизация контейнера хранилища

Чтобы РАЗРЕШИТЬ API обрабатывать документы и записывать результаты в контейнерах хранилища Azure, необходимо авторизоваться с помощью одного из следующих двух вариантов:

✔️ Управляемое удостоверение. Управляемое удостоверение — это субъект-служба, создающий удостоверение Microsoft Entra и определенные разрешения для управляемого ресурса Azure. Управляемые удостоверения позволяют запускать приложение Аналитики документов без необходимости внедрения учетных данных в код, более безопасный способ предоставления доступа к данным хранилища без включения маркеров подписи (SAS) в код.

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

Внимание

При использовании управляемых удостоверений не включайте URL-адрес маркера SAS с HTTP-запросами. Использование управляемых удостоверений заменяет требование для включения маркеров подписанных URL-адресов (SAS).

✔️ Подписанный URL-адрес (SAS). Подписанный URL-адрес — это URL-адрес, предоставляющий ограниченный доступ к контейнеру хранилища. Чтобы использовать этот метод, создайте маркеры подписанного URL-адреса (SAS) для исходных и результирующих контейнеров. Перейдите к контейнеру хранилища на портале Azure и выберите "Маркеры общего доступа" , чтобы создать маркер SAS и URL-адрес.

Исходный контейнер или большой двоичный объект должен назначать разрешения на чтение, запись, список и удаление.
Контейнер результатов или большой двоичный объект должны назначить разрешения на запись, список, удаление.

Снимок экрана: поля разрешений SAS на портале Azure.

Ознакомьтесь с разделом "Создание маркеров SAS" , чтобы узнать больше о создании маркеров SAS и их работе.

Вызов API пакетного анализа

1. Указание входных файлов

Пакетный API поддерживает два варианта указания обрабатываемого файла.

Если вы хотите обработать все файлы в контейнере или папке, а количество файлов меньше 10000, используйте azureBlobSource объект в запросе.

POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30

{
  "azureBlobSource": {
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken"

},
{
   "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
   "resultPrefix": "trainingDocsResult/"
}

Если вы не хотите обрабатывать все файлы в контейнере или папке, а скорее конкретные файлы в этом контейнере или папке, используйте azureBlobFileListSource объект. Для этой операции требуется JSONL-файл списка файлов, который перечисляет обрабатываемые файлы. Сохраните JSONL-файл в корневой папке контейнера. Ниже приведен пример JSONL-файла с двумя файлами, перечисленными ниже.
```
{"file": "Adatum Corporation.pdf"}
{"file": "Best For You Organics Company.pdf"}
```

Используйте файл списка JSONL файлов со следующими условиями:

Когда необходимо обработать определенные файлы вместо всех файлов в контейнере;
Если общее количество файлов в входном контейнере или папке превышает ограничение пакетной обработки 10 000 файлов;
Если требуется больше контроля над тем, какие файлы обрабатываются в каждом пакетном запросе;

POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30

{
  "azureBlobFileListSource": {
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
    "fileList": "myFileList.jsonl"
    ...
  },
  ...
}

В обоих вариантах требуется URL-адрес контейнера или URL-адрес SAS контейнера. Используйте URL-адрес контейнера, если используется управляемое удостоверение для доступа к контейнеру хранилища. Если вы используете подписанный URL-адрес (SAS), используйте URL-адрес SAS.

2. Укажите расположение результатов

Укажите URL-адрес контейнера хранилища BLOB-объектов Azure (или URL-адрес SAS контейнера) для хранения результатов с помощью resultContainerURL параметра. Рекомендуется использовать отдельные контейнеры для источника и результатов, чтобы предотвратить случайное перезаписи.
overwriteExisting Задайте логическое свойство False и предотвратите перезапись существующих результатов для одного документа. Если вы хотите перезаписать все существующие результаты, задайте логическое значение True. Плата за обработку документа по-прежнему взимается, даже если существующие результаты не перезаписаны.
Используется resultPrefix для группировки и хранения результатов в определенной папке контейнера.

3. Создание и запуск запроса POST

Не забудьте заменить приведенные ниже примеры значений URL-адреса контейнера реальными значениями из контейнеров хранилища BLOB-объектов Azure.

В этом примере показан запрос POST с azureBlobSource входными данными

POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30

{
  "azureBlobSource": {
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
    "prefix": "inputDocs/"
  },
  {
  "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
  "resultPrefix": "batchResults/",
  "overwriteExisting": true
}

В этом примере показан запрос POST и azureBlobFileListSource входные данные списка файлов

POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30

{
   "azureBlobFileListSource": {
      "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
      "fileList": "myFileList.jsonl"
    },
{
  "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
  "resultPrefix": "batchResults/",
  "overwriteExisting": true
}

Ниже приведен пример успешного ответа

202 Accepted
Operation-Location: /documentintelligence/documentModels/{modelId}/analyzeBatchResults/{resultId}?api-version=2024-11-30

4. Получение результатов API

GET Используйте операцию для получения результатов пакетного анализа после выполнения операции POST. Операция GET получает сведения о состоянии, процент завершения пакетной службы и создание и обновление даты и времени обновления. Эти сведения сохраняются только через 24 часа после завершения пакетного анализа.

GET {endpoint}/documentintelligence/documentModels/{modelId}/analyzeBatchResults/{resultId}?api-version=2024-11-30
200 OK

{
  "status": "running",      // notStarted, running, completed, failed
  "percentCompleted": 67,   // Estimated based on the number of processed documents
  "createdDateTime": "2021-09-24T13:00:46Z",
  "lastUpdatedDateTime": "2021-09-24T13:00:49Z"
...
}

5. Интерпретация сообщений о состоянии

Для каждого обработанного документа назначается состояние либо succeeded, либо .failedrunningnotStartedskipped Предоставляется ИСХОДНЫй URL-адрес, являющийся контейнером хранилища BLOB-объектов источника для входного документа.

Состояние notStarted или running. Операция пакетного анализа не инициируется или не завершена. Дождитесь завершения операции для всех документов.
Состояние completed. Операция пакетного анализа завершена.

Состояние succeeded. Пакетная операция прошла успешно, и был обработан входной документ. Результаты доступны resultUrlпо адресу , который создается путем resultContainerUrlобъединения , resultPrefixinput filenameи .ocr.json расширения. Свойство имеет только файлы, успешно выполненные resultUrl.

succeeded Пример ответа состояния:

{
    "resultId": "myresultId-",
    "status": "succeeded",
    "percentCompleted": 100,
    "createdDateTime": "2025-01-01T00:00:000",
    "lastUpdatedDateTime": "2025-01-01T00:00:000",
    "result": {
        "succeededCount": 10,000,
        "failedCount": 0,
        "skippedCount": 0,
        "details": [
            {
                "sourceUrl": "https://{your-source-container}/inputFolder/document1.pdf",
                "resultUrl": "https://{your-result-container}/resultsFolder/document1.pdf.ocr.json",
                "status": "succeeded"
            },
          ...
            {
                "sourceUrl": "https://{your-source-container}/inputFolder/document10000.pdf",
                "resultUrl": "https://{your-result-container}/resultsFolder/document10000.pdf.ocr.json",
                "status": "succeeded"
            }
       ]

     }
}

Состояние failed. Эта ошибка возвращается только в случае возникновения ошибок в общем пакетном запросе. После запуска операции пакетного анализа состояние отдельной операции документа не влияет на состояние общего пакетного задания, даже если все файлы имеют состояние failed.

failed Пример ответа состояния:
```
[
    "result": {
    "succeededCount": 0,
    "failedCount": 2,
    "skippedCount": 0,
    "details": [
        "sourceUrl": "https://{your-source-container}/inputFolder/document1.jpg",
        "status": "failed",
        "error": {
            "code": "InvalidArgument",
            "message": "Invalid argument.",
            "innererror": {
              "code": "InvalidSasToken",
              "message": "The shared access signature (SAS) is invalid: {details}"
                }
            }
        ]
    }
]
...
```
Состояние skipped: обычно это состояние происходит, когда выходные данные для документа уже присутствуют в указанной выходной папке, а overwriteExisting логическое свойство имеет значение false.

skipped Пример ответа состояния:
```
[
     "result": {
     "succeededCount": 3,
     "failedCount": 0,
     "skippedCount": 2,
     "details": [
         ...
         "sourceUrl": "https://{your-source-container}/inputFolder/document1.pdf",
         "status": "skipped",
         "error": {
             "code": "OutputExists",
             "message": "Analysis skipped because result file https://{your-result-container}/resultsFolder/document1.pdf.ocr.json already exists."
              }
         ]
     }
]
...
```
Примечание.

Результаты анализа не возвращаются для отдельных файлов до завершения анализа для всего пакета. Чтобы отслеживать подробный ход выполнения, percentCompletedвы можете отслеживать *.ocr.json файлы по мере их записи в resultContainerUrl.

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

Просмотр примеров кода на GitHub.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-05-18