Gestire i documenti

Questo documento descrive come gestire i documenti in Document AI Warehouse, incluse le operazioni di creazione, recupero, aggiornamento ed eliminazione.

Che cosa sono i documenti

Un documento è il modello dei dati utilizzato in Document AI Warehouse per organizzare un documento reale (ad esempio PDF o TXT) e le relative proprietà. Interagisci con Document AI Warehouse tramite operazioni sui documenti.

Tipi di file supportati

Sebbene l'obiettivo di Document AI Warehouse siano i documenti, viene utilizzato anche per gestire le immagini associate (ad esempio, in settori verticali come assicurazioni, ingegneria, edilizia e ricerca).

  • L'API Ingest supporta PDF e immagini TIFF, JPEG e PNG, insieme a eventuali proprietà o testo pre-estratto.
  • L'UI di caricamento supporta l'estrazione di PDF utilizzando Document AI OCR e processori personalizzati.
  • L'UI del visualizzatore supporta il rendering in file PDF, di testo e di Microsoft Office.

Prima di iniziare

Prima di iniziare, assicurati di aver completato la pagina Guida rapida.

Per la creazione di documenti, se i dati si trovano nel tuo bucket Cloud Storage, devi concedere al account di servizio account di Document AI Warehouse l'autorizzazione di visualizzatore di oggetti Storage per leggere i tuoi dati.

Ogni documento è specificato da uno schema e appartiene a un tipo di documento. Uno schema di documento definisce la struttura del documento in Document AI Warehouse. Prima di poter creare documenti, devi creare uno schema di documento.

Crea un documento

Per creare un documento, devi fornire i contenuti del documento non elaborati a Document AI Warehouse. I due modi per fornire i contenuti dei byte del documento non elaborati sono impostando Document.inline_raw_document o Document.raw_document_path.

Le differenze sono le seguenti:

  • Document.raw_document_path: questo è l'approccio preferito. Utilizza il percorso Cloud Storage (gs://bucket/object) del file da importare. Tieni presente che il chiamante deve disporre dell'autorizzazione di lettura per questo oggetto affinché la chiamata vada a buon fine.

  • Document.inline_raw_document: rappresentazione di byte/testo del file, fornita direttamente all'endpoint.

Per creare un documento:

Carica un documento da Cloud Storage

Devi concedere al account di servizio di Document AI Warehouse l'accesso al tuo bucket Cloud Storage come descritto nella sezione dei prerequisiti.

Devi caricare il file in un bucket Cloud Storage seguendo le istruzioni.

REST

Richiesta:

curl --location --request POST --url https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/documents \
--header "Authorization: Bearer $(gcloud auth print-access-token)" \
--header "Content-Type: application/json; charset=utf-8" \
--data '{
"document": {
  "display_name": "TestDoc3",
  "document_schema_name": "projects/PROJECT_NUMBER/locations/LOCATION/documentSchemas/DOCUMENT_SCHEMA_ID",
  "raw_document_path": "gs://BUCKET_URI/FILE_URI",
  "properties": [
    {
      "name": "supplier_name",
      "text_values": {
        "values": "Stanford Plumbing & Heating"
      }
    },
    {
      "name": "total_amount",
      "float_values": {
        "values": "1091.81"
      }
    },
  ]
}, 
"requestMetadata":{
  "userInfo":{
    "id": "user:USER_EMAIL_ID"
  }
}
}'

Carica da una macchina locale

REST

Richiesta:

curl --location --request POST --url https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/documents/ \
--header "Authorization: Bearer $(gcloud auth print-access-token)" \
--header "Content-Type: application/json; charset=utf-8" \
--data '{
"document": {
  "display_name": "TestDoc3",
  "document_schema_name": "projects/PROJECT_NUMBER/locations/LOCATION/documentSchemas/DOCUMENT_SCHEMA_ID",
  "inline_raw_document": "<bytes>",
  "properties": [
    {
      "name": "supplier_name",
      "text_values": {
        "values": "Stanford Plumbing & Heating"
      }
    },
    {
      "name": "total_amount",
      "float_values": {
        "values": "1091.81"
      }
    },
  ]
},
"requestMetadata": {
  "userInfo": {
    "id": "user:USER_EMAIL_ID"
  }
}
}'

Recupera un documento

Per document_id:

REST

curl --request POST \
--header "Authorization: Bearer $(gcloud auth print-access-token)" \
--header "Content-Type: application/json; charset=UTF-8" -d '{
  "requestMetadata":{
    "userInfo":{
      "id": "user:USER_EMAIL"
    }
  }
}' \
"https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/documents/DOCUMENT_ID:get"

Python

Per saperne di più, consulta la documentazione di riferimento dell'API Document AI Warehouse Python.

Per eseguire l'autenticazione in Document AI Warehouse, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 


from google.cloud import contentwarehouse


