Google Docs-Inhalte in Jitterbit Studio lesen und parsen

Einführung

Der Google Docs-Connector ruft Dokumente aus Google Docs als strukturierte JSON-Daten ab. Das content-Feld, das von einer Get Docs-Aktivität zurückgegeben wird, enthält den gesamten Dokumentinhalt und kann direkt als String an ein LLM übergeben werden (siehe Dokumente mit KI verarbeiten). Wenn ein granularerer Zugriff erforderlich ist, kann die verschachtelte Struktur des Dokuments mit GetJSONString durchlaufen werden, um spezifische Elemente zu extrahieren: einzelne Absätze, @-erwähnte Kontaktnamen und E-Mail-Adressen oder andere Inline-Objekte.

Dieser Leitfaden behandelt drei Muster:

• Durchlaufen der verschachtelten Elementstruktur des Dokuments mit GetJSONString und indizierten Pfaden, um den Absatztext zusammenzustellen.
• Lesen von person-Elementen, um den Namen und die E-Mail-Adresse von @-erwähnten Kontakten zu extrahieren.
• Extrahieren einer Google Doc-ID aus dem Textkörper einer Gmail-Nachricht, wenn der Dokumentenlink als Teil einer E-Mail-Benachrichtigung eintrifft.

Dieser Leitfaden baut auf Dokumente mit KI verarbeiten auf, der die grundlegende Einrichtung der Google Docs-Verbindung und die einfache Zuordnung von Source.content behandelt. Für die Voraussetzungen der Google Docs-Verbindung siehe Voraussetzungen für Google Docs.

Entwurfsmuster

Das Parsen des Dokumenteninhalts verwendet zwei verknüpfte Schritte innerhalb einer einzigen Operation:

Eine Anfrage-Transformation liefert die Dokument-ID an die Get Docs-Aktivität. Eine zweite Transformation erfasst das content-Antwortfeld als globale Variable. Der Skript-Schritt durchläuft die verschachtelte JSON-Struktur, um den Absatztext und die @-erwähnten Kontaktdetails zu extrahieren, wodurch Variablen erzeugt werden, die von nachgelagerten Operationen direkt verwendet werden können. Teil 5 behandelt das Übergeben dieser Variablen an eine nachgelagerte Operation.

Wenn die Dokument-ID im Voraus nicht bekannt ist (zum Beispiel, wenn sie in einer Gmail-Benachrichtigung ankommt), decodiert ein vorhergehender Skriptschritt den E-Mail-Inhalt und extrahiert die ID, bevor die Transformation ausgeführt wird. Teil 4 behandelt diesen Fall.

Teil 1: Konfigurieren der Google Docs-Verbindung

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

Nachdem Sie die Verbindung erstellt haben, erstellen Sie eine Projektvariable, um die Dokument-ID zu speichern:

1. Öffnen Sie im Studio das Projektaktionsmenü und wählen Sie Projektvariablen.
2. Erstellen Sie eine Projektvariable mit dem Namen google_docs_document_id. Setzen Sie den Standardwert auf die Dokument-ID des Dokuments, 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 festgelegt wird, wie in Teil 4 beschrieben.

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

Teil 2: Dokument abrufen und den Inhalt erfassen

Erstellen Sie die Abrufdokument-Operation

1. Erstellen Sie im Studio eine neue Operation. Nennen Sie sie Dokument abrufen oder einen ähnlichen Namen.

2. Erweitern Sie im Design-Komponenten-Palette den Google Docs-Endpunkt. Ziehen Sie den Aktivitätstyp Get Docs auf die Designflä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, zum Beispiel Dokumentinhalt abrufen.

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

Dokument-ID zuordnen

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

<trans>
$google_docs_document_id
</trans>

Erfassen des Dokumentinhalts

Nach der Get Docs-Aktivität fügen Sie eine Transformation hinzu, um das content-Antwortfeld als globale Variable zu erfassen. Fügen Sie diesen Skriptnode unmapped (nicht einem Ziel-Feld zugewiesen) hinzu, damit er als Nebeneffekt während der Transformation ausgeführt wird:

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

Das content-Feld enthält die JSON-Darstellung von document.body.content: ein Array von strukturellen Elementen wie Absätzen, Abschnittswechseln und Tabellen. Dieser Wert ist jetzt als docContent für jeden nachfolgenden Skriptschritt in derselben Operation oder in einer verketteten Operation zugänglich.

