Text in einem Dokument zusammenführen

In dieser Anleitung wird erläutert, wie Sie mit der Google Docs API Informationen aus einer oder mehreren externen Datenquellen in ein vorhandenes Vorlagendokument einfügen.

Eine Vorlage ist ein Dokumenttyp, der festen Text und Platzhalter für dynamische Inhalte enthält. Eine Vertragsvorlage kann beispielsweise festen Text mit Platzhaltern für den Namen und die Adresse des Empfängers enthalten. Die App fügt dann nutzerspezifische Daten in die Vorlage ein, um das fertige Dokument zu erstellen.

Es gibt mehrere Gründe, warum dieser Ansatz nützlich ist:

  • Designer können das Design eines Dokuments mit Google Docs optimieren. Das ist einfacher, als Parameter in Ihrer App anzupassen, um das gerenderte Layout festzulegen.

  • Das Trennen von Inhalt und Präsentation ist ein bekanntes Designprinzip mit vielen Vorteilen.

Diagramm, das zeigt, wie Daten aus einer Quelle in eine Vorlage eingefügt werden, um ein Dokument zu erstellen.
Abbildung 1. Daten in eine Vorlage einfügen, um ein Dokument zu erstellen.

Funktionsweise des Zusammenführens von Dokumenten

Hier ein Beispiel, wie Sie mit der Docs API Daten in ein Dokument einfügen können:

  1. Erstellen Sie Ihr Dokument mit Platzhalterinhalten, um das Design und das Format festzulegen. Alle Textformatierungen, die Sie ersetzen möchten, bleiben erhalten.

  2. Ersetzen Sie für jedes einzufügende Element den Platzhalterinhalt durch ein Tag. Verwenden Sie Strings, die normalerweise nicht vorkommen. For example, {{account-holder-name}} might be a good tag.

  3. Verwenden Sie in Ihrem Code die Google Drive API, um eine Kopie des Dokuments zu erstellen.

  4. Verwenden Sie in Ihrem Code die batchUpdate Methode der Docs API mit dem Dokumentnamen und fügen Sie eine ReplaceAllTextRequestein.

Dokument-IDs verweisen auf ein Dokument und können aus der URL abgeleitet werden:

https://docs.google.com/document/d/DOCUMENT_ID/edit

Vorlagen verwalten

Für Vorlagendokumente, die von der App definiert werden und deren Inhaber sie ist, erstellen Sie die Vorlage mit einem speziellen Konto, das die App repräsentiert. Dienst konten sind eine gute Wahl und vermeiden Komplikationen mit Google Workspace-Richtlinien, die die Freigabe einschränken.

Wenn Sie Instanzen von Dokumenten aus Vorlagen erstellen, verwenden Sie immer Endnutzer-Anmeldedaten. So haben Nutzer die vollständige Kontrolle über das resultierende Dokument und es werden Skalierungsprobleme im Zusammenhang mit den Limits pro Nutzer in Google Drive vermieden.

So erstellen Sie eine Vorlage mit einem Dienstkonto und den App-Anmeldedaten:

  1. Erstellen Sie mit documents.create in der Docs API ein Dokument.
  2. Aktualisieren Sie die Berechtigungen, damit die Dokumentempfänger es mit permissions.create in der Drive API lesen können.
  3. Aktualisieren Sie die Berechtigungen, damit Vorlagenautoren mit permissions.create in der Drive API in das Dokument schreiben können.
  4. Bearbeiten Sie die Vorlage nach Bedarf.

So erstellen Sie eine Instanz des Dokuments mit den Nutzeranmeldedaten:

  1. Erstellen Sie mit files.copy in der Drive API eine Kopie der Vorlage.
  2. Ersetzen Sie Werte mit documents.batchUpdate in der Docs API.

Beispiel: Daten in eine Vorlage einfügen

Das folgende Codebeispiel zeigt, wie Sie zwei Felder auf allen Tabs einer Vorlage durch tatsächliche Werte ersetzen, um ein fertiges Dokument zu erstellen:

Bild einer Dokumentvorlage mit Platzhaltern für Tags und dem daraus resultierenden zusammengeführten Dokument.
Abbildung 2. Platzhalter-Tags durch Werte ersetzen.

Verwenden Sie den folgenden Code, um diese Zusammenführung auszuführen:

Java

String customerName = "Alice";
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy/MM/dd");
String date = formatter.format(LocalDate.now());

// Make a copy of the template document using the Drive API.
String copyTitle = "Merged Document";
File copyMetadata = new File().setName(copyTitle);
File documentCopyFile =
        driveService.files().copy(DOCUMENT_ID, copyMetadata).execute();
String documentCopyId = documentCopyFile.getId();

List requests = new ArrayList<>();
// One option for replacing all text is to specify all tab IDs.
requests.add(new Request()
        .setReplaceAllText(new ReplaceAllTextRequest()
                .setContainsText(new SubstringMatchCriteria()
                        .setText("{{customer-name}}")
                        .setMatchCase(true))
                .setReplaceText(customerName)
                .setTabsCriteria(new TabsCriteria()
                        .addTabIds(TAB_ID_1)
                        .addTabIds(TAB_ID_2)
                        .addTabIds(TAB_ID_3))));
// Another option is to omit TabsCriteria if you are replacing across all tabs.
requests.add(new Request()
        .setReplaceAllText(new ReplaceAllTextRequest()
                .setContainsText(new SubstringMatchCriteria()
                        .setText("{{date}}")
                        .setMatchCase(true))
                .setReplaceText(date)));

BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest();
service.documents().batchUpdate(documentCopyId, body.setRequests(requests)).execute();

