Leer y analizar contenido de Google Docs en Jitterbit Studio

Introducción

El conector de Google Docs recupera documentos de Google Docs como datos JSON estructurados. El campo content que devuelve una actividad Get Docs contiene el cuerpo completo del documento y se puede pasar directamente a un LLM como cadena de texto (consulta Procesar documentos con IA). Cuando se necesita un acceso más granular, se puede recorrer la estructura anidada del documento usando GetJSONString para extraer elementos específicos: párrafos individuales, nombres de contactos mencionados con @ y direcciones de correo electrónico, u otros objetos en línea.

Esta guía cubre tres patrones:

• Recorrer la estructura de elementos anidados del documento con GetJSONString y rutas indexadas para reunir texto de párrafos.
• Leer elementos person para extraer el nombre y la dirección de correo electrónico de contactos mencionados con @.
• Extraer un ID de Google Doc del cuerpo de un mensaje de Gmail cuando el enlace del documento llega como parte de una notificación por correo electrónico.

Esta guía se basa en Procesar documentos con IA, que cubre la configuración básica de la conexión de Google Docs y el mapeo directo de Source.content. Para los requisitos previos de la conexión de Google Docs, consulta Requisitos previos de Google Docs.

Patrón de diseño

El análisis del contenido del documento utiliza dos pasos vinculados dentro de una sola operación:

Una transformación de solicitud suministra el ID del documento a la actividad Get Docs. Una segunda transformación captura el campo de respuesta content como una variable global. El paso de script recorre la estructura JSON anidada para extraer texto de párrafos y detalles de contactos mencionados con @, produciendo variables que las operaciones posteriores pueden usar directamente. La Parte 5 cubre el paso de esas variables a una operación posterior.

Cuando el ID del documento no se conoce de antemano (por ejemplo, cuando llega dentro de una notificación de Gmail), un paso de script anterior decodifica el cuerpo del correo electrónico y extrae el ID antes de que se ejecute la transformación. La Parte 4 cubre este caso.

Parte 1: Configurar la conexión de Google Docs

Configura una conexión de Google Docs como se describe en Requisitos previos de Google Docs y Conexión de Google Docs.

Después de crear la conexión, crea una variable de proyecto para almacenar el ID del documento:

1. En Studio, abre el menú de acciones del proyecto y selecciona Variables de proyecto.
2. Crea una variable de proyecto llamada google_docs_document_id. Establece su valor predeterminado al ID del documento que deseas obtener (visible en la URL de Google Docs: https://docs.google.com/document/d/<document-id>/edit), o deja el valor vacío si el ID se establecerá en tiempo de ejecución como se describe en la Parte 4.

Haz referencia a esta variable en scripts y transformaciones usando el prefijo $ como $google_docs_document_id.

Parte 2: Obtener el documento y capturar el contenido

Crear la operación Fetch Document

1. En Studio, crea una nueva operación. Asígnale el nombre Fetch Document o un nombre similar.

2. En la paleta de componentes de diseño, expande el endpoint de Google Docs. Arrastra el tipo de actividad Get Docs al lienzo de diseño para crear una instancia de actividad.

3. Haz doble clic en la actividad para abrir su configuración.

4. Nombre: Escribe un nombre para la actividad, por ejemplo Get Document Content.

5. Haz clic en Next para revisar los esquemas de datos y luego haz clic en Finished.

Mapear el ID del documento

Agrega una transformación de solicitud antes de la actividad Get Docs para suministrar el ID del documento. Mapea el campo de solicitud docid a la variable de proyecto google_docs_document_id:

<trans>
$google_docs_document_id
</trans>

Capturar el contenido del documento

Después de la actividad Get Docs, agrega una transformación para capturar el campo de respuesta content como una variable global. Agrega este nodo de script sin asignar (no asignado a ningún campo de destino) para que se ejecute como efecto secundario durante la transformación:

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

El campo content contiene la representación JSON de document.body.content: un arreglo de elementos estructurales como párrafos, saltos de sección y tablas. Este valor ahora es accesible como docContent en cualquier paso de script posterior en la misma operación u operación encadenada.

Agregar el paso de script de análisis

Después de la transformación en el lienzo de diseño, agrega un paso de script a la operación. Agregarás la lógica de recorrido a este paso en Parte 3.

Parte 3: Recorrer la estructura del documento

La variable docContent contiene un arreglo JSON de elementos estructurales. Cada elemento representa una unidad a nivel de bloque en el documento. La ruta para acceder al contenido de texto dentro de un párrafo es:

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

Donde i es el índice en el arreglo de contenido de nivel superior y j es el índice en el arreglo de elementos de un párrafo. No todo elemento de contenido contiene un nodo paragraph (los saltos de sección y las tablas no lo hacen), y no todo elemento de párrafo contiene un nodo textRun (las personas mencionadas con @ usan un nodo person en su lugar). GetJSONString devuelve una cadena vacía cuando una ruta no existe, por lo que ambos bucles While terminan naturalmente cuando un índice está fuera de rango.

Extraer texto de párrafos

Agrega el siguiente script al paso de script creado en 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 elimina los caracteres de comillas dobles que GetJSONString incluye en su salida para valores de cadena. Después de que se completa el script, fullText contiene el texto completo del documento con saltos de línea de párrafo preservados. Pasa fullText como cuerpo del indicador a una operación de LLM descendente. Para configurar LLM, consulta Usar OpenAI para procesar datos en una operación de Studio o Usar Azure OpenAI en una operación de Studio.

Extraer contactos mencionados con @

Cuando un documento de Google contiene personas mencionadas con @, cada mención aparece como un elemento person dentro del arreglo de elementos de un párrafo. El nodo secundario personProperties contiene el nombre para mostrar y la dirección de correo electrónico del contacto.

Agrega lo siguiente al paso de script, después del bucle de texto de párrafo:

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

Después de que se completa el script, contacts contiene una lista separada por saltos de línea de nombres para mostrar y direcciones de correo electrónico para todas las personas mencionadas con @ en el documento.

Parte 4: Extraer un ID de documento de Google del cuerpo de un correo electrónico de Gmail

Cuando una operación de Studio recibe una notificación de correo electrónico que contiene un enlace a un documento de Google, el ID del documento se puede extraer del cuerpo del correo electrónico antes de que se ejecute la operación Fetch Document.

Las respuestas de la API de Gmail codifican los cuerpos de correo electrónico usando codificación base64url, que sustituye - por + y _ por / en comparación con base64 estándar. La decodificación requiere revertir estas sustituciones antes de llamar a Base64Decode.

Agrega el siguiente script en un paso de script que se ejecuta antes de la operación 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 la sustitución de caracteres base64url. La cadena Base64Decode → BinaryToHex → HexToString convierte contenido decodificado en binario a una cadena legible. Index encuentra la posición de carácter del prefijo de URL, Length avanza pasarlo, y Mid extrae el ID del documento en esa posición.

El cuerpo del correo electrónico decodificado suele ser HTML. El patrón docs.google.com/document/d/ aparece en los atributos href de las etiquetas de anclaje, y los IDs de documentos de Google Docs tienen consistentemente 44 caracteres de largo. Después de que se completa este script, google_docs_document_id se establece y la operación Fetch Document puede ejecutarse.

Parte 5: Usar el contenido extraído en operaciones posteriores

Después de que se ejecuta el paso del script de análisis, fullText y contacts contienen el texto del documento extraído y los contactos mencionados con @. Encadena una operación posterior al éxito de la operación Fetch Document para usar estos valores:

• Envía fullText a un LLM para resumir o analizar mapeándolo al cuerpo de solicitud de una actividad Prompt de OpenAI o Azure OpenAI. Consulta Usar OpenAI para procesar datos en una operación de Studio, Usar Azure OpenAI en una operación de Studio o Procesar documentos con IA.
• Publica fullText o contacts en un canal de notificaciones mapeando el valor a una actividad Post Message de Slack o Microsoft Teams. Consulta Enviar una notificación de Slack desde una operación de Studio.
• Escribe los valores en un registro o archivo para almacenamiento.

Dado que fullText y contacts son variables globales, están disponibles para cualquier operación encadenada después de la operación Fetch Document sin mapeo adicional.

Verificar la integración

1. Implementa y ejecuta la operación Fetch Document.

2. En los registros de operación, confirma que la actividad Get Document Content se completó correctamente.

3. Confirma que fullText contiene el texto del documento esperado. Añade WriteToOperationLog($fullText) temporalmente al paso del script para inspeccionar el valor en el registro de operación.

4. Si el documento contiene menciones con @, confirma que contacts no está vacío y contiene los nombres y direcciones de correo electrónico esperados.

5. Si la actividad Get Docs devuelve un campo content vacío o nulo:

   • Confirma que google_docs_document_id está establecido en el ID de documento correcto de 44 caracteres.
   • Confirma que la cuenta de servicio configurada en la conexión de Google Docs tiene acceso de lectura al documento. Si es necesario, comparte el documento directamente con la dirección client_email de la cuenta de servicio en Google Docs.

6. Si fullText contiene espacios vacíos inesperados, ten en cuenta que elementos estructurales como saltos de sección y celdas de tabla producen elementos de contenido sin un nodo paragraph. El bucle While externo los omite porque GetJSONString devuelve una cadena vacía para la ruta faltante.