GSP927

Visão geral

A API Document AI é uma solução de compreensão de documentos que usa dados não estruturados, como documentos e e-mails, e facilita a compreensão, a análise e efetivação dos dados.

Neste laboratório, você vai criar um pipeline de processamento de documentos para analisar automaticamente os documentos enviados ao Cloud Storage. O pipeline usa uma função do Cloud Run com um processador de formulários da Document AI para extrair dados e armazená-los no BigQuery. Se o formulário incluir campos de endereço, os dados de endereço serão enviados para um tópico do Pub/Sub. Isso aciona uma segunda função do Cloud Run, que usa a API Geocoding para adicionar coordenadas e grava os resultados no BigQuery.

Esse pipeline simples usa um processador de formulários geral para detectar dados básicos de formulários, como campos de endereço rotulados. Para documentos mais complexos, a Document AI oferece analisadores especializados (além do escopo deste laboratório) que extraem informações detalhadas mesmo sem rótulos evidentes. Por exemplo, o analisador de faturas pode identificar detalhes de endereço e fornecedor em uma fatura não rotulada ao entender layouts comuns de faturas.

A arquitetura geral que você vai criar é parecida com esta:

1. Fazer upload de formulários com dados de endereço para o Cloud Storage.
2. O upload aciona uma chamada de função do Cloud Run para processar os formulários.
3. Document AI chamada da função do Cloud Run.
4. Dados JSON da Document AI salvos de volta no Cloud Storage.
5. Dados do formulário gravados no BigQuery pela função do Cloud Run.
6. A função do Cloud Run envia endereços para um tópico do Pub/Sub.
7. A mensagem do Pub/Sub aciona a função do Cloud Run para o processamento de geocodificação.
8. API Geocoding chamada da função do Cloud Run.
9. Dados de geocodificação gravados no BigQuery pela função do Cloud Run.

Esta arquitetura de exemplo usa funções do Cloud Run para implementar um pipeline simples, mas as funções do Cloud Run não são recomendadas para ambientes de produção, porque as chamadas da API Document AI podem exceder os tempos limite aceitos pelas funções do Cloud Run. O Cloud Tasks é recomendado para uma solução sem servidor mais robusta.

O que você vai aprender

Neste laboratório, você vai aprender a:

• Ative a API Document AI.
• Implantar funções do Cloud Run que usam as APIs da Document AI, BigQuery, Cloud Storage e Pub/Sub.

Você vai configurar uma função do Cloud Run para:

• Acionar quando documentos são enviados para o Cloud Storage.
• Usar a biblioteca de cliente da Document AI para Python.
• Acionar quando uma mensagem do Pub/Sub é criada.

Configuração e requisitos

Antes de clicar no botão Começar o Laboratório

Leia estas instruções. Os laboratórios são cronometrados e não podem ser pausados. O timer é ativado quando você clica em Iniciar laboratório e mostra por quanto tempo os recursos do Google Cloud vão ficar disponíveis.

Este laboratório prático permite que você realize as atividades em um ambiente real de nuvem, e não em uma simulação ou demonstração. Você vai receber novas credenciais temporárias para fazer login e acessar o Google Cloud durante o laboratório.

Confira os requisitos para concluir o laboratório:

• Acesso a um navegador de Internet padrão (recomendamos o Chrome).

Observação: para executar este laboratório, use o modo de navegação anônima (recomendado) ou uma janela anônima do navegador. Isso evita conflitos entre sua conta pessoal e de estudante, o que poderia causar cobranças extras na sua conta pessoal.

• Tempo para concluir o laboratório: não se esqueça que, depois de começar, não será possível pausar o laboratório.

Observação: use apenas a conta de estudante neste laboratório. Se usar outra conta do Google Cloud, você poderá receber cobranças nela.

Ativar o Cloud Shell

O Cloud Shell é uma máquina virtual com várias ferramentas de desenvolvimento. Ele tem um diretório principal permanente de 5 GB e é executado no Google Cloud. O Cloud Shell oferece acesso de linha de comando aos recursos do Google Cloud.

