Guida rapida

Questa guida fornisce tutte le procedure di configurazione necessarie per iniziare a utilizzare Document AI Warehouse.

Informazioni sulla console Google Cloud

Google Cloud console è un'interfaccia utente web utilizzata per eseguire il provisioning, configurare, gestire e monitorare i sistemi che utilizzano i prodotti Google Cloud . Utilizzi la consoleGoogle Cloud per configurare e gestire le risorse di Document AI Warehouse.

Crea un progetto

Per utilizzare i servizi forniti da Google Cloud, devi creare un progetto.

che organizza tutte le risorse Google Cloud . Un progetto è costituito dai seguenti componenti:

  • Un insieme di collaboratori
  • API abilitate (e altre risorse)
  • Strumenti di monitoraggio
  • Dati di fatturazione
  • Autenticazione e controlli dell'accesso

Puoi creare un progetto o più progetti. Puoi utilizzare i progetti per organizzare le risorse di Google Cloud in una gerarchia di risorse. Per ulteriori informazioni sui progetti, consulta la documentazione di Resource Manager.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

  • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
  • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Abilita fatturazione

Un account di fatturazione definisce chi paga per un determinato insieme di risorse. Gli account di fatturazione possono essere collegati a uno o più progetti. L'utilizzo del progetto viene addebitato all'account di fatturazione collegato. Puoi configurare la fatturazione quando crei un progetto. Per maggiori informazioni, consulta la documentazione sulla fatturazione.

Verify that billing is enabled for your Google Cloud project.

Esegui il provisioning e inizializza il servizio

Prima di utilizzare Document AI Warehouse per la prima volta, devi eseguire il provisioning e l'inizializzazione delle risorse associate al tuo progetto nella pagina di provisioning di Document AI Warehouse.

Se vuoi eseguire il provisioning delle risorse, devi disporre dei ruoli Amministratore di Content Warehouse e Amministratore utilizzo dei servizi del progetto.

