Envoyer une demande de traitement

Une fois que vous avez configuré votre compteGoogle Cloud et créé un processeur, vous pouvez envoyer une requête à votre processeur Document AI.

Le code utilisé pour envoyer la requête est le même pour tous les processeurs. Vous constatez des différences dans le fonctionnement des processeurs en fonction des informations qu'ils génèrent.

En utilisant la version v1 de l'API Document AI ou dans la console Google Cloud , vous pouvez envoyer des requêtes de traitement à cette version spécifique du processeur. Si vous ne spécifiez pas de version de processeur, la version par défaut est utilisée. Pour en savoir plus, consultez Gérer les versions de l'outil de traitement.

Traitement en ligne

Les requêtes en ligne (synchrones) vous permettent d'envoyer un seul document à traiter. Document AI traite immédiatement la requête et renvoie un document.

Envoyer une demande à un sous-traitant

Les exemples de code suivants montrent comment envoyer une requête à un processeur.

REST

Cet exemple vous montre comment fournir le contenu d'un document (contenu brut du document en octets via une chaîne encodée en base64) dans l'objet rawDocument.

Vous pouvez également spécifier inlineDocument, qui correspond au même format JSON Document renvoyé par Document AI. Cela vous permet d'enchaîner les requêtes en transmettant le même format dans les deux sens (par exemple, si vous classifiez un document, puis en extrayez le contenu).

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • LOCATION : emplacement de votre processeur, par exemple :
    • us : États-Unis
    • eu : Union européenne
  • PROJECT_ID : ID de votre projet Google Cloud .
  • PROCESSOR_ID : ID de votre processeur personnalisé.
  • skipHumanReview : booléen permettant de désactiver l'examen manuel (compatible uniquement avec les processeurs Human-in-the-Loop).
    • true : l'examen manuel est ignoré.
    • false : active l'examen manuel (valeur par défaut)
  • MIME_TYPE : l'une des options de type MIME valides.
  • IMAGE_CONTENT : contenu de document intégré valide, représenté sous forme de flux d'octets. Pour les représentations JSON, l'encodage base64 (chaîne ASCII) de vos données d'image binaire. Cette chaîne doit ressembler à la chaîne suivante :
    • /9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==
    Pour en savoir plus, consultez la section Encodage Base64.
  • FIELD_MASK : spécifie les champs à inclure dans le résultat Document. Il s'agit d'une liste de noms de champs complets séparés par une virgule au format FieldMask.
    • Exemple : text,entities,pages.pageNumber
  • INDIVIDUAL_PAGES : liste des pages individuelles à traiter.
    • Vous pouvez également fournir les champs fromStart ou fromEnd pour traiter une quantité spécifique de pages au début ou à la fin du document.

† Ce contenu peut également être spécifié à l'aide d'un contenu encodé en base64 dans l'objet inlineDocument.

Méthode HTTP et URL :

POST https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID:process

Corps JSON de la requête :

{
  "skipHumanReview": skipHumanReview,
  "rawDocument": {
    "mimeType": "MIME_TYPE",
    "content": "IMAGE_CONTENT"
  },
  "fieldMask": "FIELD_MASK",
  "processOptions": {
    "individualPageSelector" {
      "pages": [INDIVIDUAL_PAGES]
    }
  }
}

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 "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID:process"

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" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID:process" | Select-Object -Expand Content

Si la requête aboutit, le serveur renvoie un code d'état HTTP 200 OK et la réponse au format JSON. Le corps de la réponse contient une instance de Document.

