A API Vision pode detetar e transcrever texto de ficheiros PDF e TIFF armazenados no Cloud Storage.
A deteção de texto de documentos PDF e TIFF tem de ser pedida através da função files:asyncBatchAnnotate
, que executa um pedido offline (assíncrono) e fornece o respetivo estado através dos recursos operations
.
A saída de um pedido PDF/TIFF é escrita num ficheiro JSON criado no contentor do Cloud Storage especificado.
Limitações
A API Vision aceita ficheiros PDF/TIFF com até 2000 páginas. Os ficheiros maiores vão devolver um erro.
Autenticação
As chaves API não são suportadas para pedidos files:asyncBatchAnnotate
. Consulte o artigo
Usar uma conta de serviço para ver
instruções sobre a autenticação com uma conta de serviço.
A conta usada para a autenticação tem de ter acesso ao contentor do Cloud Storage que especificar para a saída (roles/editor
ou roles/storage.objectCreator
ou superior).
Pode usar uma chave da API para consultar o estado da operação. Consulte as instruções em Usar uma chave da API.
Pedidos de deteção de texto em documentos
Atualmente, a deteção de documentos PDF/TIFF só está disponível para ficheiros armazenados em contentores do Cloud Storage. Os ficheiros JSON de resposta são guardados de forma semelhante num contentor do Cloud Storage.

