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.

No console do Google Cloud , na página do seletor de projetos, selecione ou crie um projeto do Google Cloud .

Funções necessárias para selecionar ou criar um projeto

  • Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
  • Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

Acessar o seletor de projetos

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.

Verifique se o faturamento está ativado para o projeto do Google Cloud .

Provisionar e inicializar o serviço

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

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

Etapas de provisionamento

  1. 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.

  2. 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.

  3. 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.

    1. 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.

      • 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 faz a transmissão das 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 para envolvidos no projeto)

    2. 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.

  4. 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).

  5. 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.

  6. 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 para envolvidos no 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 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.

  7. 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 para envolvidos no projeto e do IAM. Consulte permissões necessárias para mais detalhes.

Configurar permissões para envolvidos no 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 para envolvidos no 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:

  1. Clique em Adicionar usuário.

  2. Insira o e-mail do administrador e escolha Administrador de documentos como o nível de acesso. Clique em Salvar.

  3. Para outros usuários, você pode adicioná-los 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, independentemente 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 dos documentos.

    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 permissões de documentos.

    4. Criador de documentos: uma função com permissões apenas para fazer upload de documentos. Os criadores de documentos têm permissões completas para os documentos que enviam, mas não têm outras permissões para nenhum outro documento, a menos que recebam permissões explícitas para eles.

  4. 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.

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 para envolvidos no 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

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 Google Cloud CLI 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