Envoyer une requête à une version du processeur

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • LOCATION : emplacement de votre processeur, par exemple :
    • us : États-Unis
    • eu : Union européenne
  • PROJECT_ID : ID de votre projet Google Cloud .
  • PROCESSOR_ID : ID de votre processeur personnalisé.
  • PROCESSOR_VERSION : identifiant de la version du processeur. Pour en savoir plus, consultez Sélectionner une version de l'outil de traitement. Par exemple :
      .
    • pretrained-TYPE-vX.X-YYYY-MM-DD
    • stable
    • rc
  • skipHumanReview : booléen permettant de désactiver l'examen manuel (compatible uniquement avec les processeurs Human-in-the-Loop).
    • true : l'examen manuel est ignoré.
    • false : active l'examen manuel (valeur par défaut)
  • MIME_TYPE : l'une des options de type MIME valides.
  • IMAGE_CONTENT : contenu de document intégré valide, représenté sous forme de flux d'octets. Pour les représentations JSON, l'encodage base64 (chaîne ASCII) de vos données d'image binaire. Cette chaîne doit ressembler à la chaîne suivante :
    • /9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==
    Pour en savoir plus, consultez la section Encodage Base64.
  • FIELD_MASK : spécifie les champs à inclure dans le résultat Document. Il s'agit d'une liste de noms de champs complets séparés par une virgule au format FieldMask.
    • Exemple : text,entities,pages.pageNumber

† Ce contenu peut également être spécifié à l'aide d'un contenu encodé en base64 dans l'objet inlineDocument.

Méthode HTTP et URL :

POST https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/PROCESSOR_VERSION:process

Corps JSON de la requête :

{
  "skipHumanReview": skipHumanReview,
  "rawDocument": {
    "mimeType": "MIME_TYPE",
    "content": "IMAGE_CONTENT"
  },
  "fieldMask": "FIELD_MASK"
}

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 "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/PROCESSOR_VERSION:process"

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" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/PROCESSOR_VERSION:process" | Select-Object -Expand Content

Si la requête aboutit, le serveur renvoie un code d'état HTTP 200 OK et la réponse au format JSON. Le corps de la réponse contient une instance de Document.

C#

Pour en savoir plus, consultez la documentation de référence de l'API Document AI C#.

Pour vous authentifier auprès de Document AI, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.


using Google.Cloud.DocumentAI.V1;
using Google.Protobuf;
using System;
using System.IO;

public class QuickstartSample
{
    public Document Quickstart(
        string projectId = "your-project-id",
        string locationId = "your-processor-location",
        string processorId = "your-processor-id",
        string localPath = "my-local-path/my-file-name",
        string mimeType = "application/pdf"
    )
    {
        // Create client
        var client = new DocumentProcessorServiceClientBuilder
        {
            Endpoint = $"{locationId}-documentai.googleapis.com"
        }.Build();

        // Read in local file
        using var fileStream = File.OpenRead(localPath);
        var rawDocument = new RawDocument
        {
            Content = ByteString.FromStream(fileStream),
            MimeType = mimeType
        };

        // Initialize request argument(s)
        var request = new ProcessRequest
        {
            Name = ProcessorName.FromProjectLocationProcessor(projectId, locationId, processorId).ToString(),
            RawDocument = rawDocument
        };

        // Make the request
        var response = client.ProcessDocument(request);

        var document = response.Document;
        Console.WriteLine(document.Text);
        return document;
    }
}

Java

Pour en savoir plus, consultez la documentation de référence de l'API Document AI Java.

Pour vous authentifier auprès de Document AI, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.


import com.google.cloud.documentai.v1.Document;
import com.google.cloud.documentai.v1.DocumentProcessorServiceClient;
import com.google.cloud.documentai.v1.DocumentProcessorServiceSettings;
import com.google.cloud.documentai.v1.ProcessRequest;
import com.google.cloud.documentai.v1.ProcessResponse;
import com.google.cloud.documentai.v1.RawDocument;
import com.google.protobuf.ByteString;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.List;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeoutException;