1. Clique em Ativar o Cloud Shell na parte de cima do console do Google Cloud.

2. Clique nas seguintes janelas:

   • Continue na janela de informações do Cloud Shell.
   • Autorize o Cloud Shell a usar suas credenciais para fazer chamadas de APIs do Google Cloud.

Depois de se conectar, você verá que sua conta já está autenticada e que o projeto está configurado com seu Project_ID, . A saída contém uma linha que declara o projeto PROJECT_ID para esta sessão:

Your Cloud Platform project in this session is set to {{{project_0.project_id | "PROJECT_ID"}}}

A gcloud é a ferramenta de linha de comando do Google Cloud. Ela vem pré-instalada no Cloud Shell e aceita preenchimento com tabulação.

3. (Opcional) É possível listar o nome da conta ativa usando este comando:

gcloud auth list

4. Clique em Autorizar.

Saída:

ACTIVE: * ACCOUNT: {{{user_0.username | "ACCOUNT"}}} To set the active account, run: $ gcloud config set account `ACCOUNT`

5. (Opcional) É possível listar o ID do projeto usando este comando:

gcloud config list project

Saída:

[core] project = {{{project_0.project_id | "PROJECT_ID"}}} Observação: consulte a documentação completa da gcloud no Google Cloud no guia de visão geral da gcloud CLI.

Tarefa 1: Ativar APIs e criar uma chave de API

Você precisa ativar as APIs da Document AI, funções do Cloud Run, Cloud Build e Geocoding para este laboratório e criar a chave de API exigida pela função de geocodificação do Cloud Run.

1. Clique em Ativar o Cloud Shell na parte de cima do console do Google Cloud.

2. No Cloud Shell, insira os comandos a seguir para ativar as APIs exigidas pelo laboratório:

gcloud services enable documentai.googleapis.com gcloud services enable cloudfunctions.googleapis.com gcloud services enable cloudbuild.googleapis.com gcloud services enable geocoding-backend.googleapis.com

3. No Menu de navegação () do Console, clique em APIs e serviços > Credenciais.

4. Clique em Criar credenciais e selecione a chave de API no menu suspenso.

A nova chave será exibida na caixa de diálogo Chave de API criada. Uma chave de API é uma string longa que contém letras maiúsculas e minúsculas, números e traços. Por exemplo, a4db08b757294ea94c08f2df493465a1.

5. Clique nos três pontos em Ações e depois em Editar chave de API na caixa de diálogo.

6. Selecione Restringir chave na seção Restrições da API para adicionar restrições de API à sua nova chave.

7. Clique no menu suspenso Selecionar APIs e digite API Geocoding na caixa de filtro.

8. Selecione API Geocoding e clique em OK.

9. Clique no botão Salvar.

Observação : se você não encontrar a API Geocoding na lista suspensa Restringir chave, atualize a página para atualizar a lista de APIs disponíveis. Verifique se todas as APIs necessárias foram ativadas.

Tarefa 2: Baixe o código-fonte do laboratório

Nesta tarefa, você vai copiar os arquivos de origem para o Cloud Shell. Esses arquivos incluem o código-fonte das funções do Cloud Run e os esquemas das tabelas do BigQuery que você vai criar no laboratório.

1. No Cloud Shell, insira o comando a seguir para fazer o download do código-fonte deste laboratório:

mkdir ./documentai-pipeline-demo gcloud storage cp -r \ gs://spls/gsp927/documentai-pipeline-demo/* \ ~/documentai-pipeline-demo/

Tarefa 3: Criar um processador de formulários

Crie uma instância do processador de formulários genérico para usar na Plataforma Document AI usando o analisador especializado Form Parser da Document AI. O processador de formulários geral vai processar qualquer tipo de documento e extrair todo o conteúdo de texto que puder identificar no documento. Ele não se limita a textos impressos, mas também gerencia textos manuscritos e em qualquer orientação, aceita vários idiomas e entende como os elementos de dados do formulário se relacionam entre si, tornando possível extrair pares de chave-valor dos campos do formulário com rótulos de texto.

