Com a API Vision, é possível detectar e transcrever textos de arquivos PDF e TIFF armazenados no Cloud Storage.
Solicite a detecção de texto em documentos de PDF e TIFF usando a função
files:asyncBatchAnnotate
, que executa uma solicitação off-line (assíncrona)
e fornece o status usando recursos operations
.
A saída de uma solicitação em PDF/TIFF é gravada em um arquivo JSON criado no bucket do Cloud Storage especificado.
Limitações
A API do Vision aceita arquivos PDF/TIFF de até 2.000 páginas. Arquivos maiores retornarão um erro.
Authentication
As chaves de API não são compatíveis com solicitações files:asyncBatchAnnotate
. Consulte
Como usar uma conta de serviço para receber
instruções sobre a autenticação com uma conta de serviço.
A conta usada para autenticação precisa ter acesso ao bucket do
Cloud Storage especificado para a saída (roles/editor
,
roles/storage.objectCreator
ou superior).
É possível usar uma chave de API para consultar o status da operação. Para ver instruções, consulte Como usar uma chave de API.
Solicitações de detecção de texto em documento
No momento, a detecção de documentos em PDF/TIFF está disponível apenas para arquivos armazenados em buckets do Cloud Storage. Os arquivos JSON de resposta são salvos de maneira semelhante em um bucket do Cloud Storage.
REST
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- CLOUD_STORAGE_BUCKET: um bucket/diretório
do Cloud Storage para salvar arquivos de saída, expresso no seguinte formato:
gs://bucket/directory/
- CLOUD_STORAGE_FILE_URI: o caminho para um arquivo válido
(PDF/TIFF) em um bucket do Cloud Storage. Você precisa ter, pelo menos, privilégios de leitura
para o arquivo.
Exemplo:
gs://cloud-samples-data/vision/pdf_tiff/census2010.pdf
- FEATURE_TYPE: um tipo de recurso válido.
Para solicitações
files:asyncBatchAnnotate
, use os seguintes tipos de recursos:DOCUMENT_TEXT_DETECTION
TEXT_DETECTION
- PROJECT_ID pelo ID do projeto no Google Cloud.
Considerações específicas de campo:
inputConfig
: substitui o campoimage
usado em outras solicitações da API do Vision. Contém dois campos filhos:gcsSource.uri
: o URI do Google Cloud Storage do arquivo PDF ou TIFF (acessível ao usuário ou à conta de serviço que faz a solicitação).mimeType
: um dos tipos de arquivo aceitos (application/pdf
ouimage/tiff
)
outputConfig
: especifica os detalhes de saída. Contém dois campos filhos:gcsDestination.uri
- um URI válido do Google Cloud Storage. O bucket precisa ser gravável pelo usuário ou pela conta de serviço que faz a solicitação. O nome do arquivo seráoutput-x-to-y
, em quex
ey
representam os números de páginas em PDF/TIFF incluídos nesse arquivo de saída. Se o arquivo existir, o conteúdo dele será sobrescrito.batchSize
: especifica quantas páginas de saída precisam ser incluídas em cada arquivo JSON de saída.
Método HTTP e URL:
POST https://vision.googleapis.com/v1/files:asyncBatchAnnotate
Corpo JSON da solicitação:
{ "requests":[ { "inputConfig": { "gcsSource": { "uri": "CLOUD_STORAGE_FILE_URI" }, "mimeType": "application/pdf" }, "features": [ { "type": "FEATURE_TYPE" } ], "outputConfig": { "gcsDestination": { "uri": "CLOUD_STORAGE_BUCKET" }, "batchSize": 1 } } ] }
Para enviar a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo com o nome request.json
e execute o comando a seguir:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://vision.googleapis.com/v1/files:asyncBatchAnnotate"
PowerShell
Salve o corpo da solicitação em um arquivo com o nome request.json
e execute o comando a seguir:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://vision.googleapis.com/v1/files:asyncBatchAnnotate" | Select-Object -Expand Content
Uma solicitação asyncBatchAnnotate
bem-sucedida retorna uma resposta com um único campo de
nome:
{ "name": "projects/usable-auth-library/operations/1efec2285bd442df" }
Esse nome representa uma operação de longa duração com um ID associado
(por exemplo, 1efec2285bd442df
), que pode ser consultado usando a API v1.operations
.
Para recuperar a resposta de anotação do Vision, envie uma solicitação GET para o
endpoint v1.operations
, transmitindo o ID da operação no URL.
GET https://vision.googleapis.com/v1/operations/operation-id
Exemplo:
curl -X GET -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json" \ https://vision.googleapis.com/v1/projects/project-id/locations/location-id/operations/1efec2285bd442df
Se a operação estiver em andamento:
{ "name": "operations/1efec2285bd442df", "metadata": { "@type": "type.googleapis.com/google.cloud.vision.v1.OperationMetadata", "state": "RUNNING", "createTime": "2019-05-15T21:10:08.401917049Z", "updateTime": "2019-05-15T21:10:33.700763554Z" } }
Quando a operação for concluída, state
será exibido como DONE
e os
resultados serão gravados no arquivo do Google Cloud Storage especificado:
{ "name": "operations/1efec2285bd442df", "metadata": { "@type": "type.googleapis.com/google.cloud.vision.v1.OperationMetadata", "state": "DONE", "createTime": "2019-05-15T20:56:30.622473785Z", "updateTime": "2019-05-15T20:56:41.666379749Z" }, "done": true, "response": { "@type": "type.googleapis.com/google.cloud.vision.v1.AsyncBatchAnnotateFilesResponse", "responses": [ { "outputConfig": { "gcsDestination": { "uri": "gs://your-bucket-name/folder/" }, "batchSize": 1 } } ] } }
O JSON no arquivo de saída é semelhante ao de uma imagem
[solicitação de detecção de texto do documento](/vision/docs/ocr), com um
campo context
mostrando o local do PDF ou TIFF especificado e
o número de páginas no arquivo:
output-1-to-1.json
Go
Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido do Vision: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API VisionGo.
Para autenticar no Vision, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido da API Vision: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vision para Java.
Node.js
Antes de testar esta amostra, siga as instruções de configuração do Node.js no Guia de início rápido do Vision: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API VisionNode.js.
Para autenticar no Vision, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do Vision: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API VisionPython.
Para autenticar no Vision, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
gcloud
O comando gcloud
que você usa depende do tipo de arquivo.
Para realizar a detecção de texto em PDF, use o comando
gcloud ml vision detect-text-pdf
como mostrado no exemplo a seguir:gcloud ml vision detect-text-pdf gs://my_bucket/input_file gs://my_bucket/out_put_prefix
Para executar a detecção de texto em TIFF, use o comando
gcloud ml vision detect-text-tiff
como mostrado no exemplo a seguir:gcloud ml vision detect-text-tiff gs://my_bucket/input_file gs://my_bucket/out_put_prefix
Outras linguagens
C#: Siga as Instruções de configuração do C# na página das bibliotecas de cliente e acesse a Documentação de referência do Vision para .NET.
PHP: Siga as Instruções de configuração do PHP na página das bibliotecas de cliente e acesse a Documentação de referência do Vision para PHP.
Ruby: Siga as Instruções de configuração do Ruby na página das bibliotecas de cliente e acesse a Documentação de referência do Vision para Ruby.
Suporte multirregional
Já é possível especificar o armazenamento de dados e o processamento de OCR em nível de continente. Estas regiões são compatíveis:
us
: somente nos EUAeu
: União Europeia
Locais
O Cloud Vision oferece controle sobre onde os recursos do projeto são armazenados e processados. Especificamente, é possível configurar o Cloud Vision para armazenar e processar os dados somente na União Europeia.
Por padrão, o Cloud Vision armazena e processa recursos em um local global, o que significa que o Cloud Vision não garante que os recursos permanecerão em um determinado local ou região. Se você escolher a União Europeia como local, o Google armazenará os dados e os processará somente na União Europeia. Você e seus usuários podem acessar os dados de qualquer local.
Como definir o local usando a API
A API Vision aceita um endpoint de API global (vision.googleapis.com
), bem
como dois endpoints baseados em região: um endpoint da União Europeia
(eu-vision.googleapis.com
) e
um endpoint dos Estados Unidos (us-vision.googleapis.com
). Use esses endpoints para processamento específico da
região. Por exemplo, para armazenar e processar os dados somente na União Europeia, use o
URI eu-vision.googleapis.com
no lugar de vision.googleapis.com
para as chamadas da API REST:
- https://eu-vision.googleapis.com/v1/projects/PROJECT_ID/locations/eu/images:annotate
- https://eu-vision.googleapis.com/v1/projects/PROJECT_ID/locations/eu/images:asyncBatchAnnotate
- https://eu-vision.googleapis.com/v1/projects/PROJECT_ID/locations/eu/files:annotate
- https://eu-vision.googleapis.com/v1/projects/PROJECT_ID/locations/eu/files:asyncBatchAnnotate
Para armazenar e processar seus dados somente nos Estados Unidos, use o endpoint dos EUA
(us-vision.googleapis.com
) com os métodos anteriores.
Como definir o local usando as bibliotecas de cliente
Por padrão, as bibliotecas cliente da API Vision acessam o endpoint global da API
(vision.googleapis.com
). Para armazenar e processar os dados somente na
União Europeia, você precisa definir explicitamente o endpoint
(eu-vision.googleapis.com
). Os exemplos de código abaixo mostram como definir
essa configuração.
REST
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- REGION_ID: um dos identificadores de local
regionais válidos:
us
: somente nos EUAeu
: União Europeia
- CLOUD_STORAGE_IMAGE_URI: o caminho para um arquivo de imagem
válido em um bucket do Cloud Storage. Você precisa ter, pelo menos, privilégios de leitura para o arquivo.
Exemplo:
gs://cloud-samples-data/vision/pdf_tiff/census2010.pdf
- CLOUD_STORAGE_BUCKET: um bucket/diretório
do Cloud Storage para salvar arquivos de saída, expresso no seguinte formato:
gs://bucket/directory/
- FEATURE_TYPE: um tipo de recurso válido.
Para solicitações
files:asyncBatchAnnotate
, use os seguintes tipos de recursos:DOCUMENT_TEXT_DETECTION
TEXT_DETECTION
- PROJECT_ID pelo ID do projeto no Google Cloud.
Considerações específicas de campo:
inputConfig
: substitui o campoimage
usado em outras solicitações da API do Vision. Contém dois campos filhos:gcsSource.uri
: o URI do Google Cloud Storage do arquivo PDF ou TIFF (acessível ao usuário ou à conta de serviço que faz a solicitação).mimeType
: um dos tipos de arquivo aceitos (application/pdf
ouimage/tiff
)
outputConfig
: especifica os detalhes de saída. Contém dois campos filhos:gcsDestination.uri
- um URI válido do Google Cloud Storage. O bucket precisa ser gravável pelo usuário ou pela conta de serviço que faz a solicitação. O nome do arquivo seráoutput-x-to-y
, em quex
ey
representam os números de páginas em PDF/TIFF incluídos nesse arquivo de saída. Se o arquivo existir, o conteúdo dele será sobrescrito.batchSize
: especifica quantas páginas de saída precisam ser incluídas em cada arquivo JSON de saída.
Método HTTP e URL:
POST https://REGION_ID-vision.googleapis.com/v1/projects/PROJECT_ID/locations/REGION_ID/files:asyncBatchAnnotate
Corpo JSON da solicitação:
{ "requests":[ { "inputConfig": { "gcsSource": { "uri": "CLOUD_STORAGE_IMAGE_URI" }, "mimeType": "application/pdf" }, "features": [ { "type": "FEATURE_TYPE" } ], "outputConfig": { "gcsDestination": { "uri": "CLOUD_STORAGE_BUCKET" }, "batchSize": 1 } } ] }
Para enviar a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo com o nome request.json
e execute o comando a seguir:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://REGION_ID-vision.googleapis.com/v1/projects/PROJECT_ID/locations/REGION_ID/files:asyncBatchAnnotate"
PowerShell
Salve o corpo da solicitação em um arquivo com o nome request.json
e execute o comando a seguir:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://REGION_ID-vision.googleapis.com/v1/projects/PROJECT_ID/locations/REGION_ID/files:asyncBatchAnnotate" | Select-Object -Expand Content
Uma solicitação asyncBatchAnnotate
bem-sucedida retorna uma resposta com um único campo de
nome:
{ "name": "projects/usable-auth-library/operations/1efec2285bd442df" }
Esse nome representa uma operação de longa duração com um ID associado
(por exemplo, 1efec2285bd442df
), que pode ser consultado usando a API v1.operations
.
Para recuperar a resposta de anotação do Vision, envie uma solicitação GET para o
endpoint v1.operations
, transmitindo o ID da operação no URL.
GET https://vision.googleapis.com/v1/operations/operation-id
Exemplo:
curl -X GET -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json" \ https://vision.googleapis.com/v1/projects/project-id/locations/location-id/operations/1efec2285bd442df
Se a operação estiver em andamento:
{ "name": "operations/1efec2285bd442df", "metadata": { "@type": "type.googleapis.com/google.cloud.vision.v1.OperationMetadata", "state": "RUNNING", "createTime": "2019-05-15T21:10:08.401917049Z", "updateTime": "2019-05-15T21:10:33.700763554Z" } }
Quando a operação for concluída, state
será exibido como DONE
e os
resultados serão gravados no arquivo do Google Cloud Storage especificado:
{ "name": "operations/1efec2285bd442df", "metadata": { "@type": "type.googleapis.com/google.cloud.vision.v1.OperationMetadata", "state": "DONE", "createTime": "2019-05-15T20:56:30.622473785Z", "updateTime": "2019-05-15T20:56:41.666379749Z" }, "done": true, "response": { "@type": "type.googleapis.com/google.cloud.vision.v1.AsyncBatchAnnotateFilesResponse", "responses": [ { "outputConfig": { "gcsDestination": { "uri": "gs://your-bucket-name/folder/" }, "batchSize": 1 } } ] } }
O JSON no arquivo de saída é semelhante ao da resposta de
detecção de texto do documento
da imagem se você usou o recurso DOCUMENT_TEXT_DETECTION
ou a resposta de
detecção de texto
se você usou o recurso TEXT_DETECTION
. A saída terá um campo
context
extra que mostra o local do PDF ou TIFF especificado e o número de páginas no arquivo:
output-1-to-1.json
Go
Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido do Vision: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API VisionGo.
Para autenticar no Vision, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido da API Vision: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vision para Java.
Node.js
Antes de testar esta amostra, siga as instruções de configuração do Node.js no Guia de início rápido do Vision: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API VisionNode.js.
Para autenticar no Vision, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do Vision: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API VisionPython.
Para autenticar no Vision, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Faça um teste
Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho da API Cloud Vision em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.
Faça uma avaliação gratuita da API Cloud Vision