public class ProcessDocument {
  public static void processDocument()
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String location = "your-project-location"; // Format is "us" or "eu".
    String processerId = "your-processor-id";
    String filePath = "path/to/input/file.pdf";
    processDocument(projectId, location, processerId, filePath);
  }

  public static void processDocument(
      String projectId, String location, String processorId, String filePath)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    // 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.
    String endpoint = String.format("%s-documentai.googleapis.com:443", location);
    DocumentProcessorServiceSettings settings =
        DocumentProcessorServiceSettings.newBuilder().setEndpoint(endpoint).build();
    try (DocumentProcessorServiceClient client = DocumentProcessorServiceClient.create(settings)) {
      // The full resource name of the processor, e.g.:
      // projects/project-id/locations/location/processor/processor-id
      // You must create new processors in the Cloud Console first
      String name =
          String.format("projects/%s/locations/%s/processors/%s", projectId, location, processorId);

      // Read the file.
      byte[] imageFileData = Files.readAllBytes(Paths.get(filePath));

      // Convert the image data to a Buffer and base64 encode it.
      ByteString content = ByteString.copyFrom(imageFileData);

      RawDocument document =
          RawDocument.newBuilder().setContent(content).setMimeType("application/pdf").build();

      // Configure the process request.
      ProcessRequest request =
          ProcessRequest.newBuilder().setName(name).setRawDocument(document).build();

      // Recognizes text entities in the PDF document
      ProcessResponse result = client.processDocument(request);
      Document documentResponse = result.getDocument();

      // Get all of the document text as one big string
      String text = documentResponse.getText();

      // Read the text recognition output from the processor
      System.out.println("The document contains the following paragraphs:");
      Document.Page firstPage = documentResponse.getPages(0);
      List<Document.Page.Paragraph> paragraphs = firstPage.getParagraphsList();

      for (Document.Page.Paragraph paragraph : paragraphs) {
        String paragraphText = getText(paragraph.getLayout().getTextAnchor(), text);
        System.out.printf("Paragraph text:\n%s\n", paragraphText);
      }

      // Form parsing provides additional output about
      // form-formatted PDFs. You must create a form
      // processor in the Cloud Console to see full field details.
      System.out.println("The following form key/value pairs were detected:");

      for (Document.Page.FormField field : firstPage.getFormFieldsList()) {
        String fieldName = getText(field.getFieldName().getTextAnchor(), text);
        String fieldValue = getText(field.getFieldValue().getTextAnchor(), text);

        System.out.println("Extracted form fields pair:");
        System.out.printf("\t(%s, %s))\n", fieldName, fieldValue);
      }
    }
  }

  // Extract shards from the text field
  private static String getText(Document.TextAnchor textAnchor, String text) {
    if (textAnchor.getTextSegmentsList().size() > 0) {
      int startIdx = (int) textAnchor.getTextSegments(0).getStartIndex();
      int endIdx = (int) textAnchor.getTextSegments(0).getEndIndex();
      return text.substring(startIdx, endIdx);
    }
    return "[NO TEXT]";
  }
}

Node.js

Pour en savoir plus, consultez la documentation de référence de l'API Document AI Node.js.

Pour vous authentifier auprès de Document AI, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const projectId = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION'; // Format is 'us' or 'eu'
// const processorId = 'YOUR_PROCESSOR_ID'; // Create processor in Cloud Console
// const filePath = '/path/to/local/pdf';

const {DocumentProcessorServiceClient} =
  require('@google-cloud/documentai').v1;

// Instantiates a client
const client = new DocumentProcessorServiceClient();