Fügen Sie den Parsing-Skriptschritt hinzu

Nach der Transformation auf der Entwurfskanvas fügen Sie einen Skriptschritt zur Operation hinzu. Sie werden die Traversierungslogik in diesem Schritt in Teil 3 hinzufügen.

Teil 3: Durchlaufen der Dokumentstruktur

Die Variable docContent enthält ein JSON-Array von strukturellen Elementen. Jedes Element stellt eine Blockebeneinheit im Dokument dar. Der Pfad, um auf den Textinhalt innerhalb eines Absatzes zuzugreifen, lautet:

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

Dabei ist i der Index im obersten Inhaltsarray und j der Index im Elementarray eines Absatzes. Nicht jedes Inhaltsitem enthält einen paragraph-Knoten (Abschnittswechsel und Tabellen tun dies nicht), und nicht jedes Absatz-Element enthält einen textRun-Knoten (mit @-erwähnten Personen wird stattdessen ein person-Knoten verwendet). GetJSONString gibt einen leeren String zurück, wenn ein Pfad nicht existiert, sodass beide While-Schleifen natürlich enden, wenn ein Index außerhalb der Grenzen liegt.

Absatztext extrahieren

Fügen Sie das folgende Skript zum im 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 Stringwerte enthält. Nach Abschluss des Skripts enthält fullText den vollständigen Text des Dokuments mit erhaltenen Absatzzeilenumbrüchen. Übergeben Sie fullText als Eingabetext an eine nachgelagerte LLM-Operation. Für die LLM-Einrichtung siehe Verwenden Sie OpenAI zur Verarbeitung von Daten in einer Studio-Operation oder Verwenden Sie Azure OpenAI in einer Studio-Operation.

Kontakte mit @-Erwähnungen extrahieren

Wenn ein Google-Dokument @-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 Folgendes zum Skriptschritt hinzu, nach der Schleife über 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 durch Zeilenumbrüche getrennte Liste von Anzeigenamen und E-Mail-Adressen aller @-erwähnten Personen im Dokument.

Teil 4: Eine Google-Dokument-ID aus dem Textkörper einer Gmail-E-Mail extrahieren

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

Gmail-API-Antworten kodieren E-Mail-Textkörper mit base64url-Kodierung, die - für + und _ für / im Vergleich zur standardmäßigen base64-Kodierung ersetzt. Das Dekodieren erfordert das Umkehren dieser Ersetzungen, bevor Base64Decode aufgerufen wird.

Fügen Sie das folgende Skript in einen Skriptschritt ein, 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 Ersetzung der base64url-Zeichen. Die Kette Base64Decode → BinaryToHex → HexToString konvertiert binär-dekodierte Inhalte in eine lesbare Zeichenfolge. Index findet die Zeichenposition des URL-Präfixes, Length geht darüber hinaus, und Mid extrahiert die Dokument-ID an dieser Position.

Der dekodierte E-Mail-Inhalt ist typischerweise HTML. Das Muster docs.google.com/document/d/ erscheint in den href-Attributen von Anker-Tags, und die 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 im weiteren Verlauf

Nachdem der Parsing-Skript-Schritt ausgeführt wurde, halten fullText und contacts den extrahierten Dokumenttext und die @-erwähnten Kontakte. Verkettete eine nachfolgende Operation an den Erfolg der Fetch Document-Operation, um diese Werte zu verwenden:

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

Da fullText und contacts globale Variablen sind, stehen sie jeder Operation zur Verfügung, die nach der Fetch Document-Operation ohne zusätzliche Zuordnung verkettet wird.

Überprüfen Sie die Integration

1. Bereitstellen und ausführen der Fetch Document-Operation.

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

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

4. Wenn das Dokument @-Erwähnungen enthält, stellen Sie sicher, 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 Dienstkonto, das in der Google Docs-Verbindung konfiguriert ist, Lesezugriff auf das Dokument hat. Teilen Sie das Dokument bei Bedarf direkt mit der client_email-Adresse des Dienstkontos in Google Docs.

6. Wenn fullText unerwartete Lücken enthält, beachten Sie, dass strukturelle Elemente wie Abschnittswechsel und Tabellenzellen Inhaltselemente ohne paragraph-Knoten erzeugen. Diese werden von der äußeren While-Schleife übersprungen, da GetJSONString für den fehlenden Pfad einen leeren String zurückgibt.