Google Docs-Inhalte in Jitterbit Studio lesen und analysieren

Einführung

Der Google Docs-Connector ruft Dokumente aus Google Docs als strukturierte JSON-Daten ab. Das Feld content, das eine Get Docs-Aktivität zurückgibt, enthält den vollständigen Dokumenttext und kann direkt an ein LLM als String übergeben werden (siehe Dokumente mit KI verarbeiten). Wenn man granularere Kontrolle benötigt, lässt sich die verschachtelte Struktur des Dokuments mit GetJSONString und indizierten Pfaden durchlaufen, um spezifische Elemente zu extrahieren: einzelne Absätze, Namen und E-Mail-Adressen von @-erwähnten Kontakten oder andere Inline-Objekte.

In diesem Leitfaden werden drei Muster behandelt:

• Durchlaufen der verschachtelten Elementstruktur des Dokuments mit GetJSONString und indizierten Pfaden zum Zusammensetzen von Absatztexten.
• Lesen von person-Elementen zum Extrahieren von Name und E-Mail-Adresse von @-erwähnten Kontakten.
• Extrahieren einer Google Doc-ID aus einem Gmail-Nachrichtentext, wenn der Dokumentlink als Teil einer E-Mail-Benachrichtigung ankommt.

Dieser Leitfaden baut auf Dokumente mit KI verarbeiten auf, das die grundlegende Einrichtung der Google Docs-Verbindung und die einfache Source.content-Zuordnung behandelt. Informationen zu Voraussetzungen für Google Docs-Verbindungen finden Sie unter Google Docs-Voraussetzungen.

Designmuster

Das Analysieren von Dokumentinhalten verwendet zwei verknüpfte Schritte innerhalb eines einzelnen Vorgangs:

Eine Anfrage-Transformation stellt die Dokument-ID für die Get Docs-Aktivität bereit. Eine zweite Transformation erfasst das Antwortfeld content als globale Variable. Der Skriptschritt durchläuft die verschachtelte JSON-Struktur, um Absatztexte und @-erwähnte Kontaktdetails zu extrahieren und erzeugt Variablen, die nachgelagerte Vorgänge direkt nutzen können. Teil 5 behandelt die Übergabe dieser Variablen an einen nachgelagerten Vorgang.

Falls die Dokument-ID nicht im Voraus bekannt ist (beispielsweise wenn sie in einer Gmail-Benachrichtigung ankommt), dekodiert ein vorgelagerter Skriptschritt den E-Mail-Text und extrahiert die ID, bevor die Transformation ausgeführt wird. Teil 4 behandelt diesen Fall.

Teil 1: Google Docs-Verbindung konfigurieren

Richten Sie eine Google Docs-Verbindung wie in Google Docs-Voraussetzungen und Google Docs-Verbindung beschrieben ein.

Nach dem Erstellen der Verbindung erstellen Sie eine Projektvariable zur Speicherung der Dokument-ID:

1. Öffnen Sie in Studio das Projektaktionsmenü und wählen Sie Projektvariablen aus.
2. Erstellen Sie eine Projektvariable namens google_docs_document_id. Legen Sie den Standardwert auf die Dokument-ID des Dokuments fest, das Sie abrufen möchten (sichtbar in der Google Docs-URL: https://docs.google.com/document/d/<document-id>/edit), oder lassen Sie den Wert leer, wenn die ID zur Laufzeit wie in Teil 4 beschrieben gesetzt wird.

Referenzieren Sie diese Variable in Skripten und Transformationen mit dem Präfix $ als $google_docs_document_id.

Teil 2: Dokument abrufen und Inhalte erfassen

Vorgang „Fetch Document" erstellen

1. Erstellen Sie in Studio einen neuen Vorgang. Nennen Sie ihn Fetch Document oder einen ähnlichen Namen.

2. Erweitern Sie auf der Designkomponentenpalette den Google Docs-Endpunkt. Ziehen Sie den Aktivitätstyp Get Docs auf die Designoberfläche, um eine Aktivitätsinstanz zu erstellen.

3. Doppelklicken Sie auf die Aktivität, um ihre Konfiguration zu öffnen.

4. Name: Geben Sie einen Namen für die Aktivität ein, z. B. Get Document Content.

5. Klicken Sie auf Weiter, um die Datenschemas zu überprüfen, und klicken Sie dann auf Fertig.

Dokument-ID zuordnen

Fügen Sie vor der Get Docs-Aktivität eine Anfrage-Transformation hinzu, um die Dokument-ID bereitzustellen. Ordnen Sie das Anfragefield docid der Projektvariablen google_docs_document_id zu:

<trans>
$google_docs_document_id
</trans>

Den Dokumentinhalt erfassen

Fügen Sie nach der Aktivität Get Docs eine Transformation hinzu, um das Antwortfeld content als globale Variable zu erfassen. Fügen Sie diesen Skriptknoten unmapped (nicht einer Zielfeld zugewiesen) hinzu, damit er während der Transformation als Nebeneffekt ausgeführt wird:

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

Das Feld content enthält die JSON-Darstellung von document.body.content: ein Array struktureller Elemente wie Absätze, Umbrüche und Tabellen. Dieser Wert ist nun als docContent für alle nachfolgenden Skriptschritte in derselben oder verketteten Operation verfügbar.

Den Parsing-Skriptschritt hinzufügen

Fügen Sie nach der Transformation auf der Designoberfläche einen Skriptschritt zur Operation hinzu. Die Traversierungslogik wird in Teil 3 hinzugefügt.

Teil 3: Die Dokumentstruktur durchlaufen

Die Variable docContent enthält ein JSON-Array struktureller Elemente. Jedes Element stellt eine Block-Ebenen-Einheit im Dokument dar. Der Pfad, um auf Textinhalte innerhalb eines Absatzes zu zugreifen, ist:

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

Dabei ist i der Index im Array der obersten Inhalte und j der Index im Array der Elemente eines Absatzes. Nicht jedes Inhaltselement enthält einen paragraph-Knoten (Umbrüche und Tabellen nicht), und nicht jedes Absatzelement enthält einen textRun-Knoten (@-erwähnte Personen verwenden stattdessen einen person-Knoten). GetJSONString gibt eine leere Zeichenkette zurück, wenn ein Pfad nicht vorhanden ist, daher beenden sich beide While-Schleifen natürlicherweise, wenn ein Index außerhalb der Grenzen liegt.

Absatztext extrahieren

Fügen Sie das folgende Skript dem in Teil 2 erstellten Skriptschritt hinzu:

<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 entfernt die umgebenden Anführungszeichen, die GetJSONString in seiner Ausgabe für Zeichenkettenwerte einfügt. Nach Abschluss des Skripts enthält fullText den vollständigen Text des Dokuments mit beibehaltenen Absatzumbrüchen. Übergeben Sie fullText als Prompt-Body an eine nachgelagerte LLM-Operation. Informationen zur LLM-Einrichtung finden Sie unter OpenAI verwenden, um Daten in einer Studio-Operation zu verarbeiten oder Azure OpenAI in einer Studio-Operation verwenden.

@-erwähnte Kontakte extrahieren

Wenn ein Google Doc @-erwähnte Personen enthält, erscheint jede Erwähnung als person-Element im Array der Elemente eines Absatzes. Der untergeordnete Knoten personProperties enthält den Anzeigenamen und die E-Mail-Adresse des Kontakts.

Fügen Sie das folgende an den Skriptschritt an, nach der Schleife für den Absatztext:

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

Nach Abschluss des Skripts enthält contacts eine zeilenumbruchgetrennte Liste mit Anzeigenamen und E-Mail-Adressen aller @-erwähnten Personen im Dokument.

Teil 4: Eine Google Doc-ID aus einem Gmail-E-Mail-Text extrahieren

Wenn eine Studio-Operation eine E-Mail-Benachrichtigung erhält, die einen Link zu einem Google Doc enthält, kann die Dokument-ID aus dem E-Mail-Text extrahiert werden, bevor die Fetch Document-Operation ausgeführt wird.

Gmail-API-Responses codieren E-Mail-Texte mit base64url-Codierung, die - durch + und _ durch / im Vergleich zur Standard-Base64 ersetzt. Die Decodierung erfordert die Rückgängigmachung dieser Ersetzungen, bevor Base64Decode aufgerufen wird.

Fügen Sie das folgende Skript in einem Skriptschritt hinzu, der vor der Fetch Document-Operation ausgeführt wird:

<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 korrigiert die base64url-Zeichenersetzung. Die Kette Base64Decode → BinaryToHex → HexToString konvertiert binary-decodierten Inhalt in eine lesbare Zeichenkette. Index findet die Zeichenposition des URL-Präfix, Length geht über diesen hinaus, und Mid extrahiert die Dokument-ID an dieser Position.

Der dekodierte E-Mail-Text ist typischerweise HTML. Das Muster docs.google.com/document/d/ erscheint in Anker-Tag-href-Attributen, und Google Docs-Dokument-IDs sind durchgehend 44 Zeichen lang. Nach Abschluss dieses Skripts wird google_docs_document_id gesetzt und die Fetch Document-Operation kann ausgeführt werden.

Teil 5: Verwenden Sie den extrahierten Inhalt nachgelagert

Nach Ausführung des Parsing-Skriptschritts enthalten fullText und contacts den extrahierten Dokumenttext und die @-erwähnten Kontakte. Verketten Sie eine nachgelagerte Operation nach erfolgreichem Abschluss der Fetch Document-Operation, um diese Werte zu nutzen:

• Senden Sie fullText an ein LLM zur Zusammenfassung oder Analyse, indem Sie es dem Anfragebody einer OpenAI oder Azure OpenAI Prompt-Aktivität zuordnen. Siehe OpenAI zur Datenverarbeitung in einer Studio-Operation verwenden, Azure OpenAI in einer Studio-Operation verwenden oder Dokumente mit KI verarbeiten.
• Leiten Sie fullText oder contacts an einen Benachrichtigungskanal weiter, indem Sie den Wert einer Slack Post Message- oder Microsoft Teams-Aktivität zuordnen. Siehe Slack-Benachrichtigung aus einer Studio-Operation senden.
• Schreiben Sie die Werte in einen Datensatz oder eine Datei zur Speicherung.

Da fullText und contacts globale Variablen sind, sind sie für jede nach der Fetch Document-Operation verkettete Operation ohne zusätzliche Zuordnung verfügbar.

Überprüfen Sie die Integration

1. Stellen Sie bereit und führen Sie die Fetch Document-Operation aus.

2. Bestätigen Sie in den Operationslogs, dass die Get Document Content-Aktivität erfolgreich abgeschlossen wurde.

3. Bestätigen Sie, dass fullText den erwarteten Dokumenttext enthält. Fügen Sie WriteToOperationLog($fullText) vorübergehend zum Skriptschritt hinzu, um den Wert im Operationslog zu überprüfen.

4. Wenn das Dokument @-Erwähnungen enthält, bestätigen Sie, dass contacts nicht leer ist und die erwarteten Namen und E-Mail-Adressen enthält.

5. Wenn die Get Docs-Aktivität ein leeres oder null content-Feld zurückgibt:

   • Bestätigen Sie, dass google_docs_document_id auf die korrekte 44-stellige Dokument-ID gesetzt ist.
   • Bestätigen Sie, dass das in der Google Docs-Verbindung konfigurierte Service-Konto Lesezugriff auf das Dokument hat. Teilen Sie das Dokument bei Bedarf direkt in Google Docs mit der client_email-Adresse des Service-Kontos.

6. Wenn fullText unerwartete Lücken enthält, beachten Sie, dass Strukturelemente wie Seitenumbrüche und Tabellenzellen Inhaltselemente ohne paragraph-Knoten erzeugen. Diese werden von der äußeren While-Schleife übersprungen, da GetJSONString eine leere Zeichenfolge für den fehlenden Pfad zurückgibt.