def sample_get_document(document_name: str, user_id: str) -> contentwarehouse.Document:
    """Gets a document.

    Args:
        document_name: The resource name of the document.
                Format: 'projects/{project_number}/
                locations/{location}/documents/{document_id}'.
        user_id: user:YOUR_SERVICE_ACCOUNT_ID or user:USER_EMAIL.
    Returns:
        Response object
    """
    # Create a client
    client = contentwarehouse.DocumentServiceClient()

    request_metadata = contentwarehouse.RequestMetadata(
        user_info=contentwarehouse.UserInfo(id=user_id)
    )

    # Initialize request argument(s)
    request = contentwarehouse.GetDocumentRequest(
        name=document_name, request_metadata=request_metadata
    )

    # Make the request
    response = client.get_document(request=request)

    return response

Java

Per saperne di più, consulta la Documentazione di riferimento dell'Java API di Document AI Warehouse.

Per eseguire l'autenticazione in Document AI Warehouse, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 


import com.google.cloud.contentwarehouse.v1.Document;
import com.google.cloud.contentwarehouse.v1.DocumentName;
import com.google.cloud.contentwarehouse.v1.DocumentServiceClient;
import com.google.cloud.contentwarehouse.v1.DocumentServiceSettings;
import com.google.cloud.contentwarehouse.v1.GetDocumentRequest;
import com.google.cloud.contentwarehouse.v1.RequestMetadata;
import com.google.cloud.contentwarehouse.v1.UserInfo;
import com.google.cloud.resourcemanager.v3.Project;
import com.google.cloud.resourcemanager.v3.ProjectName;
import com.google.cloud.resourcemanager.v3.ProjectsClient;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeoutException;

public class GetDocument {

  public static void getDocument() throws IOException, 
        InterruptedException, ExecutionException, TimeoutException {
    String projectId = "your-project-id";
    String location = "your-region"; // Format is "us" or "eu".
    String documentId = "your-document-id";
    String userId = "your-user-id"; // Format is user:<user-id>
    getDocument(projectId, location, documentId, userId);
  }

  // Retrieves details about existing Document using the document Id
  public static void getDocument(String projectId, String location, 
        String documentId, String userId) throws IOException, 
            InterruptedException, ExecutionException, TimeoutException {
    String projectNumber = getProjectNumber(projectId);

    String endpoint = "contentwarehouse.googleapis.com:443";
    if (!"us".equals(location)) {
      endpoint = String.format("%s-%s", location, endpoint);
    }
    DocumentServiceSettings documentServiceSettings = 
         DocumentServiceSettings.newBuilder().setEndpoint(endpoint).build(); 

    // Create a Document Service client
    try (DocumentServiceClient documentServiceClient =
        DocumentServiceClient.create(documentServiceSettings)) {
      /* The full resource name of the location, e.g.: 
       projects/{project_number}/location/{location}/documents/{document_id} */
      DocumentName documentName = 
          DocumentName.of(projectNumber, location, documentId);

      // Define Request Metadata for enforcing access control
      RequestMetadata requestMetadata = RequestMetadata.newBuilder()
            .setUserInfo(
            UserInfo.newBuilder()
              .setId(userId).build()).build();

      // Define request to get details of a specific Document Schema
      GetDocumentRequest getDocumentRequest = 
          GetDocumentRequest.newBuilder()
          .setName(documentName.toString())
          .setRequestMetadata(requestMetadata).build();

      // Get details of the Document 
      Document document = documentServiceClient.getDocument(getDocumentRequest);

      System.out.println(document.getName());
    }
  }

  private static String getProjectNumber(String projectId) throws IOException { 
    /* Initialize client that will be used to send requests. 
    * This client only needs to be created once, and can be reused for multiple requests. */
    try (ProjectsClient projectsClient = ProjectsClient.create()) { 
      ProjectName projectName = ProjectName.of(projectId); 
      Project project = projectsClient.getProject(projectName);
      String projectNumber = project.getName(); // Format returned is projects/xxxxxx
      return projectNumber.substring(projectNumber.lastIndexOf("/") + 1);
    } 
  }
}

Node.js

Per saperne di più, consulta la documentazione di riferimento dell'API Document AI Warehouse Node.js.

Per eseguire l'autenticazione in Document AI Warehouse, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 


/**
 * TODO(developer): Uncomment these variables before running the sample.
 * const projectNumber = 'YOUR_PROJECT_NUMBER';
 * const location = 'YOUR_PROJECT_LOCATION'; // Format is 'us' or 'eu'
 * documentId = 'YOUR_DOCUMENT_ID';
 * const userId = 'user:xxx@example.com'; // Format is "user:xxx@example.com"
 */

// Import from google cloud
const {DocumentServiceClient} = require('@google-cloud/contentwarehouse').v1;