1. No console do Google Cloud, na barra de pesquisa, digite Document AI e clique no resultado da página do produto.

2. Clique em Explorar os processadores e em Form Parser para criar um novo processador.

3. Especifique o nome do processador como form-parser e selecione a região US (Estados Unidos) na lista.

4. Clique em Criar para que o processador seja criado.

Você vai configurar uma função do Cloud Run mais tarde neste laboratório com o ID e a localização desse processador para que a função do Cloud Run use esse processador específico para processar faturas de amostra.

Tarefa 4: Criar buckets do Cloud Storage e um conjunto de dados do BigQuery

Nesta seção, você vai preparar seu ambiente criando os recursos do Google Cloud necessários para o pipeline de processamento de documentos.

Criar buckets de entrada, saída e arquivo do Cloud Storage

Criar buckets de entrada, saída e arquivo do Cloud Storage para seu pipeline de processamento de documentos.

1. No Cloud Shell, insira o comando a seguir para criar os buckets do Cloud Storage para o laboratório:

export PROJECT_ID=$(gcloud config get-value core/project) export BUCKET_LOCATION="{{{my_primary_project.default_region|REGION}}}" gsutil mb -c standard -l ${BUCKET_LOCATION} -b on \ gs://${PROJECT_ID}-input-invoices gsutil mb -c standard -l ${BUCKET_LOCATION} -b on \ gs://${PROJECT_ID}-output-invoices gsutil mb -c standard -l ${BUCKET_LOCATION} -b on \ gs://${PROJECT_ID}-archived-invoices

Criar um conjunto de dados e tabelas do BigQuery

Criar um conjunto de dados do BigQuery e as três tabelas de saída necessárias para o pipeline de processamento de dados.

1. No Cloud Shell, insira o comando a seguir para criar as tabelas do BigQuery para o laboratório:

bq --location="US" mk -d \ --description "Form Parser Results" \ ${PROJECT_ID}:invoice_parser_results cd ~/documentai-pipeline-demo/scripts/table-schema/ bq mk --table \ invoice_parser_results.doc_ai_extracted_entities \ doc_ai_extracted_entities.json bq mk --table \ invoice_parser_results.geocode_details \ geocode_details.json

Você pode acessar o BigQuery no console do Cloud e inspecionar os esquemas das tabelas no conjunto de dados invoice_parser_results usando o espaço de trabalho SQL do BigQuery.

Criar um tópico do Pub/Sub

Inicializar o tópico do Pub/Sub usado para acionar as operações de aprimoramento de dados da API Geocoding no pipeline de processamento.

1. No Cloud Shell, insira o comando a seguir para criar os tópicos do Pub/Sub para o laboratório:

export GEO_CODE_REQUEST_PUBSUB_TOPIC=geocode_request gcloud pubsub topics \ create ${GEO_CODE_REQUEST_PUBSUB_TOPIC} Verifique se o conjunto de dados do BigQuery, os buckets do Cloud Storage e o tópico do Pub/Sub foram criados.

Tarefa 5: Criar funções do Cloud Run

Criar as duas funções do Cloud Run que o pipeline de processamento de dados usa para processar as faturas enviadas ao Cloud Storage. Essas funções usam a API Document AI para extrair dados de formulários dos documentos brutos e, em seguida, usam a API GeoCode para recuperar dados de geolocalização sobre as informações de endereço extraídas dos documentos.

Você pode examinar o código-fonte das duas funções do Cloud Run usando o Editor de código ou qualquer outro editor de sua escolha. As funções do Cloud Run são armazenadas nas seguintes pastas no Cloud Shell:

• Processar faturas - scripts/cloud-functions/process-invoices
• Geocodificar endereços - scripts/cloud-functions/geocode-addresses

