Annotation de fichiers par lots hors connexion

L'API Cloud Vision peut détecter toute caractéristique de l'API Cloud Vision à partir des fichiers PDF et TIFF stockés dans Cloud Storage.

La détection de caractéristiques à partir de fichiers PDF et TIFF doit être initiée à l'aide de la fonction files:asyncBatchAnnotate qui effectue une requête hors connexion (asynchrone) et fournit son état à l'aide des 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 fonctionnalités

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ésultat sont enregistrés de même dans un bucket Cloud Storage.

Ligne de commande

Pour lancer une détection de document PDF/TIFF, utilisez une requête POST dont le corps approprié est :

curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://vision.googleapis.com/v1/files:asyncBatchAnnotate -d "{
  'requests':[
    {
      'inputConfig': {
        'gcsSource': {
          'uri': 'gs://your-source-bucket-name/folder/multi-page-file.pdf'
        },
        'mimeType': 'application/pdf'
      },
      'features': [
        {
          'type': 'DOCUMENT_TEXT_DETECTION'
        }
      ],
      'outputConfig': {
        'gcsDestination': {
          'uri': 'gs://your-bucket-name/folder/'
        },
        'batchSize': 1
      }
    }
  ]
}"

Où :

  • inputConfig remplace le champ image utilisé dans d'autres requêtes de l'API Vision. Il contient deux sous-champs :

    • gcsSource.uri est l'URI 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 ou image/tiff.
  • outputConfig sert à configurer le résultat. Il contient deux sous-champs :

    • gcsDestination.uri est un URI Cloud Storage 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 sera output-x-to-y, où x et y représentent les numéros de page PDF/TIFF inclus dans le fichier de réponse. Si un autre fichier semblable existe, son contenu sera écrasé.
    • batchSize est le nombre de pages à inclure dans chaque fichier JSON résultat.

Réponse :

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.

curl -X GET -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
https://vision.googleapis.com/v1/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 de votre fichier de réponse est semblable à celui de la requête de détection du texte d'un document d'une image, avec simplement l'ajout d'un champ context indiquant l'emplacement du fichier PDF ou TIFF spécifié et son nombre de pages :

output-1-to-1.json

C#

Avant d'essayer cet exemple, suivez les instructions de configuration pour C# dans le guide de démarrage rapide de Vision à l'aide des bibliothèques clientes. Pour plus d'informations, consultez la documentation de référence de l'API Cloud Vision en langage C#.

private static object DetectDocument(string gcsSourceUri,
    string gcsDestinationBucketName, string gcsDestinationPrefixName)
{
    var client = ImageAnnotatorClient.Create();

    var asyncRequest = new AsyncAnnotateFileRequest
    {
        InputConfig = new InputConfig
        {
            GcsSource = new GcsSource
            {
                Uri = gcsSourceUri
            },
            // Supported mime_types are: 'application/pdf' and 'image/tiff'
            MimeType = "application/pdf"
        },
        OutputConfig = new OutputConfig
        {
            // How many pages should be grouped into each json output file.
            BatchSize = 2,
            GcsDestination = new GcsDestination
            {
                Uri = $"gs://{gcsDestinationBucketName}/{gcsDestinationPrefixName}"
            }
        }
    };

    asyncRequest.Features.Add(new Feature
    {
        Type = Feature.Types.Type.DocumentTextDetection
    });

    List<AsyncAnnotateFileRequest> requests =
        new List<AsyncAnnotateFileRequest>();
    requests.Add(asyncRequest);

    var operation = client.AsyncBatchAnnotateFiles(requests);

    Console.WriteLine("Waiting for the operation to finish");

    operation.PollUntilCompleted();

    // Once the rquest has completed and the output has been
    // written to GCS, we can list all the output files.
    var storageClient = StorageClient.Create();

    // List objects with the given prefix.
    var blobList = storageClient.ListObjects(gcsDestinationBucketName,
        gcsDestinationPrefixName);
    Console.WriteLine("Output files:");
    foreach (var blob in blobList)
    {
        Console.WriteLine(blob.Name);
    }

    // Process the first output file from GCS.
    // Select the first JSON file from the objects in the list.
    var output = blobList.Where(x => x.Name.Contains(".json")).First();

    var jsonString = "";
    using (var stream = new MemoryStream())
    {
        storageClient.DownloadObject(output, stream);
        jsonString = System.Text.Encoding.UTF8.GetString(stream.ToArray());
    }

    var response = JsonParser.Default
                .Parse<AnnotateFileResponse>(jsonString);

    // The actual response for the first page of the input file.
    var firstPageResponses = response.Responses[0];
    var annotation = firstPageResponses.FullTextAnnotation;

    // Here we print the full text from the first page.
    // The response contains more information:
    // annotation/pages/blocks/paragraphs/words/symbols
    // including confidence scores and bounding boxes
    Console.WriteLine($"Full text: \n {annotation.Text}");

    return 0;
}

