L'API Vision può rilevare e trascrivere testo da file PDF e TIFF archiviati in Cloud Storage.
Il rilevamento del testo dei documenti da PDF e TIFF deve essere richiesto utilizzando la funzione files:asyncBatchAnnotate
, che esegue una richiesta offline (asincrona) e fornisce il proprio stato utilizzando le risorse operations
.
L'output di una richiesta PDF/TIFF viene scritto in un file JSON creato nel bucket Cloud Storage specificato.
Limitazioni
L'API Vision accetta file PDF/TIFF fino a 2000 pagine. I file più grandi restituiranno un errore.
Autenticazione
Le chiavi API non sono supportate per le richieste files:asyncBatchAnnotate
. Per istruzioni sull'autenticazione con un account di servizio, consulta Utilizzo di un account di servizio.
L'account utilizzato per l'autenticazione deve avere accesso al bucket Cloud Storage specificato per l'output (roles/editor
o roles/storage.objectCreator
o successivo).
Puoi utilizzare una chiave API per eseguire query sullo stato dell'operazione. Per le istruzioni, consulta la sezione Utilizzo di una chiave API.
Richieste di rilevamento di testo dei documenti
Attualmente il rilevamento di documenti PDF/TIFF è disponibile solo per i file archiviati nei bucket Cloud Storage. I file JSON di risposta vengono salvati in modo simile in un bucket Cloud Storage.
REST
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- CLOUD_STORAGE_BUCKET: una directory o un bucket Cloud Storage in cui salvare i file di output, espressi nel seguente formato:
gs://bucket/directory/
- CLOUD_STORAGE_FILE_URI: il percorso di un file
valido (PDF/TIFF) in un bucket Cloud Storage. Devi disporre almeno dei privilegi di lettura per il file.
Esempio:
gs://cloud-samples-data/vision/pdf_tiff/census2010.pdf
- FEATURE_TYPE: un tipo di elemento valido.
Per le richieste
files:asyncBatchAnnotate
, puoi utilizzare i seguenti tipi di funzionalità:DOCUMENT_TEXT_DETECTION
TEXT_DETECTION
- PROJECT_ID: l'ID del tuo progetto Google Cloud.
Considerazioni specifiche sul campo:
inputConfig
: sostituisce il campoimage
utilizzato in altre richieste dell'API Vision. Contiene due campi secondari:gcsSource.uri
: l'URI Google Cloud Storage del file PDF o TIFF (accessibile all'account utente o di servizio che effettua la richiesta).mimeType
: uno dei tipi di file accettati:application/pdf
oimage/tiff
.
outputConfig
: specifica i dettagli dell'output. Contiene due campi secondari:gcsDestination.uri
: un URI Google Cloud Storage valido. Il bucket deve essere scrivibile dall'account utente o di servizio che effettua la richiesta. Il nome del file saràoutput-x-to-y
, dovex
ey
rappresentano i numeri di pagina PDF/TIFF inclusi nel file di output. Se il file esiste, i relativi contenuti verranno sovrascritti.batchSize
: specifica quante pagine di output devono essere incluse in ogni file JSON di output.
Metodo HTTP e URL:
POST https://vision.googleapis.com/v1/files:asyncBatchAnnotate
Corpo JSON della richiesta:
{ "requests":[ { "inputConfig": { "gcsSource": { "uri": "CLOUD_STORAGE_FILE_URI" }, "mimeType": "application/pdf" }, "features": [ { "type": "FEATURE_TYPE" } ], "outputConfig": { "gcsDestination": { "uri": "CLOUD_STORAGE_BUCKET" }, "batchSize": 1 } } ] }
Per inviare la richiesta, scegli una delle seguenti opzioni:
arricciatura
Salva il corpo della richiesta in un file denominato request.json
ed esegui questo 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
Salva il corpo della richiesta in un file denominato request.json
ed esegui questo 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 richiesta asyncBatchAnnotate
riuscita restituisce una risposta con un singolo campo nome:
{ "name": "projects/usable-auth-library/operations/1efec2285bd442df" }
Questo nome rappresenta un'operazione a lunga esecuzione con un ID associato (ad esempio 1efec2285bd442df
), su cui è possibile eseguire una query utilizzando l'API v1.operations
.
Per recuperare la risposta dell'annotazione Vision, invia una richiesta GET all'endpoint v1.operations
, passando l'ID operazione nell'URL:
GET https://vision.googleapis.com/v1/operations/operation-id
Ad esempio:
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 l'operazione è in corso:
{ "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" } }
Al termine dell'operazione, state
verrà visualizzato come DONE
e
i risultati verranno scritti nel file di Google Cloud Storage specificato:
{ "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 } } ] } }
Il JSON nel file di output è simile a quello di una [richiesta di rilevamento del testo del documento](/vision/docs/ocr) di un'immagine, con l'aggiunta di un campo context
che mostra la posizione del PDF o TIFF specificato e il numero di pagine nel file:
output-1-to-1.json
Go
Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida di Vision sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Vision Go.
Per eseguire l'autenticazione in Vision, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida dell'API Vision sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento di Java dell'API Vision.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di Vision sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Vision Node.js.
Per eseguire l'autenticazione in Vision, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di Vision sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Vision Python.
Per eseguire l'autenticazione in Vision, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
gcloud
Il comando gcloud
che utilizzi dipende dal tipo di file.
Per eseguire il rilevamento del testo dei PDF, utilizza il comando
gcloud ml vision detect-text-pdf
come mostrato nell'esempio seguente:gcloud ml vision detect-text-pdf gs://my_bucket/input_file gs://my_bucket/out_put_prefix
Per eseguire il rilevamento del testo TIFF, usa il comando
gcloud ml vision detect-text-tiff
come mostrato nell'esempio seguente:gcloud ml vision detect-text-tiff gs://my_bucket/input_file gs://my_bucket/out_put_prefix
Linguaggi aggiuntivi
C#: segui le istruzioni di configurazione di C# nella pagina delle librerie client e poi consulta la documentazione di riferimento di Vision per .NET.
PHP: segui le istruzioni per la configurazione dei file PHP nella pagina delle librerie client e poi consulta la documentazione di riferimento di Vision per PHP.
Ruby: segui le istruzioni di configurazione di Ruby nella pagina delle librerie client e poi visita la documentazione di riferimento di Vision per Ruby.
Supporto di più aree geografiche
Ora puoi specificare l'archiviazione dei dati e l'elaborazione OCR a livello di continente. Al momento sono supportate le seguenti regioni:
us
: solo paese USAeu
: Unione Europea
Località
Cloud Vision offre un controllo su dove vengono archiviate ed elaborate le risorse del progetto. In particolare, puoi configurare Cloud Vision per archiviare ed elaborare i dati solo nell'Unione Europea.
Per impostazione predefinita, Cloud Vision archivia ed elabora le risorse in una località Globale, il che significa che Cloud Vision non garantisce che le risorse rimarranno in una determinata località o regione. Se scegli la località nell'Unione Europea, Google memorizzerà i tuoi dati e li tratterà solo nell'Unione Europea. Tu e i tuoi utenti potete accedere ai dati da qualsiasi luogo.
Impostazione della località mediante l'API
L'API Vision supporta un endpoint API globale (vision.googleapis.com
) e anche due endpoint basati sulla regione: un endpoint dell'Unione Europea (eu-vision.googleapis.com
) e un endpoint degli Stati Uniti (us-vision.googleapis.com
). Utilizza questi endpoint per l'elaborazione specifica per regione. Ad esempio, per archiviare ed elaborare i dati solo nell'Unione Europea, utilizza
l'URI eu-vision.googleapis.com
al posto di vision.googleapis.com
per le chiamate 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
Per archiviare ed elaborare i dati solo negli Stati Uniti, utilizza l'endpoint degli Stati Uniti
(us-vision.googleapis.com
) con i metodi precedenti.
Impostazione della località utilizzando le librerie client
Per impostazione predefinita, le librerie client dell'API Vision accedono all'endpoint API globale (vision.googleapis.com
). Per archiviare ed elaborare i dati solo nell'Unione Europea, devi impostare esplicitamente l'endpoint (eu-vision.googleapis.com
). I seguenti esempi di codice mostrano come configurare questa impostazione.
REST
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- REGION_ID: uno degli identificatori di località a livello di regione validi:
us
: solo paese USAeu
: Unione Europea
- CLOUD_STORAGE_IMAGE_URI: il percorso di un file immagine
valido in un bucket Cloud Storage. Devi disporre almeno dei privilegi di lettura per il file.
Esempio:
gs://cloud-samples-data/vision/pdf_tiff/census2010.pdf
- CLOUD_STORAGE_BUCKET: una directory o un bucket Cloud Storage in cui salvare i file di output, espressi nel seguente formato:
gs://bucket/directory/
- FEATURE_TYPE: un tipo di elemento valido.
Per le richieste
files:asyncBatchAnnotate
, puoi utilizzare i seguenti tipi di funzionalità:DOCUMENT_TEXT_DETECTION
TEXT_DETECTION
- PROJECT_ID: l'ID del tuo progetto Google Cloud.
Considerazioni specifiche sul campo:
inputConfig
: sostituisce il campoimage
utilizzato in altre richieste dell'API Vision. Contiene due campi secondari:gcsSource.uri
: l'URI Google Cloud Storage del file PDF o TIFF (accessibile all'account utente o di servizio che effettua la richiesta).mimeType
: uno dei tipi di file accettati:application/pdf
oimage/tiff
.
outputConfig
: specifica i dettagli dell'output. Contiene due campi secondari:gcsDestination.uri
: un URI Google Cloud Storage valido. Il bucket deve essere scrivibile dall'account utente o di servizio che effettua la richiesta. Il nome del file saràoutput-x-to-y
, dovex
ey
rappresentano i numeri di pagina PDF/TIFF inclusi nel file di output. Se il file esiste, i relativi contenuti verranno sovrascritti.batchSize
: specifica quante pagine di output devono essere incluse in ogni file JSON di output.
Metodo HTTP e URL:
POST https://REGION_ID-vision.googleapis.com/v1/projects/PROJECT_ID/locations/REGION_ID/files:asyncBatchAnnotate
Corpo JSON della richiesta:
{ "requests":[ { "inputConfig": { "gcsSource": { "uri": "CLOUD_STORAGE_IMAGE_URI" }, "mimeType": "application/pdf" }, "features": [ { "type": "FEATURE_TYPE" } ], "outputConfig": { "gcsDestination": { "uri": "CLOUD_STORAGE_BUCKET" }, "batchSize": 1 } } ] }
Per inviare la richiesta, scegli una delle seguenti opzioni:
arricciatura
Salva il corpo della richiesta in un file denominato request.json
ed esegui questo 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
Salva il corpo della richiesta in un file denominato request.json
ed esegui questo 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 richiesta asyncBatchAnnotate
riuscita restituisce una risposta con un singolo campo nome:
{ "name": "projects/usable-auth-library/operations/1efec2285bd442df" }
Questo nome rappresenta un'operazione a lunga esecuzione con un ID associato (ad esempio 1efec2285bd442df
), su cui è possibile eseguire una query utilizzando l'API v1.operations
.
Per recuperare la risposta dell'annotazione Vision, invia una richiesta GET all'endpoint v1.operations
, passando l'ID operazione nell'URL:
GET https://vision.googleapis.com/v1/operations/operation-id
Ad esempio:
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 l'operazione è in corso:
{ "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" } }
Al termine dell'operazione, state
verrà visualizzato come DONE
e
i risultati verranno scritti nel file di Google Cloud Storage specificato:
{ "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 } } ] } }
Il JSON nel file di output è simile a quello della risposta di
rilevamento di testo nei documenti
di un'immagine se hai utilizzato la funzionalità DOCUMENT_TEXT_DETECTION
o
la risposta di rilevamento del testo
se hai usato la funzionalità TEXT_DETECTION
. L'output avrà un campo context
aggiuntivo che mostra la posizione del PDF o TIFF specificato e il numero di pagine nel file:
output-1-to-1.json
Go
Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida di Vision sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Vision Go.
Per eseguire l'autenticazione in Vision, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida dell'API Vision sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento di Java dell'API Vision.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di Vision sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Vision Node.js.
Per eseguire l'autenticazione in Vision, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di Vision sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Vision Python.
Per eseguire l'autenticazione in Vision, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Provalo
Se non hai mai utilizzato Google Cloud, crea un account per valutare le prestazioni dell'API Cloud Vision in scenari reali. I nuovi clienti ricevono anche 300 $ di crediti gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.
Prova l'API Cloud Vision gratuitamente