La API de Vision puede detectar y transcribir texto de archivos PDF y TIFF almacenados en Cloud Storage.
La detección de texto en documentos PDF y TIFF se debe solicitar mediante la función files:asyncBatchAnnotate
, que realiza una solicitud sin conexión (asíncrona) y proporciona su estado mediante los recursos operations
.
La salida de una solicitud de PDF o TIFF se escribe en un archivo JSON que se crea en el bucket de Cloud Storage especificado.
Limitaciones
La API de Vision acepta archivos PDF o TIFF de hasta 2,000 páginas. Los archivos más grandes mostrarán un error.
Authentication
Las claves de API no son compatibles con las solicitudes files:asyncBatchAnnotate
. Consulta Usa una cuenta de servicio si deseas obtener instrucciones sobre la autenticación con una cuenta de servicio.
La cuenta que se use en la autenticación debe tener acceso al bucket de Cloud Storage que especifiques para la salida (roles/editor
, roles/storage.objectCreator
o uno superior).
Puedes usar una clave de API a fin de consultar el estado de la operación. Consulta Usa una clave de API para obtener instrucciones.
Solicitudes de detección de texto en documentos
Por el momento, la detección en documentos PDF o TIFF solo está disponible para archivos almacenados en depósitos de Cloud Storage. Los archivos JSON de respuesta se guardan de manera similar en un bucket de Cloud Storage.
REST
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- CLOUD_STORAGE_BUCKET: Es un bucket o directorio de Cloud Storage para guardar archivos de salida, que se expresa de la siguiente manera:
gs://bucket/directory/
- CLOUD_STORAGE_FILE_URI: Es la ruta a un archivo válido (PDF/TIFF) en un bucket de Cloud Storage. Como mínimo, debes tener privilegios de lectura del archivo.
Ejemplo:
gs://cloud-samples-data/vision/pdf_tiff/census2010.pdf
- FEATURE_TYPE: Es un tipo de función válido.
Para las solicitudes
files:asyncBatchAnnotate
, puedes usar los siguientes tipos de funciones:DOCUMENT_TEXT_DETECTION
TEXT_DETECTION
- PROJECT_ID es el ID del proyecto de Google Cloud.
Consideraciones específicas del campo:
inputConfig
: Reemplaza el campoimage
que se usó en otras solicitudes a la API de Vision. Contiene dos campos secundarios:gcsSource.uri
: Es el URI de Google Cloud Storage del archivo PDF o TIFF (al que puede acceder el usuario o la cuenta de servicio que realiza la solicitud)mimeType
: Es uno de los tipos de archivo aceptados,application/pdf
oimage/tiff
.
outputConfig
: Especifica los detalles de la salida. Contiene dos campos secundarios:gcsDestination.uri
: Es un URI de Google Cloud Storage válido. El usuario o la cuenta de servicio que realiza la solicitud debe poder escribir el bucket. El nombre del archivo seráoutput-x-to-y
, en el quex
yy
representan los números de página del archivo PDF o TIFF que se incluyen en ese archivo de salida. Si existe un archivo, se sobrescribirán sus contenidos.batchSize
: Especifica cuántas páginas de salida se deben incluir en cada archivo JSON de salida.
Método HTTP y URL:
POST https://vision.googleapis.com/v1/files:asyncBatchAnnotate
Cuerpo JSON de la solicitud:
{ "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 tu solicitud, elige una de estas opciones:
curl
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente 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
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente 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
Una solicitud asyncBatchAnnotate
correcta muestra una respuesta con un solo campo de nombre:
{ "name": "projects/usable-auth-library/operations/1efec2285bd442df" }
Este nombre representa una operación de larga duración con un ID asociado (por ejemplo, 1efec2285bd442df
), que se puede consultar mediante la API de v1.operations
.
Para recuperar tu respuesta de anotación de Vision, envía una solicitud GET al extremo v1.operations
y pasa el ID de operación en la URL:
GET https://vision.googleapis.com/v1/operations/operation-id
Por ejemplo:
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
Si la operación se encuentra en curso, usa lo siguiente:
{ "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" } }
Una vez que la operación se completa, el state
se muestra como DONE
, y los resultados se escriben en el archivo de Google Cloud Storage que especificaste:
{ "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 } } ] } }
El JSON en el archivo de salida es similar a la [solicitud de detección de texto del documento](/vision/docs/ocr) de una imagen y, además, tiene un campo context
que muestra la ubicación del PDF o TIFF que se especificó y la cantidad de páginas en el archivo:
output-1-to-1.json
Go
Antes de probar este código de muestra, sigue las instrucciones de configuración para Go que se encuentran en la Guía de inicio rápido de Vision sobre cómo usar las bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Vision para Go.
Para autenticarte en Vision, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Java
Antes de probar este código de muestra, sigue las instrucciones de configuración para Java que se encuentran la Guía de inicio rápido de la API de Vision sobre cómo usar las bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Vision para Java.
Node.js
Antes de probar este código de muestra, sigue las instrucciones de configuración para Node.js que se encuentran en la Guía de inicio rápido de Vision sobre cómo usar las bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Vision para Node.js.
Para autenticarte en Vision, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Antes de probar este código de muestra, sigue las instrucciones de configuración para Python que se encuentran en la Guía de inicio rápido de Vision sobre cómo usar las bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Vision para Python.
Para autenticarte en Vision, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
gcloud
El comando de gcloud
que uses dependerá del tipo de archivo.
Si quieres realizar la detección de texto en PDF, usa el comando
gcloud ml vision detect-text-pdf
como se muestra en el siguiente ejemplo:gcloud ml vision detect-text-pdf gs://my_bucket/input_file gs://my_bucket/out_put_prefix
Si quieres realizar la detección de texto en TIFF, usa el comando
gcloud ml vision detect-text-tiff
como se muestra en el siguiente ejemplo:gcloud ml vision detect-text-tiff gs://my_bucket/input_file gs://my_bucket/out_put_prefix
Lenguajes adicionales
C#: sigue lasinstrucciones de configuración de C# en la página Bibliotecas cliente y, luego, visita la documentación de referencia de Vision para .NET.
PHP: sigue las instrucciones de configuración de PHP en la página Bibliotecas cliente y, luego, visita la documentación de referencia de Vision para PHP.
Ruby: sigue las instrucciones de configuración de Ruby en la página Bibliotecas cliente y, luego, visita la documentación de referencia de Vision para Ruby.
Compatibilidad multirregional
Ahora puedes especificar el almacenamiento de datos a nivel de continente y el procesamiento de OCR. En este momento, se admiten las siguientes regiones:
us
: Solo países de EE.UU.eu
: La Unión Europea
Ubicaciones
Cloud Vision te ofrece cierto control sobre dónde se almacenan y procesan los recursos de tu proyecto. En particular, puedes configurar Cloud Vision para almacenar y procesar los datos solo en la Unión Europea.
De forma predeterminada, Cloud Vision almacena y procesa recursos en una ubicación global, lo que significa que Cloud Vision no garantiza que tus recursos permanezcan dentro de una región o ubicación en particular. Si eliges la ubicación de la Unión Europea, Google almacenará los datos y solo se procesarán en esa ubicación. Tú y tus usuarios pueden acceder a los datos desde cualquier ubicación.
Configura la ubicación con la API
La API de Vision admite un extremo de API global (vision.googleapis.com
) y también dos extremos basados en regiones: un extremo de la Unión Europea (eu-vision.googleapis.com
) y un extremo de Estados Unidos (us-vision.googleapis.com
). Usa estos extremos para el procesamiento específico de la región. Por ejemplo, para almacenar y procesar los datos solo en la Unión Europea, usa el URI eu-vision.googleapis.com
en lugar de vision.googleapis.com
para las llamadas a la API de 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 almacenar y procesar tus datos solo en Estados Unidos, usa el extremo de EE. UU. (us-vision.googleapis.com
) con los métodos anteriores.
Configura la ubicación con las bibliotecas cliente
Las bibliotecas cliente de la API de Vision acceden al extremo global de la API (vision.googleapis.com
) de forma predeterminada. Para almacenar y procesar tus datos solo en la Unión Europea, debes establecer el extremo (eu-vision.googleapis.com
) de manera explícita. En las siguientes muestras de código, se muestra cómo establecer esta configuración.
REST
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- REGION_ID: Uno de los identificadores de ubicación
regional válidos:
us
: Solo países de EE.UU.eu
: La Unión Europea
- CLOUD_STORAGE_IMAGE_URI: La ruta a un archivo de imagen válido en un depósito de Cloud Storage. Como mínimo, debes tener privilegios de lectura en el archivo.
Ejemplo:
gs://cloud-samples-data/vision/pdf_tiff/census2010.pdf
- CLOUD_STORAGE_BUCKET: Es un bucket o directorio de Cloud Storage para guardar archivos de salida, que se expresa de la siguiente manera:
gs://bucket/directory/
- FEATURE_TYPE: Es un tipo de función válido.
Para las solicitudes
files:asyncBatchAnnotate
, puedes usar los siguientes tipos de funciones:DOCUMENT_TEXT_DETECTION
TEXT_DETECTION
- PROJECT_ID es el ID del proyecto de Google Cloud.
Consideraciones específicas del campo:
inputConfig
: Reemplaza el campoimage
que se usó en otras solicitudes a la API de Vision. Contiene dos campos secundarios:gcsSource.uri
: Es el URI de Google Cloud Storage del archivo PDF o TIFF (al que puede acceder el usuario o la cuenta de servicio que realiza la solicitud)mimeType
: Es uno de los tipos de archivo aceptados,application/pdf
oimage/tiff
.
outputConfig
: Especifica los detalles de la salida. Contiene dos campos secundarios:gcsDestination.uri
: Es un URI de Google Cloud Storage válido. El usuario o la cuenta de servicio que realiza la solicitud debe poder escribir el bucket. El nombre del archivo seráoutput-x-to-y
, en el quex
yy
representan los números de página del archivo PDF o TIFF que se incluyen en ese archivo de salida. Si existe un archivo, se sobrescribirán sus contenidos.batchSize
: Especifica cuántas páginas de salida se deben incluir en cada archivo JSON de salida.
Método HTTP y URL:
POST https://REGION_ID-vision.googleapis.com/v1/projects/PROJECT_ID/locations/REGION_ID/files:asyncBatchAnnotate
Cuerpo JSON de la solicitud:
{ "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 tu solicitud, elige una de estas opciones:
curl
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente 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
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente 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
Una solicitud asyncBatchAnnotate
correcta muestra una respuesta con un solo campo de nombre:
{ "name": "projects/usable-auth-library/operations/1efec2285bd442df" }
Este nombre representa una operación de larga duración con un ID asociado (por ejemplo, 1efec2285bd442df
), que se puede consultar mediante la API de v1.operations
.
Para recuperar tu respuesta de anotación de Vision, envía una solicitud GET al extremo v1.operations
y pasa el ID de operación en la URL:
GET https://vision.googleapis.com/v1/operations/operation-id
Por ejemplo:
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
Si la operación se encuentra en curso, usa lo siguiente:
{ "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" } }
Una vez que la operación se completa, el state
se muestra como DONE
, y los resultados se escriben en el archivo de Google Cloud Storage que especificaste:
{ "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 } } ] } }
El JSON en tu archivo de salida es similar al de la respuesta de detección de texto en documentos de una imagen si usaste la función DOCUMENT_TEXT_DETECTION
, o al de la respuesta de detección de texto si usaste la función TEXT_DETECTION
. El resultado tendrá un campo context
adicional que muestra la ubicación del PDF o TIFF que se especificó y el número de páginas en el archivo:
output-1-to-1.json
Go
Antes de probar este código de muestra, sigue las instrucciones de configuración para Go que se encuentran en la Guía de inicio rápido de Vision sobre cómo usar las bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Vision para Go.
Para autenticarte en Vision, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Java
Antes de probar este código de muestra, sigue las instrucciones de configuración para Java que se encuentran la Guía de inicio rápido de la API de Vision sobre cómo usar las bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Vision para Java.
Node.js
Antes de probar este código de muestra, sigue las instrucciones de configuración para Node.js que se encuentran en la Guía de inicio rápido de Vision sobre cómo usar las bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Vision para Node.js.
Para autenticarte en Vision, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Antes de probar este código de muestra, sigue las instrucciones de configuración para Python que se encuentran en la Guía de inicio rápido de Vision sobre cómo usar las bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Vision para Python.
Para autenticarte en Vision, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Pruébalo tú mismo
Si es la primera vez que usas Google Cloud, crea una cuenta para evaluar el rendimiento de API de Cloud Vision en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.
Prueba gratis la API de Cloud Vision