const apiEndpoint =
  location === 'us'
    ? 'contentwarehouse.googleapis.com'
    : `${location}-contentwarehouse.googleapis.com`;

// Create service client
const serviceClient = new DocumentServiceClient({
  apiEndpoint: apiEndpoint,
});

// Get Document Schema
async function getDocument() {
  // Initialize request argument(s)
  const documentRequest = {
    // The full resource name of the document, e.g.:
    // projects/{project_number}/locations/{location}/documents/{document_id}
    name: serviceClient.projectLocationDocumentPath(
      projectNumber,
      location,
      documentId
    ),
    requestMetadata: {userInfo: {id: userId}},
  };

  // Make Request
  const response = serviceClient.getDocument(documentRequest);

  // Print out response
  response.then(
    result => console.log(`Document Found: ${JSON.stringify(result)}`),
    error => console.log(`${error}`)
  );
}

Per reference_id:

  curl --request POST \
    --header "Authorization: Bearer $(gcloud auth print-access-token)" \
    --header "Content-Type: application/json; charset=UTF-8" -d '{
      "requestMetadata":{
        "userInfo":{
          "id": "user:USER_EMAIL"
        }
      }
    }' \
    "https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/documents/referenceId/REFERENCE_ID:get"

Aggiorna un documento

Per document_id:

REST

posix-terminal curl --location --request POST --url https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/documents \ --header "Authorization: Bearer $(gcloud auth print-access-token)" \ --header "Content-Type: application/json; charset=utf-8" \ --data '{ "document": { "display_name": "TestDoc3", "document_schema_name": "projects/PROJECT_NUMBER/locations/LOCATION/documentSchemas/DOCUMENT_SCHEMA_ID", "raw_document_path": "gs://BUCKET_URI/FILE_URI", "properties": [ { "name": "supplier_name", "text_values": { "values": "Stanford Plumbing & Heating" } }, { "name": "total_amount", "float_values": { "values": "1091.81" } }, { "name": "invoice_id", "text_values": { "values": "invoiceid" } }, ] }, "requestMetadata": { "userInfo": { "id": "user:USER_EMAIL" } } }'

Python

Per saperne di più, consulta la documentazione di riferimento dell'API Document AI Warehouse Python.

Per eseguire l'autenticazione in Document AI Warehouse, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 


from google.cloud import contentwarehouse


def sample_update_document(
    document_name: str, document: contentwarehouse.Document, user_id: str
) -> contentwarehouse.CreateDocumentResponse:
    """Updates a document.

    Args:
        document_name: The resource name of the document.
                    Format: 'projects/{project_number}/
                    locations/{location}/documents/{document_id}'.
        document: Document AI Warehouse Document object..
        user_id: user_id: user:YOUR_SERVICE_ACCOUNT_ID or user:USER_EMAIL.
    Returns:
        Response object.
    """
    # Create a client
    client = contentwarehouse.DocumentServiceClient()

    # Update document fields
    # For fields which can be updated, refer
    # https://cloud.google.com/python/docs/reference/contentwarehouse/
    # latest/google.cloud.contentwarehouse_v1.types.Document
    document.display_name = "Updated Order Invoice"

    request_metadata = contentwarehouse.RequestMetadata(
        user_info=contentwarehouse.UserInfo(id=user_id)
    )

    request = contentwarehouse.UpdateDocumentRequest(
        name=document_name, document=document, request_metadata=request_metadata
    )

    # Make the request
    response = client.update_document(request=request)

    return response

Java

Per saperne di più, consulta la Documentazione di riferimento dell'Java API di Document AI Warehouse.

Per eseguire l'autenticazione in Document AI Warehouse, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

import com.google.cloud.contentwarehouse.v1.Document;
import com.google.cloud.contentwarehouse.v1.DocumentName;
import com.google.cloud.contentwarehouse.v1.DocumentServiceClient;
import com.google.cloud.contentwarehouse.v1.DocumentServiceSettings;
import com.google.cloud.contentwarehouse.v1.GetDocumentRequest;
import com.google.cloud.contentwarehouse.v1.RequestMetadata;
import com.google.cloud.contentwarehouse.v1.UpdateDocumentRequest;
import com.google.cloud.contentwarehouse.v1.UpdateDocumentResponse;
import com.google.cloud.contentwarehouse.v1.UserInfo;
import com.google.cloud.resourcemanager.v3.Project;
import com.google.cloud.resourcemanager.v3.ProjectName;
import com.google.cloud.resourcemanager.v3.ProjectsClient;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeoutException;

