Leer y analizar el 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 devuelto por una actividad de Obtener Docs contiene el cuerpo completo del documento y se puede pasar directamente a un LLM como una cadena (ver Procesar documentos con IA). Cuando se necesita un acceso más granular, se puede recorrer la estructura anidada del documento utilizando 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 ensamblar el texto de los párrafos.
• Leer elementos person para extraer el nombre y la dirección de correo electrónico de los 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 conexión de Google Docs y el mapeo sencillo de Source.content. Para los requisitos previos de conexión de Google Docs, consulte 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 de Obtener 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 el texto de los párrafos y los detalles de contacto mencionados con @, produciendo variables que las operaciones posteriores pueden utilizar directamente. 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. 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 prerrequisitos 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 en el 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 Parte 4.

Referencia 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 Obtener Documento

1. En Studio, crea una nueva operación. Nómbrala Obtener Documento o un nombre similar.

2. En la paleta de componentes de diseño, expande el endpoint de Google Docs. Arrastra el tipo de actividad Obtener 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: Ingresa un nombre para la actividad, por ejemplo Obtener Contenido del Documento.

5. Haz clic en Siguiente para revisar los esquemas de datos, luego haz clic en Finalizado.

Mapear el ID del documento

Agrega una transformación de solicitud antes de la actividad Obtener Docs para proporcionar 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>

Captura el contenido del documento

Después de la actividad Obtener Docs, añade 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 objetivo) para que se ejecute como un 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 para cualquier paso de script subsiguiente en la misma operación o en una operación encadenada.

Agrega el paso de script de análisis

Después de la transformación en el lienzo de diseño, añade 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 de bloque en el documento. La ruta para alcanzar el 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 todos los elementos de contenido contienen un nodo paragraph (los saltos de sección y las tablas no lo hacen), y no todos los elementos de párrafo contienen un nodo textRun (las personas mencionadas con @ utilizan 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 límites.

Extraer texto del párrafo

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 el script se complete, fullText contiene el texto completo del documento con los saltos de línea de párrafo preservados. Pasa fullText como el cuerpo del prompt a una operación LLM posterior. Para la configuración de 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 array de elementos de un párrafo. El nodo hijo personProperties contiene el nombre para mostrar y la dirección de correo electrónico del contacto.

Agrega lo siguiente al paso del script, después del bucle de texto del 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 el script se complete, contacts contiene una lista de nombres para mostrar y direcciones de correo electrónico separados por saltos de línea para todas las personas mencionadas con @ en el documento.

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

Cuando una operación de Studio recibe una notificación por 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 de Fetch Document.

Las respuestas de la API de Gmail codifican los cuerpos de los correos electrónicos utilizando codificación base64url, que sustituye - por + y _ por / en comparación con el 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 ejecute antes de la operación de 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 el contenido decodificado en binario a una cadena legible. Index encuentra la posición del carácter del prefijo de la URL, Length avanza más allá de él, y Mid extrae el ID del documento en esa posición.

El cuerpo del correo electrónico decodificado es típicamente 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 longitud. Después de que este script se complete, se establece google_docs_document_id y se puede ejecutar la operación Fetch Document.

Parte 5: Usa el contenido extraído aguas abajo

Después de que se ejecute 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 aguas abajo en el é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 del aviso de una actividad de OpenAI o Azure OpenAI Prompt. 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 notificación mapeando el valor a una actividad de Slack Post Message 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.

Debido a 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.

Verifica la integración

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

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

3. Confirma que fullText contiene el texto del documento esperado. Agrega WriteToOperationLog($fullText) temporalmente al paso del script para inspeccionar el valor en el registro de operaciones.

4. Si el documento contiene menciones con @, confirma que contacts no esté vacío y contenga 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é configurado con el ID de documento correcto de 44 caracteres.
   • Confirma que la cuenta de servicio configurada en la conexión de Google Docs tenga acceso de lectura al documento. Comparte el documento con la dirección de correo electrónico client_email de la cuenta de servicio directamente en Google Docs si es necesario.

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