Go

Avant d'essayer cet exemple, suivez les instructions de configuration pour Go du guide de démarrage rapide de Vision à l'aide des bibliothèques clientes. Pour plus d'informations, consultez la documentation de référence de l'API Cloud Vision en langage Go.


// detectAsyncDocumentURI performs Optical Character Recognition (OCR) on a
// PDF file stored in GCS.
func detectAsyncDocumentURI(w io.Writer, gcsSourceURI, gcsDestinationURI string) error {
	ctx := context.Background()

	client, err := vision.NewImageAnnotatorClient(ctx)
	if err != nil {
		return err
	}

	request := &visionpb.AsyncBatchAnnotateFilesRequest{
		Requests: []*visionpb.AsyncAnnotateFileRequest{
			{
				Features: []*visionpb.Feature{
					{
						Type: visionpb.Feature_DOCUMENT_TEXT_DETECTION,
					},
				},
				InputConfig: &visionpb.InputConfig{
					GcsSource: &visionpb.GcsSource{Uri: gcsSourceURI},
					// Supported MimeTypes are: "application/pdf" and "image/tiff".
					MimeType: "application/pdf",
				},
				OutputConfig: &visionpb.OutputConfig{
					GcsDestination: &visionpb.GcsDestination{Uri: gcsDestinationURI},
					// How many pages should be grouped into each json output file.
					BatchSize: 2,
				},
			},
		},
	}

	operation, err := client.AsyncBatchAnnotateFiles(ctx, request)
	if err != nil {
		return err
	}

	fmt.Fprintf(w, "Waiting for the operation to finish.")

	resp, err := operation.Wait(ctx)
	if err != nil {
		return err
	}

	fmt.Fprintf(w, "%v", resp)

	return nil
}

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.

/**
 * Performs document text OCR with PDF/TIFF as source files on Google Cloud Storage.
 *
 * @param gcsSourcePath The path to the remote file on Google Cloud Storage to detect document
 *     text on.
 * @param gcsDestinationPath The path to the remote file on Google Cloud Storage to store the
 *     results on.
 * @throws Exception on errors while closing the client.
 */