public class UpdateDocument {
  public static void updateDocument() throws IOException, 
        InterruptedException, ExecutionException, TimeoutException { 
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String location = "your-region"; // Format is "us" or "eu".
    String documentId = "your-document-id";
    String userId = "your-user-id"; // Format is user:<user-id>
    /* The below method call retrieves details about the document you are about to update.
    * It is important to note that some properties cannot be edited or removed. 
    * For more information on managing documents, please see the below documentation.
    * https://cloud.google.com/document-warehouse/docs/manage-documents */
    GetDocument.getDocument(projectId, location, documentId, userId);
    updateDocument(projectId, location, documentId, userId);
  }

  // Updates an existing Document
  public static void updateDocument(String projectId, String location,
        String documentId, String userId) throws IOException, InterruptedException,
          ExecutionException, TimeoutException { 
    String projectNumber = getProjectNumber(projectId);

    String endpoint = "contentwarehouse.googleapis.com:443";
    if (!"us".equals(location)) {
      endpoint = String.format("%s-%s", location, endpoint);
    }

    DocumentServiceSettings documentServiceSettings = 
             DocumentServiceSettings.newBuilder().setEndpoint(endpoint).build(); 

    /* Create the Document Service Client 
     * Initialize client that will be used to send requests. 
     * This client only needs to be created once, and can be reused for multiple requests. */
    try (DocumentServiceClient documentServiceClient = 
            DocumentServiceClient.create(documentServiceSettings)) {

      /* The full resource name of the location, e.g.: 
       projects/{project_number}/location/{location}/documentSchemas/{document_schema_id} */
      DocumentName documentName = 
          DocumentName.of(projectNumber, location, documentId);

      // Define RequestMetadata object for context of the user making the API call
      RequestMetadata requestMetadata = RequestMetadata.newBuilder()
          .setUserInfo(
          UserInfo.newBuilder()
            .setId(userId).build()).build();

      // Get the document to retreive the document schema associated with the object
      GetDocumentRequest getDocumentRequest = GetDocumentRequest.newBuilder()
          .setName(documentName.toString())
          .setRequestMetadata(requestMetadata)
          .build(); 

      // Execute the request and store response in a document object
      Document document = documentServiceClient.getDocument(getDocumentRequest);

      // Define the updates to the document that will be passed in the request
      Document updatedDocument = Document.newBuilder()
          .setDisplayName("Updated Document Display Name")
          .setDocumentSchemaName(document.getDocumentSchemaName()).build();

      // Create the request to Update the Document
      UpdateDocumentRequest updateDocumentRequest = 
            UpdateDocumentRequest.newBuilder()
              .setName(documentName.toString())
              .setDocument(updatedDocument)
              .setRequestMetadata(requestMetadata)
              .build();

      // Update Document and receive response
      UpdateDocumentResponse updateDocumentResponse = 
          documentServiceClient.updateDocument(updateDocumentRequest);

      // Read the output of Updated Document Name
      System.out.println(updateDocumentResponse.getDocument().getDisplayName());
    }
  }

  private static String getProjectNumber(String projectId) throws IOException { 
    /* Initialize client that will be used to send requests. 
    * This client only needs to be created once, and can be reused for multiple requests. */
    try (ProjectsClient projectsClient = ProjectsClient.create()) { 
      ProjectName projectName = ProjectName.of(projectId); 
      Project project = projectsClient.getProject(projectName);
      String projectNumber = project.getName(); // Format returned is projects/xxxxxx
      return projectNumber.substring(projectNumber.lastIndexOf("/") + 1);
    } 
  }
}

Per reference_id:

  curl --location --request POST --url https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/documents \
--header "Authorization: Bearer $(gcloud auth print-access-token)" \
--header "Content-Type: application/json; charset=utf-8" \
--data '{
  "document": {
    "display_name": "TestDoc3",
    "document_schema_name": "projects/PROJECT_NUMBER/locations/LOCATION/documentSchemas/referenceId/REFERENCE_ID",
    "raw_document_path": "gs://BUCKET_URI/FILE_URI",
    "properties": [
      {
        "name": "supplier_name",
        "text_values": {
          "values": "Stanford Plumbing & Heating"
        }
      },
      {
        "name": "total_amount",
        "float_values": {
          "values": "1091.81"
        }
      },
      {
        "name": "invoice_id",
        "text_values": {
          "values": "invoiceid"
        }
      },
    ]
  },
  "requestMetadata": {
    "userInfo": {
      "id": "user:USER_EMAIL"
    }
  }
}'

Elimina un documento

REST

Per document_id:

curl --request POST \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "Content-Type: application/json; charset=UTF-8" -d '{
    "requestMetadata":{
      "userInfo":{
        "id": "user:USER_EMAIL"
      }
    }
  }' \
  "https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/documents/DOCUMENT_ID:delete"

Per reference_id:

curl --request POST \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "Content-Type: application/json; charset=UTF-8" -d '{
    "requestMetadata":{
      "userInfo":{
        "id": "user:USER_EMAIL"
      }
    }
  }' \
  "https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/documents/referenceId/REFERENCE_ID":delete"

Passaggi successivi