async function processDocument() {
  // The full resource name of the processor, e.g.:
  // projects/project-id/locations/location/processor/processor-id
  // You must create new processors in the Cloud Console first
  const name = `projects/${projectId}/locations/${location}/processors/${processorId}`;

  // Read the file into memory.
  const fs = require('fs').promises;
  const imageFile = await fs.readFile(filePath);

  // Convert the image data to a Buffer and base64 encode it.
  const encodedImage = Buffer.from(imageFile).toString('base64');

  const request = {
    name,
    rawDocument: {
      content: encodedImage,
      mimeType: 'application/pdf',
    },
  };

  // Recognizes text entities in the PDF document
  const [result] = await client.processDocument(request);
  const {document} = result;

  // Get all of the document text as one big string
  const {text} = document;

  // Extract shards from the text field
  const getText = textAnchor => {
    if (!textAnchor.textSegments || textAnchor.textSegments.length === 0) {
      return '';
    }

    // First shard in document doesn't have startIndex property
    const startIndex = textAnchor.textSegments[0].startIndex || 0;
    const endIndex = textAnchor.textSegments[0].endIndex;

    return text.substring(startIndex, endIndex);
  };

  // Read the text recognition output from the processor
  console.log('The document contains the following paragraphs:');
  const [page1] = document.pages;
  const {paragraphs} = page1;

  for (const paragraph of paragraphs) {
    const paragraphText = getText(paragraph.layout.textAnchor);
    console.log(`Paragraph text:\n${paragraphText}`);
  }

  // Form parsing provides additional output about
  // form-formatted PDFs. You  must create a form
  // processor in the Cloud Console to see full field details.
  console.log('\nThe following form key/value pairs were detected:');

  const {formFields} = page1;
  for (const field of formFields) {
    const fieldName = getText(field.fieldName.textAnchor);
    const fieldValue = getText(field.fieldValue.textAnchor);

    console.log('Extracted key value pair:');
    console.log(`\t(${fieldName}, ${fieldValue})`);
  }
}

Python

Pour en savoir plus, consultez la documentation de référence de l'API Document AI Python.

Pour vous authentifier auprès de Document AI, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

from typing import Optional

from google.api_core.client_options import ClientOptions
from google.cloud import documentai  # type: ignore

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_PROCESSOR_LOCATION" # Format is "us" or "eu"
# processor_id = "YOUR_PROCESSOR_ID" # Create processor before running sample
# file_path = "/path/to/local/pdf"
# mime_type = "application/pdf" # Refer to https://cloud.google.com/document-ai/docs/file-types for supported file types
# field_mask = "text,entities,pages.pageNumber"  # Optional. The fields to return in the Document object.
# processor_version_id = "YOUR_PROCESSOR_VERSION_ID" # Optional. Processor version to use


def process_document_sample(
    project_id: str,
    location: str,
    processor_id: str,
    file_path: str,
    mime_type: str,
    field_mask: Optional[str] = None,
    processor_version_id: Optional[str] = None,
) -> None:
    # You must set the `api_endpoint` if you use a location other than "us".
    opts = ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")

    client = documentai.DocumentProcessorServiceClient(client_options=opts)

    if processor_version_id:
        # The full resource name of the processor version, e.g.:
        # `projects/{project_id}/locations/{location}/processors/{processor_id}/processorVersions/{processor_version_id}`
        name = client.processor_version_path(
            project_id, location, processor_id, processor_version_id
        )
    else:
        # The full resource name of the processor, e.g.:
        # `projects/{project_id}/locations/{location}/processors/{processor_id}`
        name = client.processor_path(project_id, location, processor_id)

    # Read the file into memory
    with open(file_path, "rb") as image:
        image_content = image.read()

    # Load binary data
    raw_document = documentai.RawDocument(content=image_content, mime_type=mime_type)

    # For more information: https://cloud.google.com/document-ai/docs/reference/rest/v1/ProcessOptions
    # Optional: Additional configurations for processing.
    process_options = documentai.ProcessOptions(
        # Process only specific pages
        individual_page_selector=documentai.ProcessOptions.IndividualPageSelector(
            pages=[1]
        )
    )

    # Configure the process request
    request = documentai.ProcessRequest(
        name=name,
        raw_document=raw_document,
        field_mask=field_mask,
        process_options=process_options,
    )

    result = client.process_document(request=request)

    # For a full list of `Document` object attributes, reference this page:
    # https://cloud.google.com/document-ai/docs/reference/rest/v1/Document
    document = result.document

    # Read the text recognition output from the processor
    print("The document contains the following text:")
    print(document.text)