Passaggi di provisioning

  1. Scegli una regione.

    Nella pagina di provisioning, seleziona la regione che vuoi attivare.

    Ogni regione è indipendente. Pertanto, se vuoi utilizzare più di una regione, esegui il provisioning di ciascuna regione separatamente.

  2. Abilita l'API principale. {:#enable-core-api}:

    Fai clic su Attiva. Vengono abilitate le API Document AI Warehouse nel tuo progetto.

    Dopo aver abilitato l'API, fai clic su Avanti.

  3. Esegui il provisioning dell'istanza.

    Questo passaggio esegue il provisioning della risorsa per il tuo progetto nel servizio Document AI Warehouse. Devi scegliere tra tre modalità di controllo dell'accesso. Esaminali attentamente per selezionare le modalità giuste per il tuo caso d'uso. Per saperne di più, consulta la pagina sulla modalità di controllo dell'accesso.

    1. Seleziona una modalità di controllo dell'accesso (ACL).

      • [Consigliato] controllo dell'accesso a livello di documento con gli utenti in Cloud Identity.

        Ciò è applicabile se la tua organizzazione gestisce utenti o gruppi nel servizio Cloud Identity.

      • Controllo dell'accesso a livello di documento con gli utenti nel servizio Bring Your Own Identity.

        Se non è possibile aggiungere o sincronizzare gli utenti con Cloud Identity, usa questa modalità. Tuttavia:

        • L'interfaccia di Document AI Warehouse non supporta questa modalità, potrebbe essere necessaria un'applicazione client personalizzata.
        • La tua applicazione client personalizzata autentica gli utenti in base al provider di identità e passa gli utenti e le iscrizioni ai gruppi utilizzando l'API Document AI Warehouse.

      • Accesso universale: nessun controllo dell'accesso a livello di documento.

        • L'interfaccia di Document AI Warehouse supporta questa modalità per autenticare gli utenti.
        • Questa modalità viene in genere usata per concedere l'accesso agli utenti pubblici senza richiedere l'autenticazione.
        • I portali personalizzati possono accedere a tutti i documenti utilizzando un service account con il ruolo desiderato (ad esempio il ruolo Visualizzatore documenti) e possono trasferire questo accesso agli utenti pubblici senza autenticazione.
      Controllo dell'controllo dell'accesso a livello di documento con gli utenti in Cloud Identity controllo dell'accesso a livello di documento con gli utenti nel servizio Bring your own Identity Accesso universale
      Accesso a livello di documento Sì Sì No
      Supporto UI di Document AI Warehouse Sì No Sì (se gli utenti hanno accesso a livello di progetto)

    2. Attiva domande e risposte:

      Seleziona Domande e risposte se vuoi attivare la ricerca GenAI nel tuo progetto. Per saperne di più, consulta Ricerca GenAI, incluso come ottenere l'inserimento nella lista consentita per utilizzare la funzionalità.

  4. Attiva provisioning:

    Fai clic su Provisioning per avviare il provisioning del progetto. La configurazione dell'istanza richiede un po' di tempo (3-5 minuti).

  5. Crea uno schema predefinito.

    Fai clic su Crea nel passaggio di inizializzazione. Viene creato uno schema predefinito che può essere utilizzato per PDF o file TXT estratti con l'OCR. Contiene il campo di testo non elaborato per l'indicizzazione, ma non contiene proprietà.

  6. Visualizza istanza:

    In questo modo, la procedura di provisioning viene completata. Se il tuo progetto utilizza controllo dell'accesso a livello di documento, vai alla sezione successiva per configurare le autorizzazioni a livello di progetto.

    Se fai parte della lista consentita per le funzionalità dell'interfaccia utente della console Google Cloud , puoi fare clic su Inizia per iniziare a utilizzare Document AI Warehouse nella console Google Cloud .

    Se non sei nella lista consentita per le funzionalità della UI della console, puoi procedere con la configurazione dell'applicazione web per scoprire come configurare l'applicazione web Document AI Warehouse. Google Cloud

  7. Configura le autorizzazioni richieste in IAM per i tuoi utenti. Se controllo dell'accesso a livello di documento è abilitato, sono necessarie le autorizzazioni a livello di progetto e IAM. Per saperne di più, consulta le autorizzazioni richieste.

Configurare le autorizzazioni a livello di progetto

Se il tuo progetto attiva controllo dell'accesso a livello di documento (opzione 1 in Selezione della modalità ACL), devi concedere al tuo account amministratore e ai tuoi utenti le autorizzazioni a livello di progetto.

Per farlo, nella visualizzazione finale dopo il provisioning, vai a Autorizzazioni progetto:

Segui i passaggi riportati di seguito per aggiungere il tuo account amministratore come Amministratore documenti:

  1. Fai clic su Aggiungi utente.

  2. Inserisci l'email dell'amministratore e scegli Amministratore documenti come livello di accesso. Fai clic su Salva.

  3. Per gli altri utenti, puoi aggiungerli come:

    1. Amministratore documenti: un ruolo con accesso completo a tutti i documenti del progetto, inclusi il caricamento di documenti e la visualizzazione/modifica/eliminazione di tutti i documenti indipendentemente dai proprietari dei documenti. Inoltre, gli amministratori dei documenti possono modificare le autorizzazioni di tutti i documenti.

    2. Editor di documenti: un ruolo con autorizzazioni di visualizzazione e modifica per tutti i documenti, ma non può creare ed eliminare documenti nel progetto e non può modificare le autorizzazioni dei documenti.

    3. Visualizzatore documenti: un ruolo con solo le autorizzazioni di visualizzazione per tutti i documenti. I visualizzatori di documenti non possono creare, modificare, eliminare o modificare le autorizzazioni dei documenti.

    4. Creatore documenti: un ruolo con solo autorizzazioni di caricamento dei documenti. I creatori di documenti dispongono di tutte le autorizzazioni per i documenti che caricano, ma non hanno altre autorizzazioni per altri documenti, a meno che non ottengano autorizzazioni esplicite per questi documenti.

  4. L'email può essere quella di un singolo utente o di un gruppo. Scegli Gruppo nel campo Tipo quando specifichi un'email di gruppo.

