Início rápido

Neste guia, você encontra todas as etapas de configuração necessárias para começar a usar o Document AI Warehouse.

Sobre o console do Google Cloud

O Google Cloud console é uma UI da Web usada para provisionar, configurar, gerenciar e monitorar sistemas que usam produtos do Google Cloud . Use o console doGoogle Cloud para configurar e gerenciar recursos do Document AI Warehouse.

Criar um projeto

Para usar os serviços fornecidos pelo Google Cloud, crie um projeto.

Um projeto organiza todos os seus recursos do Google Cloud . Um projeto consiste nos seguintes componentes:

Um grupo de colaboradores
APIs ativadas (e outros recursos)
Ferramentas de monitoramento
Informações de faturamento
Autenticação e controles de acesso

É possível criar um projeto ou vários projetos. É possível usar seus projetos para organizar os recursos do Google Cloud em uma hierarquia de recursos. Para mais informações sobre projetos, consulte a documentação do 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

Ativar faturamento

Uma conta de faturamento define quem paga por um determinado conjunto de recursos. As contas de faturamento podem ser vinculadas a um ou mais projetos. O uso do projeto é cobrado na conta de faturamento vinculada. Você configura o faturamento quando cria um projeto. Para mais informações, consulte a documentação de faturamento.

Verify that billing is enabled for your Google Cloud project.

Provisionar e inicializar o serviço

Antes de usar o Document AI Warehouse pela primeira vez, provisione e inicialize os recursos associados ao seu projeto na página de provisionamento do Document AI Warehouse.

Se você quiser provisionar os recursos, precisará ter os papéis Administrador do Content Warehouse e Administrador de uso do serviço do projeto.

Etapas de provisionamento

Escolha uma região.

Na página de provisionamento, selecione a região que você quer ativar.

