Chamar a API de Leitura

Neste guia, você aprenderá a chamar a API de Leitura para extrair texto de imagens. Você aprenderá as diversas maneiras de configurar o comportamento dessa API para atender às suas necessidades.

Este guia pressupõe que você já criar um recurso de Pesquisa Visual computacional e obteve uma chave de assinatura e uma URL de ponto de extremidade. Se você ainda não fez isso, siga um início rápido para começar.

Determinar como processar os dados (opcional)

Especificar o modelo de OCR

Por padrão, o serviço usará o modelo de GA mais recente para extrair texto. A partir da Leitura 3.2, um parâmetro model-version permite escolher entre o GA e modelos de versão prévia para uma determinada versão da API. O modelo especificado será usado para extrair texto com a operação de leitura.

Ao usar a operação de leitura, use os valores a seguir para o parâmetro model-version opcional.

Valor Modelo usado
Não fornecida modelo e linguagens GA mais recentes
mais recente modelo e linguagens GA mais recentes
2021-09-30-preview Versão prévia do modelo com os recursos e as linguagens de versão prévia adicionais. Inclui quaisquer aprimoramentos para o modelo de GA anterior.
2021-04-12 A GA específica de data, atualmente igual à versão mais recente

Linguagem de entrada

Por padrão, o serviço extrai todo o texto de suas imagens ou documentos, incluindo idiomas mistos. A operação de Leitura tem um parâmetro de solicitação opcional para o idioma. Forneça apenas um código de linguagem se quiser forçar o documento a ser processado como essa linguagem específica. Caso contrário, o serviço poderá retornar texto incompleto e incorreto.

Saída da ordem de leitura natural (somente idiomas latinos)

Por padrão, o serviço saída as linhas de texto na ordem da esquerda para a direita. Opcionalmente, como o parâmetro de solicitação readingOrder, use natural para uma saída de ordem de leitura mais amigável, conforme mostrado no exemplo a seguir. Esse recurso é compatível apenas com idiomas latinos.

Exemplo de ordem de Leitura de OCR

Selecionar páginas ou intervalos de página para extração de texto

Por padrão, o serviço extrai texto de todas as páginas nos documentos. Opcionalmente, use o parâmetro de solicitação pages para especificar números de página ou intervalos de página para extrair o texto apenas daquelas páginas. O exemplo a seguir mostra um documento com 10 páginas, com texto extraído para ambos os casos – todas as páginas (1-10) e páginas selecionadas (3-6).

Saída de páginas selecionadas

Enviar dados ao serviço

Você envia uma imagem local ou remota à API de Leitura. Para local, você coloca os dados da imagem binária no corpo da solicitação HTTP. Para remoto, especifique a URL da imagem formatando o corpo da solicitação da seguinte maneira: {"url":"http://example.com/images/test.jpg"}.

A Chamada de leitura da API de Leitura usa uma imagem ou documento PDF como entrada e extrai o texto de maneira assíncrona.

https://{endpoint}/vision/v3.2/read/analyze[?language][&pages][&readingOrder]

A chamada retorna com um campo de cabeçalho de resposta chamado Operation-Location. O valor Operation-Location é uma URL que contém a ID da Operação a ser usada na próxima etapa.

Cabeçalho de resposta Valor de exemplo
Operation-Location https://cognitiveservice/vision/v3.2/read/analyzeResults/49a36324-fc4b-4387-aa06-090cfbf0064f

Observação

Billing

A página de preços da Pesquisa Visual Computacional inclui o tipo de preço para Leitura. Cada imagem ou página analisada é uma transação. Se você chamar a operação com um documento PDF ou TIFF contendo 100 páginas, a operação de Leitura fará a contagem de 100 transações e você será cobrado por 100 transações. Caso tenha feito 50 chamadas para a operação e cada chamada tiver enviado um documento com 100 páginas, você será cobrado por 50 X 100 = 5000 transações.

Obter resultados do serviço

A segunda etapa é chamar a operação Obter Resultados de Leitura. Essa operação usa como entrada a ID da operação que foi criada pela operação de Leitura.

https://{endpoint}/vision/v3.2/read/analyzeResults/{operationId}

Ela retorna uma resposta JSON que contém um campo de status com os valores possíveis a seguir.

Valor Significado
notStarted A operação não foi iniciada.
running A operação está sendo processada.
failed A operação falhou.
succeeded Êxito na operação.

Execute uma chamada a essa operação de modo iterativo até que ela retorne o valor succeeded. Use um intervalo de um a dois segundos para evitar que a taxa de RPS (solicitações por segundo) seja excedida.

Observação

A camada gratuita limita a taxa de solicitação a 20 chamadas por minuto. A camada paga permite 10 RPS (solicitações por segundo) que podem ser aumentadas mediante solicitação. Anote o identificador e a região do recurso Azure e abra um tíquete no Suporte do Azure; ou entre em contato com sua equipe de conta para solicitar uma taxa de solicitação por segundo (RPS) maior.

Quando o campo status tiver o valor succeeded, a resposta JSON conterá o conteúdo de texto extraído da imagem ou do documento. A resposta JSON mantém os agrupamentos de linhas originais de palavras reconhecidas. Isso inclui as linhas de texto extraídas e as respectivas coordenadas da caixa delimitadora. Cada linha de texto inclui todas as palavras extraídas com as respectivas coordenadas e pontuações de confiança.

Observação

Os dados enviados para a operação Read são temporariamente criptografados e armazenados em repouso por um curto período e, depois, excluídos. Isso permite que os aplicativos recuperem o texto extraído como parte da resposta do serviço.

Saída JSON de exemplo

Confira o seguinte exemplo de uma resposta JSON bem-sucedida:

{
  "status": "succeeded",
  "createdDateTime": "2021-02-04T06:32:08.2752706+00:00",
  "lastUpdatedDateTime": "2021-02-04T06:32:08.7706172+00:00",
  "analyzeResult": {
    "version": "3.2",
    "readResults": [
      {
        "page": 1,
        "angle": 2.1243,
        "width": 502,
        "height": 252,
        "unit": "pixel",
        "lines": [
          {
            "boundingBox": [
              58,
              42,
              314,
              59,
              311,
              123,
              56,
              121
            ],
            "text": "Tabs vs",
            "appearance": {
              "style": {
                "name": "handwriting",
                "confidence": 0.96
              }
            },
            "words": [
              {
                "boundingBox": [
                  68,
                  44,
                  225,
                  59,
                  224,
                  122,
                  66,
                  123
                ],
                "text": "Tabs",
                "confidence": 0.933
              },
              {
                "boundingBox": [
                  241,
                  61,
                  314,
                  72,
                  314,
                  123,
                  239,
                  122
                ],
                "text": "vs",
                "confidence": 0.977
              }
            ]
          }
        ]
      }
    ]
  }
}

Classificação manuscrita para linhas de texto (somente idiomas latinos)

A resposta inclui classificar se cada linha de texto tem um estilo manuscrito ou não, junto com uma pontuação de confiança. Esse recurso é compatível apenas com idiomas latinos. O exemplo a seguir mostra a classificação manuscrita para o texto na imagem.

Exemplo de classificação de manuscrito de OCR

Próximas etapas