Autorizzazioni obbligatorie

In Document AI Warehouse, abbiamo un sistema ACL indipendente oltre a IAM. Per i progetti ACL a livello di documento, devi ottenere autorizzazioni aggiuntive a livello di progetto nel sistema ACL di Document AI Warehouse. Per i progetti di accesso universale, sono richieste solo le autorizzazioni IAM.

Di seguito sono riportate le tabelle riepilogative delle autorizzazioni richieste:

Progetti ACL dei documenti

Tipo di utente Ruolo IAM Autorizzazioni a livello di progetto di Document AI Warehouse
Utenti amministratori Content Warehouse Admin Amministratore documenti
Utenti normali Content Warehouse document Schema Viewer Document Creator/Editor/Visualizzatore, a seconda delle autorizzazioni previste

Progetti di accesso universale

Tipo di utente Ruolo IAM
Utenti amministratori 1. Content Warehouse Admin
2. Amministratore documenti Content Warehouse
Utenti normali 1. Visualizzatore dello schema dei documenti di Content Warehouse
2. Content Warehouse document creator/viewer/editor, a seconda delle autorizzazioni previste
Ruoli IAM per i progetti di accesso universale
Titolo del ruolo Nome ruolo Finalità
Content Warehouse document creator contentwarehouse.documentCreator Creare documenti
Visualizzatore documenti Content Warehouse contentwarehouse.documentViewer Visualizzazione di eventuali documenti
Editor documenti Content Warehouse contentwarehouse.documentEditor Modifica di qualsiasi documento (non include la creazione e l'eliminazione)
Amministratore documenti Content Warehouse contentwarehouse.documentAdmin Gestione di tutti i documenti (inclusi creazione ed eliminazione)
Content Warehouse Admin contentwarehouse.admin Gestione di documenti, schemi e regole

Per ulteriori dettagli, consulta Ruoli e autorizzazioni IAM.

Configurare il token di accesso (per chiamare l'API dalla riga di comando)

Per chiamare l'API Document AI Warehouse con gli strumenti a riga di comando, segui questi passaggi.

Utilizzare il file delle chiavi per l'account di servizio nel tuo ambiente

Provide authentication credentials to your application code by setting the environment variable GOOGLE_APPLICATION_CREDENTIALS. This variable applies only to your current shell session. If you want the variable to apply to future shell sessions, set the variable in your shell startup file, for example in the ~/.bashrc or ~/.profile file.

Linux o macOS

export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

Replace KEY_PATH with the path of the JSON file that contains your credentials.

For example:

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

Windows

For PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

Replace KEY_PATH with the path of the JSON file that contains your credentials.

For example:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

For command prompt:

set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

Replace KEY_PATH with the path of the JSON file that contains your credentials.

(Facoltativo) Installa e inizializza Google Cloud CLI

La CLI gcloud fornisce un insieme di strumenti che puoi utilizzare per gestire le risorse e le applicazioni ospitate su Google Cloud.

Il seguente link fornisce le istruzioni:

Installa Google Cloud CLI. Dopo l'installazione, inizializza Google Cloud CLI eseguendo il comando seguente: 

gcloud init

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Genera il token di accesso

Se hai configurato l'autenticazione nei passaggi precedenti, puoi utilizzare Google Cloud CLI per testare l'ambiente di autenticazione. Esegui il seguente comando e verifica che non si verifichi alcun errore e che vengano restituite le credenziali:

AUTH_TOKEN=$(gcloud auth application-default print-access-token --scopes=https://www.googleapis.com/auth/cloud-platform)

Prevedi che AUTH_TOKEN sia impostato, ad esempio:

$ echo $AUTH_TOKEN
ya29.c.b0AXv0zTPvXmEMZXCe781qL0Y3r1EKnw3k4DJcoWGZkyWKx-nMNVQVErQ3ge6XA2RXsTU1tf_SMLgeWC6xwS51tP8QZhbypuGczBzMgKWYExwATHt3Vn553edl8tmqCMjROgdQjCDd8i7as-236r4d8gNwKsR192gNgNw_0zzs0MPyNVmqydpfmpj8yBwJI5QWna1331GTGKgd3Ia16fTzAHrZC_GkcO0wJPo....................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................

Testa la chiamata all'API Document AI Warehouse

AUTH_TOKEN viene utilizzato da tutti gli esempi REST dell'API Document AI Warehouse per autenticare le chiamate API. Ad esempio, il seguente comando recupera tutti gli schemi di documenti che hai definito e che sono associati al tuo progetto (nella maggior parte dei casi, utilizza "us" come località):

  curl --header "Authorization: Bearer $AUTH_TOKEN" https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER>/locations/LOCATION/documentSchemas

Esempi di codice

Java

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

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. 

public class QuickStart {

  public static void main(String[] args)
      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 userId = "your-user-id"; // Format is user:<user-id>
    quickStart(projectId, location, userId);
  }

  public static void quickStart(String projectId, String location, 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);
    }
    DocumentSchemaServiceSettings documentSchemaServiceSettings = 
         DocumentSchemaServiceSettings.newBuilder().setEndpoint(endpoint).build(); 

    // Create a Schema Service client
    try (DocumentSchemaServiceClient documentSchemaServiceClient =
        DocumentSchemaServiceClient.create(documentSchemaServiceSettings)) {
      /*  The full resource name of the location, e.g.:
      projects/{project_number}/locations/{location} */
      String parent = LocationName.format(projectNumber, location);

      /* Create Document Schema with Text Type Property Definition
       * More detail on managing Document Schemas: 
       * https://cloud.google.com/document-warehouse/docs/manage-document-schemas */
      DocumentSchema documentSchema = DocumentSchema.newBuilder()
          .setDisplayName("My Test Schema")
          .setDescription("My Test Schema's Description")
          .addPropertyDefinitions(
            PropertyDefinition.newBuilder()
              .setName("test_symbol")
              .setDisplayName("Searchable text")
              .setIsSearchable(true)
              .setTextTypeOptions(TextTypeOptions.newBuilder().build())
              .build()).build();

      // Define Document Schema request
      CreateDocumentSchemaRequest createDocumentSchemaRequest =
          CreateDocumentSchemaRequest.newBuilder()
            .setParent(parent)
            .setDocumentSchema(documentSchema).build();

      // Create Document Schema
      DocumentSchema documentSchemaResponse =
          documentSchemaServiceClient.createDocumentSchema(createDocumentSchemaRequest); 


      // Create Document Service Client Settings
      DocumentServiceSettings documentServiceSettings = 
          DocumentServiceSettings.newBuilder().setEndpoint(endpoint).build();

      // Create Document Service Client and Document with relevant properties 
      try (DocumentServiceClient documentServiceClient =
          DocumentServiceClient.create(documentServiceSettings)) {
        TextArray textArray = TextArray.newBuilder().addValues("Test").build();
        Document document = Document.newBuilder()
              .setDisplayName("My Test Document")
              .setDocumentSchemaName(documentSchemaResponse.getName())
              .setPlainText("This is a sample of a document's text.")
              .addProperties(
                Property.newBuilder()
                  .setName(documentSchema.getPropertyDefinitions(0).getName())
                  .setTextValues(textArray)).build();

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

        // Define Create Document Request 
        CreateDocumentRequest createDocumentRequest = CreateDocumentRequest.newBuilder()
            .setParent(parent)
            .setDocument(document)
            .setRequestMetadata(requestMetadata)
            .build();

        // Create Document
        CreateDocumentResponse createDocumentResponse =
            documentServiceClient.createDocument(createDocumentRequest);

        System.out.println(createDocumentResponse.getDocument().getName());
        System.out.println(documentSchemaResponse.getName());
      }
    }
  }

  private static String getProjectNumber(String projectId) throws IOException { 
    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'
 * const userId = 'user:xxx@example.com'; // Format is "user:xxx@example.com"
 */

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

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

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

// Get Document Schema
async function quickstart() {
  // The full resource name of the location, e.g.:
  // projects/{project_number}/locations/{location}
  const parent = `projects/${projectNumber}/locations/${location}`;

  // Initialize request argument(s)
  const schemaRequest = {
    parent: parent,
    documentSchema: {
      displayName: 'My Test Schema',
      propertyDefinitions: [
        {
          name: 'testPropertyDefinitionName', // Must be unique within a document schema (case insensitive)
          displayName: 'searchable text',
          isSearchable: true,
          textTypeOptions: {},
        },
      ],
    },
  };

  // Create Document Schema
  const documentSchema =
    await schemaClient.createDocumentSchema(schemaRequest);

  const documentRequest = {
    parent: parent,
    document: {
      displayName: 'My Test Document',
      documentSchemaName: documentSchema[0].name,
      plainText: "This is a sample of a document's text.",
      properties: [
        {
          name: 'testPropertyDefinitionName',
          textValues: {values: ['GOOG']},
        },
      ],
    },
    requestMetadata: {userInfo: {id: userId}},
  };

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

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

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

# TODO(developer): Uncomment these variables before running the sample.
# project_number = 'YOUR_PROJECT_NUMBER'
# location = 'YOUR_PROJECT_LOCATION' # Format is 'us' or 'eu'
# user_id = "user:xxxx@example.com" # Format is "user:xxxx@example.com"


def quickstart(project_number: str, location: str, user_id: str) -> None:
    # Create a Schema Service client
    document_schema_client = contentwarehouse.DocumentSchemaServiceClient()

    # The full resource name of the location, e.g.:
    # projects/{project_number}/locations/{location}
    parent = document_schema_client.common_location_path(
        project=project_number, location=location
    )

    # Define Schema Property of Text Type
    property_definition = contentwarehouse.PropertyDefinition(
        name="stock_symbol",  # Must be unique within a document schema (case insensitive)
        display_name="Searchable text",
        is_searchable=True,
        text_type_options=contentwarehouse.TextTypeOptions(),
    )

    # Define Document Schema Request
    create_document_schema_request = contentwarehouse.CreateDocumentSchemaRequest(
        parent=parent,
        document_schema=contentwarehouse.DocumentSchema(
            display_name="My Test Schema",
            property_definitions=[property_definition],
        ),
    )

    # Create a Document schema
    document_schema = document_schema_client.create_document_schema(
        request=create_document_schema_request
    )

    # Create a Document Service client
    document_client = contentwarehouse.DocumentServiceClient()

    # The full resource name of the location, e.g.:
    # projects/{project_number}/locations/{location}
    parent = document_client.common_location_path(
        project=project_number, location=location
    )

    # Define Document Property Value
    document_property = contentwarehouse.Property(
        name=document_schema.property_definitions[0].name,
        text_values=contentwarehouse.TextArray(values=["GOOG"]),
    )

    # Define Document
    document = contentwarehouse.Document(
        display_name="My Test Document",
        document_schema_name=document_schema.name,
        plain_text="This is a sample of a document's text.",
        properties=[document_property],
    )

    # Define Request
    create_document_request = contentwarehouse.CreateDocumentRequest(
        parent=parent,
        document=document,
        request_metadata=contentwarehouse.RequestMetadata(
            user_info=contentwarehouse.UserInfo(id=user_id)
        ),
    )

    # Create a Document for the given schema
    response = document_client.create_document(request=create_document_request)

    # Read the output
    print(f"Rule Engine Output: {response.rule_engine_output}")
    print(f"Document Created: {response.document}")

Passaggi successivi