gs://cloud-samples-data/vision/pdf_tiff/census2010.pdf
,
Fonte:
United States
Census Bureau.
REST
Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:
- CLOUD_STORAGE_BUCKET: Um contentor/diretório do Cloud Storage
para guardar os ficheiros de saída, expresso no seguinte formato:
gs://bucket/directory/
- CLOUD_STORAGE_FILE_URI: o caminho para um ficheiro (PDF/TIFF) válido num contentor do Cloud Storage. Tem de ter, pelo menos, privilégios de leitura para
o ficheiro.
Exemplo:
gs://cloud-samples-data/vision/pdf_tiff/census2010.pdf
- FEATURE_TYPE: um tipo de funcionalidade válido.
Para pedidos
files:asyncBatchAnnotate
, pode usar os seguintes tipos de funcionalidades:DOCUMENT_TEXT_DETECTION
TEXT_DETECTION
- PROJECT_ID: o ID do seu Google Cloud projeto.
Considerações específicas do campo:
inputConfig
: substitui o campoimage
usado noutros pedidos da API Vision. Contém dois campos secundários:gcsSource.uri
: o URI do Google Cloud Storage do ficheiro PDF ou TIFF (acessível ao utilizador ou à conta de serviço que está a fazer o pedido).mimeType
: um dos tipos de ficheiros aceites:application/pdf
ouimage/tiff
.
outputConfig
: especifica os detalhes da saída. Contém dois campos filho:gcsDestination.uri
– um URI do Google Cloud Storage válido. O contentor tem de ser gravável pelo utilizador ou pela conta de serviço que está a fazer o pedido. O nome do ficheiro éoutput-x-to-y
, em quex
ey
representam os números de páginas PDF/TIFF incluídos nesse ficheiro de saída. Se o ficheiro existir, o respetivo conteúdo é substituído.batchSize
- especifica quantas páginas de saída devem ser incluídas em cada ficheiro JSON de saída.
Método HTTP e URL:
POST https://vision.googleapis.com/v1/files:asyncBatchAnnotate
Corpo JSON do pedido:
{ "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 o seu pedido, escolha uma destas opções:
curl
Guarde o corpo do pedido num ficheiro com o nome request.json
,
e execute o seguinte comando:
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
Guarde o corpo do pedido num ficheiro com o nome request.json
,
e execute o seguinte comando:
$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
Um pedido asyncBatchAnnotate
bem-sucedido devolve uma resposta com um único campo de nome:
{ "name": "projects/usable-auth-library/operations/1efec2285bd442df" }
Este nome representa uma operação de longa duração com um ID associado (por exemplo, 1efec2285bd442df
), que pode ser consultado através da API v1.operations
.
Para obter a resposta de anotação do Vision, envie um pedido GET para o ponto final v1.operations
, transmitindo o ID da operação no URL:
GET https://vision.googleapis.com/v1/operations/operation-id
Por 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 curso:
{ "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 estiver concluída, o state
é apresentado como DONE
e os seus resultados são escritos no ficheiro do Google Cloud Storage que especificou:
{ "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 seu ficheiro de saída é semelhante ao de um [pedido de deteção de texto de documento](/vision/docs/ocr) de uma imagem, com a adição de um campo context
que mostra a localização do PDF ou TIFF especificado e o número de páginas no ficheiro:
output-1-to-1.json
Go
Antes de experimentar este exemplo, siga as Goinstruções de configuração no início rápido do Vision usando bibliotecas cliente. Para mais informações, consulte a documentação de referência da API Go Vision.
Para se autenticar no Vision, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Java
Antes de experimentar este exemplo, siga as instruções de configuração do Java no guia de início rápido da API Vision com as bibliotecas cliente. Para mais informações, consulte a documentação de referência da API Vision Java.
Node.js
Antes de experimentar este exemplo, siga as Node.jsinstruções de configuração no início rápido do Vision usando bibliotecas cliente. Para mais informações, consulte a documentação de referência da API Node.js Vision.
Para se autenticar no Vision, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Python
Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do Vision usando bibliotecas cliente. Para mais informações, consulte a documentação de referência da API Python Vision.
Para se autenticar no Vision, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
gcloud
O comando gcloud
que usa depende do tipo de ficheiro.
Para realizar a deteção de texto em PDF, use o comando
gcloud ml vision detect-text-pdf
conforme mostrado no exemplo seguinte:gcloud ml vision detect-text-pdf gs://my_bucket/input_file gs://my_bucket/out_put_prefix
Para realizar a deteção de texto TIFF, use o comando
gcloud ml vision detect-text-tiff
, conforme mostrado no exemplo seguinte:gcloud ml vision detect-text-tiff gs://my_bucket/input_file gs://my_bucket/out_put_prefix
Idiomas adicionais
C#: Siga as instruções de configuração do C# na página das bibliotecas cliente e, em seguida, visite 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 cliente e, em seguida, visite 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 cliente e, em seguida, visite a documentação de referência do Vision para Ruby.
Suporte multirregional
Agora, pode especificar o armazenamento de dados e o tratamento de OCR ao nível do continente. As seguintes regiões são atualmente suportadas:
us
: apenas no país EUAeu
: A União Europeia
Localizações
O Cloud Vision oferece-lhe algum controlo sobre onde os recursos do seu projeto são armazenados e processados. Em particular, pode configurar o Cloud Vision para armazenar e processar os seus dados apenas na União Europeia.
Por predefinição, o Cloud Vision armazena e processa recursos numa localização global, o que significa que o Cloud Vision não garante que os seus recursos permaneçam numa localização ou região específica. Se escolher a localização União Europeia, a Google armazena os seus dados e processa-os apenas na União Europeia. Pode aceder aos dados, bem como os seus utilizadores, a partir de qualquer localização.
Definir a localização através da API
A API Vision suporta um ponto final da API global (vision.googleapis.com
) e também
dois pontos finais baseados em regiões: um ponto final da União Europeia
(eu-vision.googleapis.com
) e um ponto final dos Estados Unidos (us-vision.googleapis.com
). Use estes pontos finais para o processamento
específico da região. Por exemplo, para armazenar e tratar os seus dados apenas na União Europeia, use o URI eu-vision.googleapis.com
em vez de vision.googleapis.com
para as suas 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 os seus dados apenas nos Estados Unidos, use o ponto final dos EUA
(us-vision.googleapis.com
) com os métodos anteriores.
Definir a localização através das bibliotecas de cliente
As bibliotecas cliente da API Vision acedem ao ponto final da API global
(vision.googleapis.com
) por predefinição. Para armazenar e processar os seus dados apenas na
União Europeia, tem de definir explicitamente o ponto final
(eu-vision.googleapis.com
). Os seguintes exemplos de código mostram como configurar
esta definição.
REST
Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:
- REGION_ID: um dos identificadores de localização regionais válidos:
us
: apenas no país EUAeu
: A União Europeia
- CLOUD_STORAGE_IMAGE_URI: o caminho para um ficheiro de imagem válido num contentor do Cloud Storage. Tem de ter, pelo menos, privilégios de leitura para o ficheiro.
Exemplo:
gs://cloud-samples-data/vision/pdf_tiff/census2010.pdf
- CLOUD_STORAGE_BUCKET: Um contentor/diretório do Cloud Storage
para guardar os ficheiros de saída, expresso no seguinte formato:
gs://bucket/directory/
- FEATURE_TYPE: um tipo de funcionalidade válido.
Para pedidos
files:asyncBatchAnnotate
, pode usar os seguintes tipos de funcionalidades:DOCUMENT_TEXT_DETECTION
TEXT_DETECTION
- PROJECT_ID: o ID do seu Google Cloud projeto.
Considerações específicas do campo:
inputConfig
: substitui o campoimage
usado noutros pedidos da API Vision. Contém dois campos secundários:gcsSource.uri
: o URI do Google Cloud Storage do ficheiro PDF ou TIFF (acessível ao utilizador ou à conta de serviço que está a fazer o pedido).mimeType
: um dos tipos de ficheiros aceites:application/pdf
ouimage/tiff
.
outputConfig
: especifica os detalhes da saída. Contém dois campos filho:gcsDestination.uri
– um URI do Google Cloud Storage válido. O contentor tem de ser gravável pelo utilizador ou pela conta de serviço que está a fazer o pedido. O nome do ficheiro éoutput-x-to-y
, em quex
ey
representam os números de páginas PDF/TIFF incluídos nesse ficheiro de saída. Se o ficheiro existir, o respetivo conteúdo é substituído.batchSize
- especifica quantas páginas de saída devem ser incluídas em cada ficheiro 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 do pedido:
{ "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 o seu pedido, escolha uma destas opções:
curl
Guarde o corpo do pedido num ficheiro com o nome request.json
,
e execute o seguinte comando:
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
Guarde o corpo do pedido num ficheiro com o nome request.json
,
e execute o seguinte comando:
$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
Um pedido asyncBatchAnnotate
bem-sucedido devolve uma resposta com um único campo de nome:
{ "name": "projects/usable-auth-library/operations/1efec2285bd442df" }
Este nome representa uma operação de longa duração com um ID associado (por exemplo, 1efec2285bd442df
), que pode ser consultado através da API v1.operations
.
Para obter a resposta de anotação do Vision, envie um pedido GET para o ponto final v1.operations
, transmitindo o ID da operação no URL:
GET https://vision.googleapis.com/v1/operations/operation-id
Por 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 curso:
{ "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 estiver concluída, o state
é apresentado como DONE
e os seus resultados são escritos no ficheiro do Google Cloud Storage que especificou:
{ "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 ficheiro de saída é semelhante ao de uma resposta de
deteção de texto em documentos
de uma imagem se tiver usado a funcionalidade DOCUMENT_TEXT_DETECTION
ou a resposta de
deteção de texto
se tiver usado a funcionalidade TEXT_DETECTION
. O resultado terá um campo context
adicional que mostra a localização do PDF ou TIFF especificado e o número de páginas no ficheiro:
output-1-to-1.json
Go
Antes de experimentar este exemplo, siga as Goinstruções de configuração no início rápido do Vision usando bibliotecas cliente. Para mais informações, consulte a documentação de referência da API Go Vision.
Para se autenticar no Vision, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Java
Antes de experimentar este exemplo, siga as instruções de configuração do Java no guia de início rápido da API Vision com as bibliotecas cliente. Para mais informações, consulte a documentação de referência da API Vision Java.
Node.js
Antes de experimentar este exemplo, siga as Node.jsinstruções de configuração no início rápido do Vision usando bibliotecas cliente. Para mais informações, consulte a documentação de referência da API Node.js Vision.
Para se autenticar no Vision, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Python
Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do Vision usando bibliotecas cliente. Para mais informações, consulte a documentação de referência da API Python Vision.
Para se autenticar no Vision, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Experimente
Se está a usar o Google Cloud pela primeira vez, crie uma conta para avaliar o desempenho da Cloud Vision API em cenários do mundo real. Os novos clientes também recebem 300 USD em créditos gratuitos para executar, testar e implementar cargas de trabalho.
Experimente a Cloud Vision API gratuitamente