Leia e analise o 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 para um LLM como uma string (veja Processar documentos com IA). Quando é necessário um 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 e-mail, ou outros objetos inline.

Este guia abrange três padrões:

• Percorrendo a estrutura de elementos aninhados do documento com GetJSONString e caminhos indexados para montar o texto dos parágrafos.
• Lendo elementos person para extrair o nome e o endereço de e-mail de contatos mencionados com @.
• Extraindo um ID do Google Doc do corpo de uma mensagem do Gmail quando o link do documento chega como parte de uma notificação por e-mail.

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

Padrão de design

A análise do conteúdo do documento utiliza dois passos interligados dentro de uma única operação:

Uma transformação de solicitação fornece o ID do documento para a atividade Get Docs. Uma segunda transformação captura o campo de resposta content como uma variável global. O passo de script percorre a estrutura JSON aninhada para extrair o texto dos parágrafos e os detalhes de contato mencionados com @, produzindo variáveis que operações a jusante podem usar diretamente. Parte 5 cobre a passagem dessas variáveis para uma operação a jusante.

Quando o ID do documento não é conhecido antecipadamente (por exemplo, quando chega dentro de uma notificação do Gmail), um passo de script anterior decodifica o corpo do e-mail e extrai o ID antes que a transformação seja executada. Parte 4 cobre esse 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 for definido em tempo de execução, conforme descrito na Parte 4.

Referencie 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 Buscar Documento ou um nome similar.

2. No painel de componentes de design, expanda o endpoint do Google Docs. Arraste o tipo de atividade Obter Docs para o canvas de design para criar uma instância de atividade.

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

4. Nome: Insira um nome para a atividade, por exemplo Obter Conteúdo do Documento.

5. Clique em Próximo para revisar os esquemas de dados e, em seguida, clique em Concluído.

Mapear o ID do documento

Adicione uma transformação de solicitação antes da atividade Obter 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 Obter 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 ele 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 travessia a esta etapa na Parte 3.

Parte 3: Navegar pela estrutura do documento

A variável docContent contém um array JSON de elementos estruturais. Cada elemento representa uma unidade de bloco no documento. O caminho para acessar 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 com @ usam um nó person em vez disso). GetJSONString retorna uma string vazia quando um caminho não existe, então 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 na 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 ao redor 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 o corpo do prompt para uma operação LLM a jusante. Para configuração do LLM, consulte Usar OpenAI para processar dados em uma operação de Estúdio ou Usar Azure OpenAI em uma operação de Estúdio.

Extrair contatos mencionados com @

Quando um Google Doc contém pessoas mencionadas com @, 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 exibido e o endereço de e-mail do contato.

Anexe o seguinte ao passo do script, após o loop de texto do 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 de nomes exibidos e endereços de e-mail separados por nova linha para todas as pessoas mencionadas com @ no documento.

Parte 4: Extrair um ID de Google Doc do corpo de um e-mail do Gmail

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

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

Adicione o seguinte script em um passo de script que é executado 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 em binário para uma string legível. Index encontra a posição do caractere do prefixo da URL, Length avança além dele, e Mid extrai o ID do documento naquela posição.

O corpo do e-mail decodificado é tipicamente HTML. O padrão docs.google.com/document/d/ aparece nos atributos href das tags de âncora, e os IDs dos 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: Use o conteúdo extraído a montante

Após a execução da etapa do script de análise, fullText e contacts contêm o texto do documento extraído e os contatos mencionados com @. Encadeie uma operação a montante com base 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. Veja Use OpenAI para processar dados em uma operação de Studio, Use Azure OpenAI em uma operação de Studio, ou Processe documentos com IA.
• Poste fullText ou contacts em um canal de notificação, mapeando o valor para uma atividade Post Message do Slack ou Microsoft Teams. Veja Envie uma notificação do Slack a partir de uma operação de Studio.
• Escreva 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.

Verifique a integração

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

2. Nos logs da 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 ao passo do script para inspecionar o valor no log de operações.

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

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

   • Confirme que google_docs_document_id está definido com o ID do 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. Compartilhe o documento com o endereço de e-mail client_email da conta de serviço diretamente no Google Docs, se necessário.

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 itens são ignorados pelo loop externo While porque GetJSONString retorna uma string vazia para o caminho ausente.