Guia de início rápido: configurar a API Document AI

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

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 do Google Cloud para configurar e gerenciar recursos da Document AI.

Criar um projeto

Para usar os serviços fornecidos pelo Google Cloud, crie um projeto, que organiza todos os seus recursos do Google Cloud e 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
• Processadores da Document AI

É 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 a API

É necessário ativar a API Document AI no projeto. Para mais informações sobre como ativar APIs, consulte a documentação do Service Usage.

Ativar a API Document AI.

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

Ativar a API

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 .

Acessar os papéis necessários

Para receber as permissões necessárias para dar a um principal acesso a arquivos no Cloud Storage, peça ao administrador para conceder a você o papel do IAM de Administrador do Storage (roles/storage.admin) no bucket. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Locais

A Document AI oferece a você algum controle sobre onde os recursos do seu projeto são armazenados e tratados. Em especial, ao criar um processador, você precisa escolher um local para armazenar e processar seus dados. Por padrão, a Document AI armazena e processa recursos em um local nos EUA. Se você escolher a União Europeia como local, seus dados e processos serão armazenados somente na União Europeia.

Observação: você e seus usuários podem acessar os dados de qualquer local.

Como definir o local usando a API

É necessário especificar a localização do seu processador sempre que você enviar uma solicitação de processamento usando a API. Por exemplo, se o processador estiver configurado para armazenar e processar seus dados na União Europeia, use o URI eu-documentai.googleapis.com da seguinte forma:

Process	https://eu-documentai.googleapis.com/v1/projects/$PROJECT_ID/locations/eu/processors/$PROCESSOR_ID:process https://eu-documentai.googleapis.com/v1beta3/projects/$PROJECT_ID/locations/eu/processors/$PROCESSOR_ID:process
batchProcess	https://eu-documentai.googleapis.com/v1/projects/$PROJECT_ID/locations/eu/processors/$PROCESSOR_ID:batchProcess https://eu-documentai.googleapis.com/v1beta3/projects/$PROJECT_ID/locations/eu/processors/$PROCESSOR_ID:batchProcess

Instalar a biblioteca de cliente da API Document AI

Você tem três opções para chamar a API Document AI:

• Bibliotecas de cliente compatíveis com o Google (recomendado)
• REST
• gRPC

As bibliotecas de cliente estão disponíveis para vários idiomas conhecidos. Para informações sobre como instalar as bibliotecas de cliente, consulte Bibliotecas de cliente da API Document AI.

Instalar e inicializar a CLI do Google Cloud

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 CLI gcloud com sua identidade federada.

Configurar a autenticação

Qualquer aplicativo cliente que usa a API precisa ser autenticado e receber acesso aos recursos solicitados. A configuração da autenticação depende de você estar trabalhando em um ambiente de desenvolvimento local ou configurando um ambiente de produção. Para mais informações, consulte Configurar o Application Default Credentials.

Selecione as guias para definir como você quer acessar a API:

gcloud

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 CLI gcloud com sua identidade federada.

Bibliotecas de cliente

Para usar bibliotecas de cliente em um ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e configure o Application Default Credentials com suas credenciais de usuário.

1. Instale a CLI do Google Cloud.

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

3. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário:

   gcloud auth application-default login

   Não é necessário fazer isso se você estiver usando o Cloud Shell.

   Se um erro de autenticação for retornado e você estiver usando um provedor de identidade (IdP) externo, confirme se você fez login na CLI gcloud com sua identidade federada.

Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local na documentação de autenticação do Google Cloud .

REST

Para usar a API REST em um ambiente de desenvolvimento local, use as credenciais que você vai informar à CLI gcloud.

Instale a CLI do Google Cloud.

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

Saiba mais em Autenticar para usar REST na documentação de autenticação do Google Cloud .

Para informações sobre como configurar a autenticação em um ambiente de produção, consulte Configurar o Application Default Credentials para código executado em Google Cloud na documentação de autenticação do Google Cloud .

Sobre os papéis

Quando um principal autenticado tenta acessar um Google Cloud recurso, o IAM verifica se o principal tem as permissões necessárias. Você concede permissões aos principais atribuindo papéis nas políticas de permissão do IAM. Para mais informações sobre principais, papéis, recursos e políticas de permissão, consulte a visão geral do IAM.

Siga o princípio de privilégio mínimo ao conceder papéis em recursos doGoogle Cloud a principais. Não conceda a um principal mais permissões do que ele precisa para concluir a solicitação. Para mais informações sobre práticas recomendadas de controle de acesso, consulte Usar o IAM com segurança.

Para acessar recursos na Document AI, use um papel com as permissões específicas necessárias. Para mais informações, consulte Permissões da Document AI e Papéis da Document AI.

Configuração de acesso a arquivos entre projetos

Ao configurar um processador da Document AI em um projeto, talvez você queira que ele acesse arquivos de entrada armazenados em outro projeto da mesma organização que hospeda os processadores da Document AI.

Para permitir o acesso entre projetos, conceda o papel de Leitor de objetos do Storage (roles/storage.objectViewer) ao agente de serviço da Document AI, conforme mostrado na figura a seguir.

Exemplo

• Suponha que o projeto A hospede processadores da Document AI e, opcionalmente, um bucket em que a saída do processador é gravada.
• O projeto B é proprietário do bucket que contém arquivos de entrada para processadores da Document AI.

• Para tornar os arquivos do projeto B acessíveis ao projeto A, conceda o papel de leitor de objetos do Storage (roles/storage.objectViewer) para o bucket de entrada no projeto B ao agente de serviço da Document AI do projeto A.

  

Para mais informações sobre o IAM e o papel de leitor de objetos do Storage, consulte Papéis do IAM para o Cloud Storage.

Contas de serviço integradas

Um agente de serviço da Document AI segue esta convenção de nomenclatura:

service-{project number}@gcp-sa-prod-dai-core.iam.gserviceaccount.com

Exemplo: [e-mail]

Próximas etapas: casos de uso

Depois que a API Document AI é ativada, os processadores da Document AI podem ser criados e usados. O melhor tipo de processador depende do seu caso de uso.