Traitement par lot

Les requêtes par lot (asynchrones) vous permettent d'envoyer plusieurs documents dans une seule requête. Document AI répond avec un operation que vous pouvez interroger pour connaître l'état de la demande. Une fois cette opération terminée, elle contient un BatchProcessMetadata qui pointe vers le bucket Cloud Storage dans lequel les résultats traités sont stockés.

Si les fichiers d'entrée auxquels vous souhaitez accéder se trouvent dans un bucket d'un autre projet, vous devez fournir un accès à ce bucket avant de pouvoir accéder aux fichiers. Consultez Accéder au fichier d'installation.

Envoyer une demande à un sous-traitant

Les exemples de code suivants montrent comment envoyer une requête de traitement par lot à un processeur.

REST

Cet exemple montre comment envoyer une requête POST à la méthode batchProcess pour le traitement asynchrone de documents volumineux. Cet exemple fait intervenir le jeton d'accès associé à un compte de service configuré pour le projet à l'aide de Google Cloud CLI. Pour obtenir des instructions sur l'installation de la Google Cloud CLI, la configuration d'un projet avec un compte de service et l'obtention d'un jeton d'accès, consultez Avant de commencer.

Une requête batchProcess lance une opération de longue durée et stocke les résultats dans un bucket Cloud Storage. Cet exemple montre également comment obtenir l'état de cette opération de longue durée une fois qu'elle a commencé.

Envoyer la requête de processus

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • LOCATION : emplacement de votre processeur, par exemple :
    • us : États-Unis
    • eu : Union européenne
  • PROJECT_ID : ID de votre projet Google Cloud .
  • PROCESSOR_ID : ID de votre processeur personnalisé.
  • INPUT_BUCKET_FOLDER : bucket/répertoire Cloud Storage à partir duquel lire les fichiers d'entrée, sous la forme suivante :
    • gs://bucket/directory/
    L'utilisateur demandeur doit disposer d'autorisations de lecture sur le bucket.
  • MIME_TYPE : l'une des options de type MIME valides.
  • OUTPUT_BUCKET_FOLDER : répertoire/bucket Cloud Storage dans lequel enregistrer les fichiers de sortie, sous ce format :
    • gs://bucket/directory/
    L'utilisateur demandeur doit disposer d'autorisations d'écriture sur le bucket.
  • skipHumanReview : booléen permettant de désactiver l'examen manuel (compatible uniquement avec les processeurs Human-in-the-Loop).
    • true : l'examen manuel est ignoré.
    • false : active l'examen manuel (valeur par défaut)
  • FIELD_MASK : spécifie les champs à inclure dans le résultat Document. Il s'agit d'une liste de noms de champs complets séparés par une virgule au format FieldMask.
    • Exemple : text,entities,pages.pageNumber

† Au lieu d'utiliser gcsPrefix pour inclure tous les fichiers d'un dossier GCS, vous pouvez également utiliser documents pour lister chaque fichier individuellement :

  "inputDocuments": {
    "gcsDocuments": {
      "documents": [
        {
          "gcsUri": "gs://BUCKET/PATH/TO/DOCUMENT1.ext",
          "mimeType": "MIME_TYPE"
        },
        {
          "gcsUri": "gs://BUCKET/PATH/TO/DOCUMENT2.ext",
          "mimeType": "MIME_TYPE"
        }
      ]
    }
  }

Méthode HTTP et URL :

POST https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID:batchProcess

Corps JSON de la requête :

{
  "inputDocuments": {
    "gcsPrefix": {
      "gcsUriPrefix": "INPUT_BUCKET_FOLDER"
    }
  },
  "documentOutputConfig": {
    "gcsOutputConfig": {
      "gcsUri": "OUTPUT_BUCKET_FOLDER",
      "fieldMask": "FIELD_MASK"
    }
  },
  "skipHumanReview": BOOLEAN
}

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 :