Node.js

  let customerName = 'Alice';
  let date = yyyymmdd()
  let requests = [
    // One option for replacing all text is to specify all tab IDs.
    {
      replaceAllText: {
        containsText: {
          text: '{{customer-name}}',
          matchCase: true,
        },
        replaceText: customerName,
        tabsCriteria: {
          tabIds: [TAB_ID_1, TAB_ID_2, TAB_ID_3],
        },
      },
    },
    // Another option is to omit TabsCriteria if you are replacing across all tabs.
    {
      replaceAllText: {
        containsText: {
          text: '{{date}}',
          matchCase: true,
        },
        replaceText: date,
      },
    },
  ];

  // Make a copy of the template document using the Drive API.
  let copyTitle = 'Merged Document';
  driveService.files.copy({
    fileId: '1yBx6HSnu_gbV2sk1nChJOFo_g3AizBhr-PpkyKAwcTg',
    resource: {
      name: copyTitle,
    },
  }, (err, driveResponse) => {
    if (err) return console.log('The Drive API returned an error: ' + err);
    let documentCopyId = driveResponse.data.id;

    google.options({auth: auth});
    google
        .discoverAPI(
            'https://docs.googleapis.com/$discovery/rest?version=v1&key={YOUR_API_KEY}')
        .then(function(docs) {
          docs.documents.batchUpdate(
              {
                documentId: documentCopyId,
                resource: {
                  requests,
                },
              },
              (err, {data}) => {
                if (err) return console.log('The API returned an error: ' + err);
                console.log(data);
              });
        });
  });

Python

customer_name = 'Alice'
date = datetime.datetime.now().strftime("%y/%m/%d")

# Make a copy of the template document using the Drive API.
copy_title = 'Merged Document'
body = {
    'name': copy_title
}
drive_response = drive_service.files().copy(
    fileId=DOCUMENT_ID, body=body).execute()
document_copy_id = drive_response.get('id')

requests = [
        # One option for replacing all text is to specify all tab IDs.
        {
        'replaceAllText': {
            'containsText': {
                'text': '{{customer-name}}',
                'matchCase':  'true'
            },
            'replaceText': customer_name,
            'tabsCriteria': {
                'tabIds': [TAB_ID_1, TAB_ID_2, TAB_ID_3],
            },
        }},
        # Another option is to omit TabsCriteria if you are replacing across all tabs.
        {
        'replaceAllText': {
            'containsText': {
                'text': '{{date}}',
                'matchCase':  'true'
            },
            'replaceText': str(date),
        }
    }
]

result = service.documents().batchUpdate(
    documentId=document_copy_id, body={'requests': requests}).execute()

Dynamische Listen und Tabellen verarbeiten

Bei einer Standarddokumentzusammenführung werden mit ReplaceAllTextRequest einzelne einmalige Platzhalter ersetzt (z. B. {{customer-name}} oder {{date}}). Wenn Ihre Daten jedoch eine dynamische Liste von Elementen enthalten (z. B. Zeilen in einer Rechnung, eine Liste bestellter Produkte oder eine dynamische Tabelle), können Sie die Standardtextersetzung nicht verwenden, da die Anzahl der Elemente beim Entwerfen der Vorlage unbekannt ist.

Verwenden Sie eine der folgenden Strategien, um dynamische Listeninhalte zu verarbeiten.

Option 1: Zeilen an eine Vorlagentabelle anhängen

Wenn Ihre Vorlagendokumente bereits eine formatierte Tabelle enthalten (z. B. mit einer Kopfzeile und einer einzelnen Platzhalterzeile), können Sie Zeilen für jedes Element in Ihrer Liste dynamisch klonen und ausfüllen:

  1. Vorlagenstruktur lesen:Suchen Sie mit der documents.get Methode die Tabelle und ermitteln Sie den Index der Vorlagenzeile.
  2. Neue Zeilen einfügen: Rufen Sie für jedes Element in Ihrer Datenliste (mit Ausnahme des ersten Elements, für das die vorhandene Vorlagenzeile wiederverwendet werden kann) InsertTableRowRequest auf, um eine neue Zeile unter der Vorlagenzeile einzufügen.
  3. Zellendaten einfügen:Füllen Sie die Zellen in der Vorlagenzeile aus, indem Sie die Platzhalter ersetzen. Verwenden Sie für die neu erstellten Zeilen InsertTextRequest um den entsprechenden Text an der Koordinatenposition jeder Zelle einzufügen.

Beispiele zum Einfügen von Tabellenzeilen finden Sie unter Mit Tabellen arbeiten.

Option 2: Tag durch eine generierte Tabelle ersetzen

Wenn Sie die Tabelle programmatisch von Grund auf erstellen möchten, gehen Sie so vor:

  1. Platzhalter-Tag einfügen: Verwenden Sie ein einzelnes Tag (z. B. {{invoice-table}}) im Vorlagendokument , um zu kennzeichnen, wo die Liste eingefügt werden soll.
  2. Platzhalter suchen:Verwenden Sie einen Suchvorgang, um den Startindex des Tags zu finden.
  3. Platzhalter löschen: Entfernen Sie mit DeleteContentRangeRequest den Text {{invoice-table}}.
  4. Tabelle einfügen: Senden Sie an diesem Startindex eine InsertTableRequest und geben Sie die Anzahl der Zeilen und Spalten basierend auf Ihrer Datenquelle an.
  5. Werte schreiben:Füllen Sie jede Tabellenzelle nacheinander aus.

Beispiele zum programmatischen Einfügen von Tabellen finden Sie unter Mit Tabellen arbeiten.