A função principal do Cloud Run, process-invoices, é acionada quando os arquivos são enviados para o bucket de armazenamento de arquivos de entrada que você criou anteriormente.

A pasta de função scripts/cloud-functions/process-invoices contém os dois arquivos usados para criar a função do Cloud Run process-invoices.

O arquivo requirements.txt especifica as bibliotecas Python necessárias para a função. Isso inclui a biblioteca de cliente da Document AI e as outras bibliotecas do Google Cloud necessárias para o código Python ler os arquivos do Cloud Storage, salvar dados no BigQuery e gravar mensagens no Pub/Sub que vão acionar as funções restantes no pipeline da solução.

O arquivo Python main.py contém o código da função do Cloud Run que cria os clientes de API Document AI, BigQuery e Pub/Sub e as seguintes funções internas para processar os documentos:

• write_to_bq - grava o objeto de dicionário na tabela do BigQuery. Observação: você precisa garantir que o esquema seja válido antes de chamar essa função.
• get_text - mapeia âncoras de texto de nome e valor do formulário para o texto digitalizado no documento. Isso permite que a função identifique elementos específicos do formulário, como o nome e o endereço do fornecedor, e extraia o valor relevante. Um processador especializado da Document AI fornece essas informações contextuais diretamente na propriedade de entidades.
• process_invoice - usa a API do cliente assíncrono da Document-AI para ler e processar arquivos do Cloud Storage da seguinte forma:
  • Cria uma solicitação assíncrona para processar os arquivos que acionaram a chamada de função do Cloud Run.
  • Processa dados de formulários para extrair campos de faturas, armazenando apenas campos específicos em um dicionário que faz parte do esquema predefinido.
  • Publica mensagens do Pub/Sub para acionar a função Geocoding do Cloud Run usando dados de formulário de endereço extraídos do documento.
  • Grava dados de formulário em uma tabela do BigQuery.
  • Exclui arquivos intermediários (de saída) da chamada assíncrona da API Document AI.
  • Copia os arquivos de entrada para o bucket de arquivo.
  • Exclui arquivos de entrada processados.

A função do Cloud Run process_invoices só processa dados de formulários detectados com os seguintes nomes de campos:

• input_file_name
• address
• supplier
• invoice_number
• purchase_order
• date
• due_date
• subtotal
• tax
• total

A outra função do Cloud Run, geocode-addresses, é acionada quando uma nova mensagem chega a um tópico do Pub/Sub e extrai os dados de parâmetro da mensagem do Pub/Sub.

Criar a função do Cloud Run para processar documentos enviados ao Cloud Storage

Criar uma função do Cloud Run que usa um processador de formulários da Document AI para analisar documentos de formulários que foram enviados para um bucket do Cloud Storage.

1. Execute o comando para receber o endereço de e-mail do agente de serviço do Cloud Storage do projeto:

gcloud storage service-agent --project=$PROJECT_ID

2. Execute o comando abaixo para permitir as permissões necessárias à conta de serviço do Cloud Storage:

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)") gcloud iam service-accounts create "service-$PROJECT_NUMBER" \ --display-name "Cloud Storage Service Account" || true gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:service-$PROJECT_NUMBER@gs-project-accounts.iam.gserviceaccount.com" \ --role="roles/pubsub.publisher" gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:service-$PROJECT_NUMBER@gs-project-accounts.iam.gserviceaccount.com" \ --role="roles/iam.serviceAccountTokenCreator" Observação: se a conta de serviço do Cloud Storage existir, ignore o erro.

3. Criar a função do Cloud Run Invoice Processor:

cd ~/documentai-pipeline-demo/scripts export CLOUD_FUNCTION_LOCATION="{{{my_primary_project.default_region|REGION}}}" gcloud functions deploy process-invoices \ --no-gen2 \ --region=${CLOUD_FUNCTION_LOCATION} \ --entry-point=process_invoice \ --runtime=python39 \ --source=cloud-functions/process-invoices \ --timeout=400 \ --env-vars-file=cloud-functions/process-invoices/.env.yaml \ --trigger-resource=gs://${PROJECT_ID}-input-invoices \ --trigger-event=google.storage.object.finalize Observação: se o comando falhar com um erro de permissão, espere um minuto e tente de novo.

Criar a função do Cloud Run para pesquisar dados de geocodificação de um endereço

Criar a função do Cloud Run que aceita dados de endereço de uma mensagem do Pub/Sub e usa a API Geocoding para localizar o endereço com precisão.

1. Crie a função Geocoding do Cloud Run:

cd ~/documentai-pipeline-demo/scripts gcloud functions deploy geocode-addresses \ --no-gen2 \ --region=${CLOUD_FUNCTION_LOCATION} \ --entry-point=process_address \ --runtime=python39 \ --source=cloud-functions/geocode-addresses \ --timeout=60 \ --env-vars-file=cloud-functions/geocode-addresses/.env.yaml \ --trigger-topic=${GEO_CODE_REQUEST_PUBSUB_TOPIC}

Tarefa 6: Editar variáveis de ambiente para as funções do Cloud Run

Nesta tarefa, você vai finalizar a configuração das funções do Cloud Run editando as variáveis de ambiente de cada função para refletir os parâmetros específicos do laboratório usando o console do Cloud.

Edite as variáveis de ambiente da função process-invoices do Cloud Run

Defina as variáveis de ambiente da função do Cloud Run para a função process-invoices.

1. No console do Cloud, na barra de pesquisa, digite Cloud Run functions e clique no resultado da página do produto.

Ele vai redirecionar para o console do Cloud Run. Clique em Acessar funções do Cloud Run 1ª geração para ver as funções implantadas process-invoices e geocode-addresses.

Observação: se o link Acessar funções do Cloud Run 1ª geração não aparecer, atualize o console do Cloud Run.

2. Clique na função do Cloud Run process-invoices para abrir a página de gerenciamento.
3. Clique em Editar.
4. Clique em Ambiente de execução, build, conexões e configurações de segurança para expandir essa seção.
5. Em Variáveis de ambiente de execução, adicione a variável GCP_PROJECT e o valor correspondente ao seu ID do projeto.
6. Em Variáveis de ambiente de execução, atualize o valor de PROCESSOR_ID para corresponder ao ID do processador de faturas que você criou anteriormente.
7. Em Variáveis de ambiente de execução, atualize o valor de PARSER_LOCATION para corresponder à região do processador de faturas que você criou anteriormente. Será us ou eu. Esse parâmetro precisa estar em letras minúsculas.
8. Clique em Próxima, selecione .env.yaml e atualize os valores de PROCESSOR_ID, PARSER_LOCATION e GCP_PROJECT novamente para o processador de faturas.

9. Clique em Implantar.

Implantar a função do Cloud Run "Process Invoices"

Edite as variáveis de ambiente da função geocode-addresses do Cloud Run

Defina as variáveis de ambiente da função do Cloud Run para a função de aprimoramento de dados GeoCode.

1. Clique na função do Cloud Run geocode-addresses para abrir a página de gerenciamento.
2. Clique em Editar.
3. Clique em Ambiente de execução, build, conexões e configurações de segurança para expandir essa seção.
4. Em Variáveis de ambiente de execução, atualize o valor de API_key para corresponder ao valor da chave de API criada na Tarefa 1.
5. Clique em Próximo, selecione .env.yaml e atualize o valor de API_key para corresponder ao valor de API Key definido na etapa anterior.
6. Clique em Implantar.

Implantar a função do Cloud Run "Geocode Addresses"

Tarefa 7: Testar e validar a solução de ponta a ponta

Fazer upload dos dados de teste para o Cloud Storage e monitorar o progresso do pipeline à medida que os documentos são processados e os dados extraídos são aprimorados.