public static void detectDocumentsGcs(String gcsSourcePath, String gcsDestinationPath)
    throws Exception {

  // Initialize client that will be used to send requests. This client only needs to be created
  // once, and can be reused for multiple requests. After completing all of your requests, call
  // the "close" method on the client to safely clean up any remaining background resources.
  try (ImageAnnotatorClient client = ImageAnnotatorClient.create()) {
    List<AsyncAnnotateFileRequest> requests = new ArrayList<>();

    // Set the GCS source path for the remote file.
    GcsSource gcsSource = GcsSource.newBuilder().setUri(gcsSourcePath).build();

    // Create the configuration with the specified MIME (Multipurpose Internet Mail Extensions)
    // types
    InputConfig inputConfig =
        InputConfig.newBuilder()
            .setMimeType(
                "application/pdf") // Supported MimeTypes: "application/pdf", "image/tiff"
            .setGcsSource(gcsSource)
            .build();

    // Set the GCS destination path for where to save the results.
    GcsDestination gcsDestination =
        GcsDestination.newBuilder().setUri(gcsDestinationPath).build();

    // Create the configuration for the System.output with the batch size.
    // The batch size sets how many pages should be grouped into each json System.output file.
    OutputConfig outputConfig =
        OutputConfig.newBuilder().setBatchSize(2).setGcsDestination(gcsDestination).build();

    // Select the Feature required by the vision API
    Feature feature = Feature.newBuilder().setType(Feature.Type.DOCUMENT_TEXT_DETECTION).build();

    // Build the OCR request
    AsyncAnnotateFileRequest request =
        AsyncAnnotateFileRequest.newBuilder()
            .addFeatures(feature)
            .setInputConfig(inputConfig)
            .setOutputConfig(outputConfig)
            .build();

    requests.add(request);

    // Perform the OCR request
    OperationFuture<AsyncBatchAnnotateFilesResponse, OperationMetadata> response =
        client.asyncBatchAnnotateFilesAsync(requests);

    System.out.println("Waiting for the operation to finish.");

    // Wait for the request to finish. (The result is not used, since the API saves the result to
    // the specified location on GCS.)
    List<AsyncAnnotateFileResponse> result =
        response.get(240, TimeUnit.SECONDS).getResponsesList();

    // Once the request has completed and the System.output has been
    // written to GCS, we can list all the System.output files.
    Storage storage = StorageOptions.getDefaultInstance().getService();

    // Get the destination location from the gcsDestinationPath
    Pattern pattern = Pattern.compile("gs://([^/]+)/(.+)");
    Matcher matcher = pattern.matcher(gcsDestinationPath);

    if (matcher.find()) {
      String bucketName = matcher.group(1);
      String prefix = matcher.group(2);

      // Get the list of objects with the given prefix from the GCS bucket
      Bucket bucket = storage.get(bucketName);
      com.google.api.gax.paging.Page<Blob> pageList = bucket.list(BlobListOption.prefix(prefix));

      Blob firstOutputFile = null;

      // List objects with the given prefix.
      System.out.println("Output files:");
      for (Blob blob : pageList.iterateAll()) {
        System.out.println(blob.getName());

        // Process the first System.output file from GCS.
        // Since we specified batch size = 2, the first response contains
        // the first two pages of the input file.
        if (firstOutputFile == null) {
          firstOutputFile = blob;
        }
      }

      // Get the contents of the file and convert the JSON contents to an AnnotateFileResponse
      // object. If the Blob is small read all its content in one request
      // (Note: the file is a .json file)
      // Storage guide: https://cloud.google.com/storage/docs/downloading-objects
      String jsonContents = new String(firstOutputFile.getContent());
      Builder builder = AnnotateFileResponse.newBuilder();
      JsonFormat.parser().merge(jsonContents, builder);

      // Build the AnnotateFileResponse object
      AnnotateFileResponse annotateFileResponse = builder.build();

      // Parse through the object to get the actual response for the first page of the input file.
      AnnotateImageResponse annotateImageResponse = annotateFileResponse.getResponses(0);

      // Here we print the full text from the first page.
      // The response contains more information:
      // annotation/pages/blocks/paragraphs/words/symbols
      // including confidence score and bounding boxes
      System.out.format("%nText: %s%n", annotateImageResponse.getFullTextAnnotation().getText());
    } else {
      System.out.println("No MATCH");
    }
  }
}

Node.js

Avant d'essayer cet exemple, suivez les instructions de configuration pour Node.js 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 Node.js.


// Imports the Google Cloud client libraries
const vision = require('@google-cloud/vision').v1;

// Creates a client
const client = new vision.ImageAnnotatorClient();

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// Bucket where the file resides
// const bucketName = 'my-bucket';
// Path to PDF file within bucket
// const fileName = 'path/to/document.pdf';
// The folder to store the results
// const outputPrefix = 'results'

const gcsSourceUri = `gs://${bucketName}/${fileName}`;
const gcsDestinationUri = `gs://${bucketName}/${outputPrefix}/`;

