Guía de inicio rápido

En esta guía, se proporcionan todos los pasos de configuración necesarios para comenzar a usar Document AI Warehouse.

Acerca de la consola de Google Cloud

La Google Cloud console es una IU web que se usa para aprovisionar, configurar, administrar y supervisar sistemas que usan productos de Google Cloud . Usas la consola deGoogle Cloud para configurar y administrar los recursos de Document AI Warehouse.

Crea un proyecto

Para usar los servicios que proporciona Google Cloud, debes crear un proyecto.

Un proyecto organiza todos tus recursos de Google Cloud . Un proyecto consta de los siguientes componentes:

un conjunto de colaboradores
API habilitadas (y otros recursos)
Herramientas de supervisión
Información de facturación
controles de autenticación y acceso

Puedes crear uno o varios proyectos Puedes usar tus proyectos para organizar tus recursos de Google Cloud en una jerarquía de recursos. Para obtener más información sobre los proyectos, consulta la documentación de 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

Habilitar facturación

Una cuenta de facturación define quién paga un determinado conjunto de recursos. Las cuentas de facturación se pueden vincular a uno o más proyectos. El uso del proyecto se cobra a la cuenta de facturación vinculada. Puedes configurar la facturación cuando creas un proyecto. Para obtener más información, consulta la documentación de facturación.

Verify that billing is enabled for your Google Cloud project.

Aprovisiona e inicializa el servicio

Antes de usar Document AI Warehouse por primera vez, debes aprovisionar e inicializar los recursos asociados con tu proyecto en la página de aprovisionamiento de Document AI Warehouse.

Si deseas aprovisionar los recursos, debes tener los roles de administrador de Content Warehouse y administrador de Service Usage del proyecto.

Pasos de aprovisionamiento

Elige una región.

En la página de aprovisionamiento, selecciona la región que deseas habilitar.