1. No Cloud Shell, insira o comando a seguir para fazer upload de formulários de amostra no bucket do Cloud Storage que vai acionar a função do Cloud Run process-invoices:

export PROJECT_ID=$(gcloud config get-value core/project) gsutil cp gs://spls/gsp927/documentai-pipeline-demo/sample-files/* gs://${PROJECT_ID}-input-invoices/

2. No console do Cloud, na barra de pesquisa, digite Cloud Run functions e clique no resultado da página do produto.
3. Clique na função do Cloud Run process-invoices para abrir a página de gerenciamento.
4. Clique em Registros.

Você vai ver eventos relacionados à criação da função e às atualizações feitas para configurar as variáveis de ambiente, seguidos de eventos que mostram detalhes sobre o arquivo que está sendo processado e os dados detectados pela Document AI.

Acompanhe os eventos até ver um evento final indicando que a execução da função terminou com um LoadJob. Se forem relatados erros, verifique se os parâmetros definidos no arquivo .env.yaml na seção anterior estão corretos. Em especial, verifique se o ID do processador, o local e o ID do projeto são válidos. A lista de eventos não é atualizada automaticamente.

Ao final do processamento, suas tabelas do BigQuery serão preenchidas com as entidades extraídas da Document AI, bem como dados enriquecidos fornecidos pela API Geocoding, caso o processador da Document AI tenha detectado dados de endereço no documento enviado.

Abrir o console do BigQuery

1. No Console do Google Cloud, selecione o menu de navegação > BigQuery:

Você verá a caixa de mensagem Olá! Este é o BigQuery no Console do Cloud. Ela tem um link para o guia de início rápido e as notas de lançamento.

2. Clique em OK.

O console do BigQuery vai abrir.

3. Expanda o ID do projeto no Explorador.

4. Expanda invoice_parser_results.

5. Selecione doc_ai_extracted_entities e clique em Visualizar.

Você pode ver as informações do formulário extraídas das faturas pelo processador de faturas e observar que as informações de endereço e o nome do fornecedor foram detectados.

6. Selecione geocode_details e clique em Visualizar.

É possível conferir o endereço formatado, a latitude e a longitude de cada fatura processada que continha dados de endereço que a Document AI conseguiu extrair.

Verificar se o pipeline completo processou os dados do formulário e do endereço.

Parabéns!

Você usou corretamente a API Document AI e outros serviços do Google Cloud para criar um pipeline de processamento de faturas de ponta a ponta. Neste laboratório, você ativou a API Document AI, implantou funções do Cloud Run que usam as APIs Document AI, BigQuery, Cloud Storage e Pub/Sub e configurou uma função do Cloud Run para ser acionada quando documentos são enviados para o Cloud Storage. Você também configurou uma função do Cloud Run para usar a biblioteca de cliente da Document AI para Python e para ser acionada quando uma mensagem do Pub/Sub fosse criada.

Próximas etapas / Saiba mais

• Para saber mais sobre essa forma de autenticação, consulte o guia.

Treinamento e certificação do Google Cloud

Esses treinamentos ajudam você a aproveitar as tecnologias do Google Cloud ao máximo. Nossas aulas incluem habilidades técnicas e práticas recomendadas para ajudar você a alcançar rapidamente o nível esperado e continuar sua jornada de aprendizado. Oferecemos treinamentos que vão do nível básico ao avançado, com opções de aulas virtuais, sob demanda e por meio de transmissões ao vivo para que você possa encaixá-las na correria do seu dia a dia. As certificações validam sua experiência e comprovam suas habilidades com as tecnologias do Google Cloud.

Manual atualizado em 26 de agosto de 2025

Laboratório testado em 29 de julho de 2025

Copyright 2025 Google LLC. Todos os direitos reservados. Google e o logotipo do Google são marcas registradas da Google LLC. Todos os outros nomes de produtos e empresas podem ser marcas registradas das respectivas empresas a que estão associados.