const inputConfig = {
  // Supported mime_types are: 'application/pdf' and 'image/tiff'
  mimeType: 'application/pdf',
  gcsSource: {
    uri: gcsSourceUri,
  },
};
const outputConfig = {
  gcsDestination: {
    uri: gcsDestinationUri,
  },
};
const features = [{type: 'DOCUMENT_TEXT_DETECTION'}];
const request = {
  requests: [
    {
      inputConfig: inputConfig,
      features: features,
      outputConfig: outputConfig,
    },
  ],
};

const [operation] = await client.asyncBatchAnnotateFiles(request);
const [filesResponse] = await operation.promise();
const destinationUri =
  filesResponse.responses[0].outputConfig.gcsDestination.uri;
console.log('Json saved to: ' + destinationUri);

PHP

Avant d'essayer cet exemple, suivez les instructions de configuration pour PHP 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 PHP.

namespace Google\Cloud\Samples\Vision;

use Google\Cloud\Storage\StorageClient;
use Google\Cloud\Vision\V1\AnnotateFileResponse;
use Google\Cloud\Vision\V1\AsyncAnnotateFileRequest;
use Google\Cloud\Vision\V1\Feature;
use Google\Cloud\Vision\V1\Feature\Type;
use Google\Cloud\Vision\V1\GcsDestination;
use Google\Cloud\Vision\V1\GcsSource;
use Google\Cloud\Vision\V1\ImageAnnotatorClient;
use Google\Cloud\Vision\V1\InputConfig;
use Google\Cloud\Vision\V1\OutputConfig;

// $path = 'gs://path/to/your/document.pdf'
// $output = 'gs://path/to/store/results/'

function detect_pdf_gcs($path, $output)
{
    # select ocr feature
    $feature = (new Feature())
        ->setType(Type::DOCUMENT_TEXT_DETECTION);

    # set $path (file to OCR) as source
    $gcsSource = (new GcsSource())
        ->setUri($path);
    # supported mime_types are: 'application/pdf' and 'image/tiff'
    $mimeType = 'application/pdf';
    $inputConfig = (new InputConfig())
        ->setGcsSource($gcsSource)
        ->setMimeType($mimeType);

    # set $output as destination
    $gcsDestination = (new GcsDestination())
        ->setUri($output);
    # how many pages should be grouped into each json output file.
    $batchSize = 2;
    $outputConfig = (new OutputConfig())
        ->setGcsDestination($gcsDestination)
        ->setBatchSize($batchSize);

    # prepare request using configs set above
    $request = (new AsyncAnnotateFileRequest())
        ->setFeatures([$feature])
        ->setInputConfig($inputConfig)
        ->setOutputConfig($outputConfig);
    $requests = [$request];

    # make request
    $imageAnnotator = new ImageAnnotatorClient();
    $operation = $imageAnnotator->asyncBatchAnnotateFiles($requests);
    print('Waiting for operation to finish.' . PHP_EOL);
    $operation->pollUntilComplete();

    # once the request has completed and the output has been
    # written to GCS, we can list all the output files.
    preg_match('/^gs:\/\/([a-zA-Z0-9\._\-]+)\/?(\S+)?$/', $output, $match);
    $bucketName = $match[1];
    $prefix = isset($match[2]) ? $match[2] : '';

    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $options = ['prefix' => $prefix];
    $objects = $bucket->objects($options);

    # save first object for sample below
    $objects->next();
    $firstObject = $objects->current();

    # list objects with the given prefix.
    print('Output files:' . PHP_EOL);
    foreach ($objects as $object) {
        print($object->name() . PHP_EOL);
    }

    # process the first output file from GCS.
    # since we specified batch_size=2, the first response contains
    # the first two pages of the input file.
    $jsonString = $firstObject->downloadAsString();
    $firstBatch = new AnnotateFileResponse();
    $firstBatch->mergeFromJsonString($jsonString);

    # get annotation and print text
    foreach ($firstBatch->getResponses() as $response) {
        $annotation = $response->getFullTextAnnotation();
        print($annotation->getText());
    }

    $imageAnnotator->close();
}

