L'API Vision peut détecter et transcrire le texte des fichiers PDF et TIFF stockés dans Cloud Storage.
La détection du texte d'un document à partir de fichiers PDF et TIFF doit être initiée à l'aide de la fonction files:asyncBatchAnnotate
qui effectue une requête hors ligne (asynchrone) et renvoie son état via les ressources operations
.
Le résultat d'une requête PDF/TIFF est écrit dans un fichier JSON créé dans le bucket Cloud Storage spécifié.
Limites
L'API Vision accepte les fichiers PDF/TIFF jusqu'à 2 000 pages. Les fichiers plus volumineux renverront une erreur.
Authentification
Les clés API ne sont pas compatibles pour les requêtes files:asyncBatchAnnotate
. Consultez la section Utiliser un compte de service pour des instructions sur l'authentification avec un compte de service.
Le compte utilisé pour l'authentification doit avoir accès au bucket Cloud Storage que vous spécifiez pour le résultat (roles/editor
, roles/storage.objectCreator
ou supérieur).
Cependant, vous pouvez utiliser une clé API pour suivre l'état de l'opération. Pour obtenir des instructions, consultez la section Utiliser une clé API.
Requêtes de détection de document texte
Pour le moment, la détection de texte dans des documents PDF et TIFF n'est disponible que si les fichiers sont stockés dans des buckets Cloud Storage. Les fichiers JSON résultats sont enregistrés de même dans un bucket Cloud Storage.
REST
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- CLOUD_STORAGE_BUCKET : répertoire/bucket Cloud Storage dans lequel enregistrer les fichiers de sortie, sous ce format :
gs://bucket/directory/
- CLOUD_STORAGE_FILE_URI : chemin d'accès à un fichier valide (PDF/TIFF) dans un bucket Cloud Storage. Il faut au minimum disposer des droits en lecture sur le fichier.
Exemple :
gs://cloud-samples-data/vision/pdf_tiff/census2010.pdf
- FEATURE_TYPE : type de fonctionnalité valide.
Pour les requêtes
files:asyncBatchAnnotate
, vous pouvez utiliser les types de fonctionnalités suivants :DOCUMENT_TEXT_DETECTION
TEXT_DETECTION
- PROJECT_ID : ID de votre projet Google Cloud.
Remarque sur les champs :
inputConfig
remplace le champimage
utilisé dans d'autres requêtes de l'API Vision. Il contient deux sous-champs :gcsSource.uri
est l'URI Google Cloud Storage du fichier PDF ou TIFF (devant être accessible à l'utilisateur ou au compte de service à l'origine de la requête).mimeType
est l'un des types de fichiers acceptés :application/pdf
ouimage/tiff
.
outputConfig
sert à configurer le résultat. Il contient deux sous-champs :gcsDestination.uri
est un URI Google Cloud Storage qui doit être valide. Le bucket doit être accessible en écriture par l'utilisateur ou le compte de service à l’origine de la requête. Le nom du fichier seraoutput-x-to-y
, oùx
ety
représentent les numéros de page PDF/TIFF inclus dans le fichier de sortie. Si un fichier portant le même nom existe déjà, son contenu sera écrasé.batchSize
est le nombre de pages à inclure dans chaque fichier JSON résultat.
Méthode HTTP et URL :
POST https://vision.googleapis.com/v1/files:asyncBatchAnnotate
Corps JSON de la requête :
{ "requests":[ { "inputConfig": { "gcsSource": { "uri": "CLOUD_STORAGE_FILE_URI" }, "mimeType": "application/pdf" }, "features": [ { "type": "FEATURE_TYPE" } ], "outputConfig": { "gcsDestination": { "uri": "CLOUD_STORAGE_BUCKET" }, "batchSize": 1 } } ] }
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
Enregistrez le corps de la requête dans un fichier nommé request.json
, puis exécutez la commande suivante :
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
Enregistrez le corps de la requête dans un fichier nommé request.json
, puis exécutez la commande suivante :
$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
Une requête asyncBatchAnnotate
réussie renvoie une réponse avec un champ de nom unique :
{ "name": "projects/usable-auth-library/operations/1efec2285bd442df" }
Sa valeur représente une opération de longue durée avec un identifiant associé (par exemple, 1efec2285bd442df
), dont on peut vérifier l'état à l'aide de l'API v1.operations
.
Pour récupérer le résultat de l'annotation par Vision, envoyez une requête GET au point de terminaison v1.operations
en transmettant l'identifiant de l'opération dans l'URL.
GET https://vision.googleapis.com/v1/operations/operation-id
Exemple :
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 l'opération est en cours :
{ "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" } }
Une fois l'opération terminée, state
prend la valeur DONE
, et le résultat est enregistré dans le fichier Google Cloud Storage que vous avez spécifié :
{ "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 } } ] } }
Le fichier JSON résultat est semblable à celui produit par une [requête de détection du texte d'un document](/vision/docs/ocr) sur une image, avec simplement en plus le champ context
qui indique l'emplacement du fichier PDF ou TIFF spécifié et le numéro des pages :
output-1-to-1.json
Go
Avant d'essayer cet exemple, suivez les instructions de configuration pour Go décrites dans le guide de démarrage rapide de Vision à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Cloud Vision en langage Go.
Pour vous authentifier auprès de Vision, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Java
Avant d'essayer cet exemple, suivez les instructions de configuration pour Java du guide de démarrage rapide de Vision à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Cloud Vision en langage Java.
Node.js
Avant d'essayer cet exemple, suivez les instructions de configuration pour Node.js décrites dans le guide de démarrage rapide de Vision à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Cloud Vision en langage Node.js.
Pour vous authentifier auprès de Vision, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Python
Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide de Vision à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Cloud Vision en langage Python.
Pour vous authentifier auprès de Vision, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
gcloud
La commande gcloud
à utiliser dépend du type de fichier à traiter.
Pour effectuer une détection de texte sur un fichier PDF, utilisez la commande
gcloud ml vision detect-text-pdf
comme indiqué dans l'exemple suivant :gcloud ml vision detect-text-pdf gs://my_bucket/input_file gs://my_bucket/out_put_prefix
Pour effectuer une détection de texte sur un fichier TIFF, utilisez la commande
gcloud ml vision detect-text-tiff
comme indiqué dans l'exemple suivant :gcloud ml vision detect-text-tiff gs://my_bucket/input_file gs://my_bucket/out_put_prefix
Langages supplémentaires
C# : Veuillez suivre les Instructions de configuration de C# sur la page des bibliothèques clientes, puis consultez la Documentation de référence sur Vision pour .NET.
PHP : Veuillez suivre les Instructions de configuration pour PHP sur la page des bibliothèques clientes, puis consultez la Documentation de référence sur Vision pour PHP.
Ruby : Veuillez suivre les Instructions de configuration de Ruby sur la page des bibliothèques clientes, puis consultez la Documentation de référence sur Vision pour Ruby.
Stockage multirégional
Vous pouvez désormais spécifier le stockage de données et le traitement OCR au niveau du continent. Les régions actuellement compatibles sont les suivantes :
us
: pays des États-Unis uniquementeu
: Union européenne
Emplacements
Cloud Vision vous permet de contrôler où les ressources de votre projet sont stockées et traitées. Vous pouvez notamment configurer Cloud Vision pour stocker vos données et ne procéder à leur traitement que dans l'Union européenne.
Dans Cloud Vision, les ressources sont stockées et traitées par défaut dans un emplacement global. Le maintien de vos ressources dans un emplacement ou une région spécifique n'est donc pas garanti. Pour que Google ne stocke et traite vos données que dans l'Union européenne, vous devez sélectionner la région Union européenne. Vous et vos utilisateurs pouvez accéder aux données depuis n'importe quel emplacement.
Définir l'emplacement à l'aide de l'API
L'API Vision accepte un point de terminaison global d'API (vision.googleapis.com
), ainsi que deux points de terminaison régionaux : un point de terminaison en Union européenne (eu-vision.googleapis.com
) et un point de terminaison aux États-Unis (us-vision.googleapis.com
). Utilisez ces points de terminaison pour un traitement spécifique à la région. Par exemple, pour stocker et traiter vos données dans l'Union européenne uniquement, utilisez l'URI eu-vision.googleapis.com
à la place de vision.googleapis.com
pour vos appels d'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
Pour stocker et traiter vos données aux États-Unis uniquement, utilisez le point de terminaison US (us-vision.googleapis.com
) avec les méthodes précédentes.
Définir l'emplacement à l'aide des bibliothèques clientes
Par défaut, les bibliothèques clientes de l'API Vision accèdent au point de terminaison global de l'API (vision.googleapis.com
). Pour ne stocker et traiter vos données qu'en Union européenne, vous devez définir explicitement le point de terminaison (eu-vision.googleapis.com
). Les exemples de code ci-dessous indiquent comment configurer ce paramètre.
REST
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- REGION_ID : l'un des identifiants de zone géographique valides :
us
: pays des États-Unis uniquementeu
: Union européenne
- CLOUD_STORAGE_IMAGE_URI : chemin d'accès à un fichier image valide dans un bucket Cloud Storage. Il faut au minimum disposer des droits en lecture sur le fichier.
Exemple :
gs://cloud-samples-data/vision/pdf_tiff/census2010.pdf
- CLOUD_STORAGE_BUCKET : répertoire/bucket Cloud Storage dans lequel enregistrer les fichiers de sortie, sous ce format :
gs://bucket/directory/
- FEATURE_TYPE : type de fonctionnalité valide.
Pour les requêtes
files:asyncBatchAnnotate
, vous pouvez utiliser les types de fonctionnalités suivants :DOCUMENT_TEXT_DETECTION
TEXT_DETECTION
- PROJECT_ID : ID de votre projet Google Cloud.
Remarque sur les champs :
inputConfig
remplace le champimage
utilisé dans d'autres requêtes de l'API Vision. Il contient deux sous-champs :gcsSource.uri
est l'URI Google Cloud Storage du fichier PDF ou TIFF (devant être accessible à l'utilisateur ou au compte de service à l'origine de la requête).mimeType
est l'un des types de fichiers acceptés :application/pdf
ouimage/tiff
.
outputConfig
sert à configurer le résultat. Il contient deux sous-champs :gcsDestination.uri
est un URI Google Cloud Storage qui doit être valide. Le bucket doit être accessible en écriture par l'utilisateur ou le compte de service à l’origine de la requête. Le nom du fichier seraoutput-x-to-y
, oùx
ety
représentent les numéros de page PDF/TIFF inclus dans le fichier de sortie. Si un fichier portant le même nom existe déjà, son contenu sera écrasé.batchSize
est le nombre de pages à inclure dans chaque fichier JSON résultat.
Méthode HTTP et URL :
POST https://REGION_ID-vision.googleapis.com/v1/projects/PROJECT_ID/locations/REGION_ID/files:asyncBatchAnnotate
Corps JSON de la requête :
{ "requests":[ { "inputConfig": { "gcsSource": { "uri": "CLOUD_STORAGE_IMAGE_URI" }, "mimeType": "application/pdf" }, "features": [ { "type": "FEATURE_TYPE" } ], "outputConfig": { "gcsDestination": { "uri": "CLOUD_STORAGE_BUCKET" }, "batchSize": 1 } } ] }
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
Enregistrez le corps de la requête dans un fichier nommé request.json
, puis exécutez la commande suivante :
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
Enregistrez le corps de la requête dans un fichier nommé request.json
, puis exécutez la commande suivante :
$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
Une requête asyncBatchAnnotate
réussie renvoie une réponse avec un champ de nom unique :
{ "name": "projects/usable-auth-library/operations/1efec2285bd442df" }
Sa valeur représente une opération de longue durée avec un identifiant associé (par exemple, 1efec2285bd442df
), dont on peut vérifier l'état à l'aide de l'API v1.operations
.
Pour récupérer le résultat de l'annotation par Vision, envoyez une requête GET au point de terminaison v1.operations
en transmettant l'identifiant de l'opération dans l'URL.
GET https://vision.googleapis.com/v1/operations/operation-id
Exemple :
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 l'opération est en cours :
{ "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" } }
Une fois l'opération terminée, state
prend la valeur DONE
, et le résultat est enregistré dans le fichier Google Cloud Storage que vous avez spécifié :
{ "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 } } ] } }
La réponse JSON dans votre fichier de sortie est semblable à celle produite par une réponse de détection d'un document texte sur une image si vous avez utilisé la fonctionnalité DOCUMENT_TEXT_DETECTION
, ou par une requête de détection de texte si vous avez utilisé la fonctionnalité TEXT_DETECTION
. Le résultat comporte un champ context
supplémentaire indiquant l'emplacement du fichier PDF ou TIFF spécifié et son nombre de pages :
output-1-to-1.json
Go
Avant d'essayer cet exemple, suivez les instructions de configuration pour Go décrites dans le guide de démarrage rapide de Vision à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Cloud Vision en langage Go.
Pour vous authentifier auprès de Vision, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Java
Avant d'essayer cet exemple, suivez les instructions de configuration pour Java du guide de démarrage rapide de Vision à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Cloud Vision en langage Java.
Node.js
Avant d'essayer cet exemple, suivez les instructions de configuration pour Node.js décrites dans le guide de démarrage rapide de Vision à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Cloud Vision en langage Node.js.
Pour vous authentifier auprès de Vision, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Python
Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide de Vision à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Cloud Vision en langage Python.
Pour vous authentifier auprès de Vision, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Faites l'essai
Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de l'API Cloud Vision en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits pour exécuter, tester et déployer des charges de travail.
Profiter d'un essai offert de l'API Cloud Vision