Cada región es independiente. Por lo tanto, si deseas usar más de una región, aprovisiona cada una por separado.
Habilita la API principal. {:#enable-core-api}:

Haz clic en Habilitar. Esto habilita las APIs de Document AI Warehouse en tu proyecto.

Después de habilitar la API, haz clic en Siguiente.

Aprovisiona la instancia.

En este paso, se aprovisiona el recurso para tu proyecto en el servicio de Document AI Warehouse. Debes elegir entre tres modos de control de acceso. Revísalos con atención para seleccionar los modos adecuados para tu caso de uso. Para obtener más información, consulta la página del modo de control de acceso.

Selecciona un modo de control de acceso (LCA).

[Recomendado] Control de acceso a nivel de documento con usuarios en Cloud Identity.

Esto se aplica si tu organización administra usuarios o grupos en el servicio de Cloud Identity.
- La interfaz de Document AI Warehouse admite este modo para autenticar a los usuarios.
- Los usuarios y grupos de LDAP y Active Directory de tu organización se pueden sincronizar con Cloud Identity.
- Los usuarios de Google Workspace se pueden agregar con facilidad a Cloud Identity.
Control de acceso a nivel de documento con usuarios en el control de acceso al servicio Bring-your-own Identity.

Si no se pueden agregar ni sincronizar tus usuarios con Cloud Identity, usa este modo. Sin embargo, debes tener en cuenta lo siguiente:
- La interfaz de Document AI Warehouse no admite este modo, por lo que es posible que se necesite una aplicación cliente personalizada.
- Tu aplicación cliente personalizada autentica a los usuarios en el proveedor de identidad y pasa los usuarios y las membresías de grupo con la API de Document AI Warehouse.
Acceso universal: Sin control de acceso a nivel de documento.
- La interfaz de Document AI Warehouse admite este modo para autenticar a los usuarios.
- Por lo general, este modo se usa para otorgar acceso a usuarios públicos sin requerir autenticación.
- Los portales personalizados pueden acceder a todos los documentos por medio de una cuenta de servicio con el rol deseado (por ejemplo, el rol de visualizador de documentos) y pueden transmitir este acceso a los usuarios públicos sin autenticación.

	Control de acceso a nivel de documento con usuarios en Cloud Identity	Control de acceso a nivel de documento con usuarios en el control de acceso al servicio Bring-your-own Identity	Acceso universal
Acceso a nivel del documento	Sí	Sí	No
Compatibilidad con la IU de Document AI Warehouse	Sí	No	Sí (si los usuarios tienen acceso a nivel del proyecto)

Habilita la opción de preguntas y respuestas:

Marca Preguntas y respuestas si deseas habilitar la búsqueda con IA generativa en tu proyecto. Consulta Búsqueda con IA generativa para obtener más información, incluido cómo obtener la aprobación para usar la función.

Activación del aprovisionamiento:

Haz clic en Aprovisionar para comenzar a aprovisionar tu proyecto. La configuración de la instancia tardará un tiempo (entre 3 y 5 minutos).
Crea un esquema predeterminado.

Haz clic en Crear en el paso de inicialización. Esto crea un esquema predeterminado que se puede usar para los archivos PDF o TXT extraídos con OCR. Contiene el campo de texto sin procesar para la indexación, pero no contiene propiedades.
Ver instancia:

Esto finaliza el proceso de aprovisionamiento. Si tu proyecto usa el control de acceso a nivel del documento, continúa con la siguiente sección para configurar los permisos a nivel del proyecto.

Si estás en la lista de entidades permitidas para las funciones de la IU de la consola de Google Cloud , puedes hacer clic en Comenzar para comenzar a usar Document AI Warehouse en la consola de Google Cloud .

Si no estás en la lista de entidades permitidas para las funciones de la IU de la consola, puedes continuar con la configuración de la aplicación web para aprender a configurar la aplicación web de Document AI Warehouse. Google Cloud
Configura los permisos necesarios en IAM para tus usuarios. Si el control de acceso a nivel del documento está habilitado, se requieren permisos a nivel del proyecto y permisos de IAM. Consulta los permisos obligatorios para obtener más detalles.

Cómo configurar permisos a nivel del proyecto

Si tu proyecto habilita el control de acceso a nivel del documento (opción 1 en Selección del modo de LCA), debes otorgar permisos a nivel del proyecto a tu cuenta de administrador y a tus usuarios.

Para ello, en la vista final después del aprovisionamiento, ve a Permisos del proyecto:

Sigue los pasos que se indican a continuación para agregar tu cuenta de administrador como administrador de documentos:

Haz clic en Agregar usuario.
Ingresa el correo electrónico del administrador y elige Administrador de documentos como el nivel de acceso. Haz clic en Guardar.
En el caso de otros usuarios, puedes agregarlos como:
1. Administrador de documentos: Es un rol con acceso completo a todos los documentos del proyecto, lo que incluye subir documentos y ver, editar o borrar todos los documentos, independientemente de quiénes sean sus propietarios. Además, los administradores de documentos pueden cambiar los permisos de todos los documentos.
2. Editor de documentos: Es un rol con permisos de visualización y edición para todos los documentos, pero no puede crear ni borrar documentos en el proyecto, ni cambiar los permisos de los documentos.
3. Visualizador de documentos: Es un rol con permisos de visualización para todos los documentos. Los usuarios que pueden ver documentos no pueden crear, editar, borrar ni cambiar los permisos de los documentos.
4. Creador de documentos: Es un rol con permisos solo para subir documentos. Los creadores de documentos tienen permisos completos para los documentos que suben, pero no tienen otros permisos para ningún otro documento, a menos que obtengan permisos explícitos para esos documentos.
El correo electrónico puede ser de un solo usuario o de un grupo. Elige Grupo en el campo Tipo cuando especifiques un correo electrónico de grupo.

Nota: Document AI Warehouse no admite la expansión del acceso a subgrupos. Si se otorgan permisos al grupo, los usuarios deben ser hijos directos dentro de un grupo.

Permisos necesarios

En Document AI Warehouse, tenemos un sistema de LCA independiente sobre IAM. En el caso de los proyectos de LCA a nivel del documento, debes obtener permisos adicionales a nivel del proyecto en el sistema de LCA de Document AI Warehouse. En el caso de los proyectos de acceso universal, solo se requieren permisos de IAM.

A continuación, se incluyen tablas de resumen de los permisos necesarios:

Proyectos de LCA de documentos

Tipo de usuario	Rol de IAM	Permisos a nivel del proyecto de Document AI Warehouse
Usuarios administradores	Administrador de Content Warehouse	Administrador de documentos
Usuarios normales	Visualizador de esquemas del documento de Content Warehouse	Creador, editor o visualizador de documentos, según los permisos previstos

Proyectos de acceso universal

Tipo de usuario	Rol de IAM
Usuarios administradores	1. Administrador de Content Warehouse 2. Administrador de documentos de Content Warehouse
Usuarios normales	1. Visualizador de esquemas del documento de Content Warehouse 2. Creador, visualizador o editor de documentos de Content Warehouse, según los permisos previstos

Roles de IAM para proyectos de acceso universal

Título del rol	Nombre del rol	Objetivo
Creador de documentos de Content Warehouse	`contentwarehouse.documentCreator`	Crea documentos
Visualizador de documentos de Content Warehouse	`contentwarehouse.documentViewer`	Visualizar cualquier documento
Editor de documentos de Content Warehouse	`contentwarehouse.documentEditor`	Editar documentos (no incluye la creación ni la eliminación)
Administrador de documentos de Content Warehouse	`contentwarehouse.documentAdmin`	Administrar cualquier documento (incluida la creación y eliminación)
Administrador de Content Warehouse	`contentwarehouse.admin`	Administrar documentos, esquemas y reglas

Consulta Roles y permisos de IAM para obtener más detalles.

Configura el token de acceso (para llamar a la API desde la línea de comandos)

Para llamar a la API de Document AI Warehouse con herramientas de línea de comandos, sigue estos pasos.

Usa el archivo de claves de la cuenta de servicio en tu entorno

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.

Instala y, luego, inicializa Google Cloud CLI (opcional)

La CLI de gcloud proporciona un conjunto de herramientas que puedes usar para administrar recursos y aplicaciones alojados en Google Cloud.

En el siguiente vínculo, se proporcionan instrucciones:

Instala Google Cloud CLI. Después de la instalación, inicializa Google Cloud CLI con el siguiente comando:

gcloud init

Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

Genera el token de acceso

Si ya configuraste la autenticación en los pasos anteriores, puedes usar Google Cloud CLI para probar tu entorno de autenticación. Ejecuta el siguiente comando y verifica que no se produzca ningún error y que se muestren las credenciales:

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

Espera que AUTH_TOKEN esté configurado, por ejemplo:

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

Prueba la llamada a la API de Document AI Warehouse

Todos los ejemplos de REST de la API de Document AI Warehouse usan AUTH_TOKEN para autenticar las llamadas a la API. Por ejemplo, el siguiente comando recupera todos los esquemas de documentos que definiste y que están asociados con tu proyecto (en la mayoría de los casos, usa "us" como ubicación):

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

Muestras de código

Java

Para obtener más información, consulta la documentación de referencia de la API de Document AI Warehouse Java.

Para autenticarte en Document AI Warehouse, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

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

Para obtener más información, consulta la documentación de referencia de la API de Document AI Warehouse Node.js.

/**
 * 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

Para obtener más información, consulta la documentación de referencia de la API de Document AI Warehouse Python.


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

Próximos pasos

Si usas la aplicación web (versión preliminar), continúa con Administra la IU de Document AI Warehouse para configurar la IU de Document AI Warehouse.
Continúa a Administrar el control de acceso para comprender y configurar el control de acceso.
Continúa a Administra esquemas de documentos para aprender a administrar los esquemas de documentos.
Continúa con Buscar documentos para aprender a buscar documentos.

Guía de inicio rápido Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Acerca de la consola de Google Cloud

Crea un proyecto

Habilitar facturación

Aprovisiona e inicializa el servicio

Pasos de aprovisionamiento

Cómo configurar permisos a nivel del proyecto

Permisos necesarios

Proyectos de LCA de documentos

Proyectos de acceso universal

Roles de IAM para proyectos de acceso universal

Configura el token de acceso (para llamar a la API desde la línea de comandos)

Usa el archivo de claves de la cuenta de servicio en tu entorno

Linux o macOS

Windows

Instala y, luego, inicializa Google Cloud CLI (opcional)

Genera el token de acceso

Prueba la llamada a la API de Document AI Warehouse

Muestras de código

Java

Node.js

Python

Próximos pasos

Guía de inicio rápido