Ler e processar conteúdo do Google Docs no Jitterbit Studio

Introdução

O conector do Google Docs recupera documentos do Google Docs como dados JSON estruturados. O campo content retornado por uma atividade Get Docs contém o corpo completo do documento e pode ser passado diretamente a um LLM como string (veja Processar documentos com IA). Quando você precisa de acesso mais granular, a estrutura aninhada do documento pode ser percorrida usando GetJSONString para extrair elementos específicos: parágrafos individuais, nomes de contatos mencionados com @ e endereços de email, ou outros objetos embutidos.

Este guia abrange três padrões:

• Percorrer a estrutura de elementos aninhados do documento com GetJSONString e caminhos indexados para montar texto de parágrafos.
• Ler elementos person para extrair o nome e endereço de email de contatos mencionados com @.
• Extrair um ID do Google Docs de um corpo de mensagem do Gmail quando o link do documento chega como parte de uma notificação de email.

Este guia se baseia em Processar documentos com IA, que aborda a configuração básica de conexão do Google Docs e o mapeamento direto de Source.content. Para pré-requisitos de conexão do Google Docs, veja Pré-requisitos do Google Docs.

Padrão de design

O processamento do conteúdo do documento usa duas etapas vinculadas em uma única operação:

Uma transformação de solicitação fornece o ID do documento à atividade Get Docs. Uma segunda transformação captura o campo de resposta content como uma variável global. A etapa de script percorre a estrutura JSON aninhada para extrair texto de parágrafos e detalhes de contatos mencionados com @, produzindo variáveis que operações posteriores podem usar diretamente. A Parte 5 aborda como passar essas variáveis para uma operação posterior.

Quando o ID do documento não é conhecido com antecedência (por exemplo, quando chega dentro de uma notificação do Gmail), uma etapa de script anterior decodifica o corpo do email e extrai o ID antes da transformação ser executada. A Parte 4 aborda este caso.

Parte 1: Configurar a conexão do Google Docs

Configure uma conexão do Google Docs conforme descrito em Pré-requisitos do Google Docs e Conexão do Google Docs.

Após criar a conexão, crie uma variável de projeto para armazenar o ID do documento:

1. No Studio, abra o menu de ações do projeto e selecione Variáveis de Projeto.
2. Crie uma variável de projeto chamada google_docs_document_id. Defina seu valor padrão como o ID do documento que você deseja buscar (visível na URL do Google Docs: https://docs.google.com/document/d/<document-id>/edit), ou deixe o valor vazio se o ID será definido em tempo de execução conforme descrito na Parte 4.

Faça referência a esta variável em scripts e transformações usando o prefixo $ como $google_docs_document_id.

Parte 2: Buscar o documento e capturar o conteúdo

Criar a operação Buscar Documento

1. No Studio, crie uma nova operação. Nomeie-a como Fetch Document ou um nome similar.

2. Na paleta de componentes de design, expanda o endpoint do Google Docs. Arraste o tipo de atividade Get Docs para a tela de design para criar uma instância de atividade.

3. Clique duas vezes na atividade para abrir sua configuração.

4. Nome: Digite um nome para a atividade, por exemplo Get Document Content.

5. Clique em Próximo para revisar os esquemas de dados e então clique em Concluído.

Mapear o ID do documento

Adicione uma transformação de solicitação antes da atividade Get Docs para fornecer o ID do documento. Mapeie o campo de solicitação docid para a variável de projeto google_docs_document_id:

<trans>
$google_docs_document_id
</trans>

Capturar o conteúdo do documento

Após a atividade Get Docs, adicione uma transformação para capturar o campo de resposta content como uma variável global. Adicione este nó de script não mapeado (não atribuído a nenhum campo de destino) para que seja executado como um efeito colateral durante a transformação:

<trans>
If(Source.errormsg != "",
    RaiseError("Google Docs error: " + Source.errormsg)
);
$docContent = Source.content;
</trans>

O campo content contém a representação JSON de document.body.content: um array de elementos estruturais como parágrafos, quebras de seção e tabelas. Este valor agora está acessível como docContent para qualquer etapa de script subsequente na mesma operação ou operação encadeada.

Adicionar a etapa de script de análise

Após a transformação na tela de design, adicione uma etapa de script à operação. Você adicionará a lógica de percurso a esta etapa em Parte 3.

Parte 3: Percorrer a estrutura do documento

A variável docContent contém um array JSON de elementos estruturais. Cada elemento representa uma unidade de nível de bloco no documento. O caminho para alcançar o conteúdo de texto dentro de um parágrafo é:

/[i]/paragraph/elements/[j]/textRun/content

Onde i é o índice no array de conteúdo de nível superior e j é o índice no array de elementos de um parágrafo. Nem todo item de conteúdo contém um nó paragraph (quebras de seção e tabelas não contêm), e nem todo elemento de parágrafo contém um nó textRun (pessoas @mencionadas usam um nó person em vez disso). GetJSONString retorna uma string vazia quando um caminho não existe, portanto ambos os loops While terminam naturalmente quando um índice está fora dos limites.

Extrair texto do parágrafo

Adicione o seguinte script à etapa de script criada em Parte 2:

<trans>
i = 0;
$fullText = "";
$element = GetJSONString($docContent, "/[" + i + "]");
While($element != "" && $element != "null",
    j = 0;
    $textPart = GetJSONString($docContent, "/[" + i + "]/paragraph/elements/[" + j + "]/textRun/content");
    While($textPart != "" && $textPart != "null",
        $fullText += TrimChars($textPart, "\"");
        j++;
        $textPart = GetJSONString($docContent, "/[" + i + "]/paragraph/elements/[" + j + "]/textRun/content");
    );
    i++;
    $element = GetJSONString($docContent, "/[" + i + "]");
);
</trans>

TrimChars remove os caracteres de aspas duplas envolventes que GetJSONString inclui em sua saída para valores de string. Após a conclusão do script, fullText contém o texto completo do documento com quebras de linha de parágrafo preservadas. Passe fullText como corpo do prompt para uma operação LLM downstream. Para configuração do LLM, consulte Usar OpenAI para processar dados em uma operação Studio ou Usar Azure OpenAI em uma operação Studio.

Extrair contatos @mencionados

Quando um Google Doc contém pessoas @mencionadas, cada menção aparece como um elemento person dentro do array de elementos de um parágrafo. O nó filho personProperties contém o nome de exibição e endereço de email do contato.

Anexe o seguinte à etapa de script, após o loop de texto de parágrafo:

<trans>
i = 0;
$contacts = "";
$element = GetJSONString($docContent, "/[" + i + "]");
While($element != "" && $element != "null",
    j = 0;
    $personNode = GetJSONString($docContent, "/[" + i + "]/paragraph/elements/[" + j + "]/person");
    While($personNode != "" && $personNode != "null",
        $personName = TrimChars(
            GetJSONString($docContent, "/[" + i + "]/paragraph/elements/[" + j + "]/person/personProperties/name"),
            "\"");
        $personEmail = TrimChars(
            GetJSONString($docContent, "/[" + i + "]/paragraph/elements/[" + j + "]/person/personProperties/email"),
            "\"");
        If($personName != "" && $personName != "null",
            $contacts += $personName + " <" + $personEmail + ">\n";
        );
        j++;
        $personNode = GetJSONString($docContent, "/[" + i + "]/paragraph/elements/[" + j + "]/person");
    );
    i++;
    $element = GetJSONString($docContent, "/[" + i + "]");
);
</trans>

Após a conclusão do script, contacts contém uma lista separada por quebras de linha com nomes de exibição e endereços de email de todas as pessoas @mencionadas no documento.

Parte 4: Extrair um ID de Google Doc do corpo de um email do Gmail

Quando uma operação Studio recebe uma notificação de email que contém um link para um Google Doc, o ID do documento pode ser extraído do corpo do email antes que a operação Fetch Document seja executada.

As respostas da API do Gmail codificam corpos de email usando codificação base64url, que substitui - por + e _ por / em comparação com a base64 padrão. A decodificação requer reverter essas substituições antes de chamar Base64Decode.

Adicione o seguinte script em uma etapa de script que é executada antes da operação Fetch Document:

<trans>
// $emailBodyBase64 holds the base64url-encoded email body from the Gmail API response

// Normalize base64url encoding to standard base64
$emailBodyBase64Clean = Replace($emailBodyBase64, "-", "+");
$emailBodyBase64Clean = Replace($emailBodyBase64Clean, "_", "/");

// Decode binary content to a plain text string
$emailBodyText = HexToString(BinaryToHex(Base64Decode($emailBodyBase64Clean)));

// Locate the Google Docs URL pattern and extract the 44-character document ID
$urlPrefix = "docs.google.com/document/d/";
$startPos = Index($emailBodyText, $urlPrefix) + Length($urlPrefix);
$google_docs_document_id = Mid($emailBodyText, $startPos, 44);
</trans>

Replace corrige a substituição de caracteres base64url. A cadeia Base64Decode → BinaryToHex → HexToString converte o conteúdo decodificado binariamente em uma string legível. Index encontra a posição do caractere do prefixo da URL, Length avança para além dele, e Mid extrai o ID do documento nessa posição.

O corpo do email decodificado é tipicamente HTML. O padrão docs.google.com/document/d/ aparece em atributos href de tags de âncora, e os IDs de documentos do Google Docs têm consistentemente 44 caracteres de comprimento. Após a conclusão deste script, google_docs_document_id é definido e a operação Fetch Document pode ser executada.

Parte 5: Usar o conteúdo extraído a jusante

Após a execução da etapa do script de análise, fullText e contacts mantêm o texto do documento extraído e os contatos mencionados com @. Encadeie uma operação a jusante no sucesso da operação Fetch Document para usar esses valores:

• Envie fullText para um LLM para sumarização ou análise mapeando-o para o corpo do prompt de uma atividade Prompt do OpenAI ou Azure OpenAI. Consulte Usar OpenAI para processar dados em uma operação do Studio, Usar Azure OpenAI em uma operação do Studio ou Processar documentos com IA.
• Publique fullText ou contacts em um canal de notificação mapeando o valor para uma atividade Slack Post Message ou Microsoft Teams. Consulte Enviar uma notificação do Slack de uma operação do Studio.
• Registre os valores em um registro ou arquivo para armazenamento.

Como fullText e contacts são variáveis globais, elas estão disponíveis para qualquer operação encadeada após a operação Fetch Document sem mapeamento adicional.

Verificar a integração

1. Implante e execute a operação Fetch Document.

2. Nos logs de operação, confirme que a atividade Get Document Content foi concluída com sucesso.

3. Confirme que fullText contém o texto do documento esperado. Adicione WriteToOperationLog($fullText) temporariamente à etapa do script para inspecionar o valor no log de operação.

4. Se o documento contiver @-menções, confirme que contacts não está vazio e contém os nomes e endereços de email esperados.

5. Se a atividade Get Docs retornar um campo content vazio ou nulo:

   • Confirme que google_docs_document_id está definido como o ID de documento correto de 44 caracteres.
   • Confirme que a conta de serviço configurada na conexão do Google Docs tem acesso de leitura ao documento. Se necessário, compartilhe o documento com o endereço client_email da conta de serviço diretamente no Google Docs.

6. Se fullText contiver lacunas inesperadas, observe que elementos estruturais como quebras de seção e células de tabela produzem itens de conteúdo sem um nó paragraph. Esses são ignorados pelo loop While externo porque GetJSONString retorna uma string vazia para o caminho ausente.