Cada região é independente. Portanto, se você quiser usar mais de uma região, faça o provisionamento de cada uma separadamente.
Ative a API principal. {:#enable-core-api}:

Clique em Ativar. Isso ativa as APIs do Document AI Warehouse no seu projeto.

Depois que a API for ativada, clique em Próxima.

Provisione a instância.

Esta etapa provisiona o recurso para seu projeto no serviço Document AI Warehouse. É preciso escolher entre três modos de controle de acesso. Analise com cuidado para selecionar os modos certos para seu caso de uso. Para mais informações, consulte a página do modo de controle de acesso.

Selecione um modo de controle de acesso (ACL).

[Recomendado] Controle de acesso no nível do documento para usuários do Cloud Identity.

Isso é aplicável se sua organização gerencia usuários ou grupos no serviço Cloud Identity.
- A interface do Document AI Warehouse é compatível com esse modo para autenticar usuários.
- Os usuários e grupos da sua organização no LDAP e no Active Directory podem ser sincronizados com o Cloud Identity.
- Os usuários do Google Workspace podem ser facilmente adicionados ao Cloud Identity.
Controle de acesso no nível do documento para usuários com o controle de acesso ao serviço "Traga sua própria identidade".

Use este modo se não for possível adicionar ou sincronizar seus usuários com o Cloud Identity. No entanto:
- A interface do Document AI Warehouse não funciona com este modo. Pode ser que você precise usar um aplicativo cliente personalizado.
- Seu aplicativo cliente personalizado autentica os usuários com base no provedor de identidade e transmite as associações de usuários e grupos usando a API Document AI Warehouse.
Acesso universal: sem controle de acesso no nível do documento.
- A interface do Document AI Warehouse é compatível com esse modo para autenticar usuários.
- Em geral, é um modo usado para conceder acesso a usuários públicos sem exigir autenticação.
- Os portais personalizados podem acessar todos os documentos usando uma conta de serviço com o papel desejado (por exemplo, o papel de leitor de documentos) e redirecionar esse acesso a usuários públicos sem autenticação.

	Controle de acesso no nível do documento para usuários do Cloud Identity	Controle de acesso no nível do documento para usuários com o controle de acesso ao serviço "Traga sua própria identidade"	Acesso universal
Acesso no nível do documento	Sim	Sim	Não
Suporte à interface do Document AI Warehouse	Sim	Não	Sim (se os usuários tiverem acesso no nível do projeto)

Ative o recurso de perguntas e respostas:

Marque Perguntas e respostas se quiser ativar a pesquisa de IA generativa no seu projeto. Consulte Pesquisa de IA generativa para mais informações, incluindo como entrar na lista de permissão para usar o recurso.

Acionar provisionamento:

Clique em Provisionar para iniciar o provisionamento do projeto. A configuração da instância leva um tempo (de 3 a 5 minutos).
Crie um esquema padrão.

Clique em Criar na etapa de inicialização. Isso cria um esquema padrão que pode ser usado para PDFs ou arquivos TXT extraídos por OCR. Ele contém o campo de texto bruto para indexação, mas não contém propriedades.
Ver instância:

Isso finaliza o processo de provisionamento. Se o projeto usar controle de acesso no nível do documento, vá para a próxima seção para configurar as permissões no nível do projeto.

Se você estiver na lista de permissão para Google Cloud recursos da interface do console, clique em Começar para usar o Document AI Warehouse no console do Google Cloud .

Se você não estiver na lista de permissão para os recursos da UI console Google Cloud , siga para configurar o web app e saiba como configurar o web app do Document AI Warehouse.
Configure as permissões necessárias no IAM para seus usuários. Se o controle de acesso no nível do documento estiver ativado, serão necessárias permissões no nível do projeto e do IAM. Consulte permissões necessárias para mais detalhes.

Configurar permissões no nível do projeto

Se o projeto ativar o controle de acesso no nível do documento (opção 1 em Seleção do modo de ACL), conceda à sua conta de administrador e aos usuários permissões no nível do projeto.

Para fazer isso, na visualização final após o provisionamento, acesse Permissões do projeto:

Siga as etapas abaixo para adicionar sua conta de administrador como um administrador de documentos:

Clique em Adicionar usuário.
Insira o e-mail do administrador e escolha Administrador de documentos como o nível de acesso. Clique em Salvar.
Para outros usuários, você pode adicionar como:
1. Administrador de documentos: uma função com acesso total a todos os documentos do projeto, incluindo o upload, a visualização, a edição e a exclusão de todos os documentos, independente dos proprietários. Além disso, os administradores de documentos podem mudar as permissões de todos os documentos.
2. Editor de documentos: uma função com permissões de visualização e edição para todos os documentos, mas não pode criar e excluir documentos no projeto nem mudar as permissões deles.
3. Leitor de documentos: um papel com apenas as permissões de visualização de todos os documentos. Os leitores de documentos não podem criar, editar, excluir ou mudar as permissões dos documentos.
4. Criador de documentos: uma função com permissões apenas para upload de documentos. Os criadores de documentos têm permissões completas para os arquivos que enviam, mas não têm outras permissões para nenhum outro documento, a menos que recebam permissões explícitas para eles.
O e-mail pode ser de um único usuário ou de um grupo. Escolha Grupo no campo Tipo ao especificar um e-mail de grupo.

Observação: o Document AI Warehouse não é compatível com a expansão do acesso a subgrupos. Se as permissões forem concedidas ao grupo, os usuários precisarão ser filhos diretos em um grupo.

Permissões necessárias

No Document AI Warehouse, temos um sistema de ACL independente além do IAM. Para projetos de ACL no nível do documento, é necessário ter outras permissões no nível do projeto no sistema de ACL do Document AI Warehouse. Para projetos de acesso universal, apenas as permissões do IAM são necessárias.

Confira as tabelas de resumo das permissões necessárias:

Projetos de ACL de documentos

Tipo de usuário	Papel do IAM	Permissões no nível do projeto do Document AI Warehouse
Usuários administradores	Administrador do armazenamento de conteúdo	Administrador de documentos
Usuários comuns	Leitor de esquema de documento do armazenamento de conteúdo	Criador/editor/leitor de documentos, dependendo das permissões pretendidas

Projetos de acesso universal

Tipo de usuário	Papel do IAM
Usuários administradores	1. Administrador do armazenamento de conteúdo 2. Administrador de documentos do armazenamento de conteúdo
Usuários comuns	1. Leitor de esquema de documento do armazenamento de conteúdo 2. Criador/leitor/editor de documentos do armazenamento de conteúdo, dependendo das permissões pretendidas

Papéis do IAM para projetos de acesso universal

Título do papel	Nome do papel	Finalidade
Criador de documentos do armazenamento de conteúdo	`contentwarehouse.documentCreator`	Como criar documentos
Leitor de documentos do armazenamento de conteúdo	`contentwarehouse.documentViewer`	Visualizar qualquer documento
Editor de documentos do armazenamento de conteúdo	`contentwarehouse.documentEditor`	Edição de documentos (não inclui criação e exclusão)
Administrador de documentos do armazenamento de conteúdo	`contentwarehouse.documentAdmin`	Gerenciar documentos (incluindo criação e exclusão)
Administrador do armazenamento de conteúdo	`contentwarehouse.admin`	Gerenciar documentos, esquemas e regras

Consulte Papéis e permissões do IAM para mais detalhes.

Configurar o token de acesso (para chamar a API na linha de comando)

Para chamar a API Document AI Warehouse com ferramentas de linha de comando, siga estas etapas.

Usar o arquivo de chave da conta de serviço no seu 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 ou 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.

Instale e inicialize a Google Cloud CLI (opcional)

A CLI gcloud oferece um conjunto de ferramentas que podem ser usadas para gerenciar recursos e aplicativos hospedados no Google Cloud.

O link a seguir fornece as instruções:

Instale a CLI do Google Cloud. Após a instalação, inicialize a CLI do Google Cloud executando o seguinte comando:

gcloud init

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

Gerar o token de acesso

Se você tiver configurado a autenticação nas etapas anteriores, poderá usar a Google Cloud CLI para testar o ambiente de autenticação. Execute o comando a seguir e verifique se nenhum erro ocorre e se as credenciais são retornadas:

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

Espere que o AUTH_TOKEN esteja definido, por exemplo:

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

Testar a chamada da API Document AI Warehouse

O AUTH_TOKEN é usado por todas as amostras REST da API Document AI Warehouse para autenticar chamadas de API. Por exemplo, o comando a seguir recupera todos os esquemas de documentos definidos e associados ao seu projeto. Na maioria dos casos, use "us" como o local:

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

Exemplos de código

Java

Para mais informações, consulte a documentação de referência da API Java da Document AI Warehouse.

Para autenticar no Document AI Warehouse, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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 mais informações, consulte a documentação de referência da API Node.js da Document AI Warehouse.

Para autenticar no Document AI Warehouse, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

/**
 * 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 mais informações, consulte a documentação de referência da API Python da Document AI Warehouse.

Para autenticar no Document AI Warehouse, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.


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óximas etapas

Se você usa o aplicativo da Web (prévia), acesse Administrar a interface da Document AI Warehouse para configurar UI da Document AI Warehouse.
Acesse Gerenciar controle de acesso para entender e configurar o controle de acesso.
Acesse Gerenciar esquemas de documentos para saber como fazer isso.
Acesse Pesquisar documentos para saber como fazer isso.

Início rápido Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Sobre o console do Google Cloud

Criar um projeto

Ativar faturamento

Provisionar e inicializar o serviço

Etapas de provisionamento

Configurar permissões no nível do projeto

Permissões necessárias

Projetos de ACL de documentos

Projetos de acesso universal

Papéis do IAM para projetos de acesso universal

Configurar o token de acesso (para chamar a API na linha de comando)

Usar o arquivo de chave da conta de serviço no seu ambiente

Linux ou macOS

Windows

Instale e inicialize a Google Cloud CLI (opcional)

Gerar o token de acesso

Testar a chamada da API Document AI Warehouse

Exemplos de código

Java

Node.js

Python

Próximas etapas

Início rápido