Python

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python 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 Python.

def async_detect_document(gcs_source_uri, gcs_destination_uri):
    """OCR with PDF/TIFF as source files on GCS"""
    import json
    import re
    from google.cloud import vision
    from google.cloud import storage

    # Supported mime_types are: 'application/pdf' and 'image/tiff'
    mime_type = 'application/pdf'

    # How many pages should be grouped into each json output file.
    batch_size = 2

    client = vision.ImageAnnotatorClient()

    feature = vision.Feature(
        type_=vision.Feature.Type.DOCUMENT_TEXT_DETECTION)

    gcs_source = vision.GcsSource(uri=gcs_source_uri)
    input_config = vision.InputConfig(
        gcs_source=gcs_source, mime_type=mime_type)

    gcs_destination = vision.GcsDestination(uri=gcs_destination_uri)
    output_config = vision.OutputConfig(
        gcs_destination=gcs_destination, batch_size=batch_size)

    async_request = vision.AsyncAnnotateFileRequest(
        features=[feature], input_config=input_config,
        output_config=output_config)

    operation = client.async_batch_annotate_files(
        requests=[async_request])

    print('Waiting for the operation to finish.')
    operation.result(timeout=420)

    # Once the request has completed and the output has been
    # written to GCS, we can list all the output files.
    storage_client = storage.Client()

    match = re.match(r'gs://([^/]+)/(.+)', gcs_destination_uri)
    bucket_name = match.group(1)
    prefix = match.group(2)

    bucket = storage_client.get_bucket(bucket_name)

    # List objects with the given prefix.
    blob_list = list(bucket.list_blobs(prefix=prefix))
    print('Output files:')
    for blob in blob_list:
        print(blob.name)

    # Process the first output file from GCS.
    # Since we specified batch_size=2, the first response contains
    # the first two pages of the input file.
    output = blob_list[0]

    json_string = output.download_as_string()
    response = json.loads(json_string)

    # The actual response for the first page of the input file.
    first_page_response = response['responses'][0]
    annotation = first_page_response['fullTextAnnotation']

    # Here we print the full text from the first page.
    # The response contains more information:
    # annotation/pages/blocks/paragraphs/words/symbols
    # including confidence scores and bounding boxes
    print('Full text:\n')
    print(annotation['text'])

Ruby

Avant d'essayer cet exemple, suivez les instructions de configuration pour Ruby 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 Ruby.

# gcs_source_uri = "Google Cloud Storage URI, eg. 'gs://my-bucket/example.pdf'"
# gcs_destination_uri = "Google Cloud Storage URI, eg. 'gs://my-bucket/prefix_'"

require "google/cloud/vision"
require "google/cloud/storage"

image_annotator = Google::Cloud::Vision.image_annotator

operation = image_annotator.document_text_detection(
  image:       gcs_source_uri,
  mime_type:   "application/pdf",
  batch_size:  2,
  destination: gcs_destination_uri,
  async:       true
)

puts "Waiting for the operation to finish."
operation.wait_until_done!

# Once the request has completed and the output has been
# written to GCS, we can list all the output files.
storage = Google::Cloud::Storage.new

bucket_name, prefix = gcs_destination_uri.match("gs://([^/]+)/(.+)").captures
bucket              = storage.bucket bucket_name

# List objects with the given prefix.
puts "Output files:"
blob_list = bucket.files prefix: prefix
blob_list.each do |file|
  puts file.name
end

# Process the first output file from GCS.
# Since we specified a batch_size of 2, the first response contains
# the first two pages of the input file.
json_string = blob_list[0].download
response    = JSON.parse json_string.string

# The actual response for the first page of the input file.
first_page_response = response["responses"][0]
annotation          = first_page_response["fullTextAnnotation"]

# Here we print the full text from the first page.
# The response contains more information:
# annotation/pages/blocks/paragraphs/words/symbols
# including confidence scores and bounding boxes
puts "Full text:\n#{annotation['text']}"

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