Text in einem Dokument zusammenführen

Eine nützliche Anwendung der Google Docs API ist das Zusammenführen von Informationen aus einer oder mehreren Datenquellen in einem Dokument.

Auf dieser Seite wird beschrieben, wie Sie Daten aus einer externen Quelle in ein vorhandenes Vorlagendokument einfügen können.

Eine Vorlage ist ein spezieller Dokumenttyp, der für alle aus der Vorlage erstellten Dokumente denselben festen Text sowie bestimmte Platzhalter enthält, an denen anderer dynamischer Text platziert werden kann. Eine Vertragsvorlage kann beispielsweise festen Inhalt sowie Felder für den Namen, die Adresse und andere Details des Empfängers enthalten. Ihre App kann dann kundenspezifische Daten in die Vorlage einfügen, um fertige Dokumente zu erstellen.

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

• Designer können das Design eines Dokuments ganz einfach mit dem Google Docs-Editor optimieren. Das ist viel 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.

Grundrezept

Hier ein Beispiel dafür, 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 die Formatierung zu erleichtern. 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. Ein gutes Tag wäre beispielsweise {{account-holder-name}}.

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

Sie können mehrere Ersetzungen in derselben BatchUpdate-Anfrage ausführen, um die Effizienz zu steigern. Unter Best Practices für Batchanfragen erfahren Sie, wie Sie API-Aufrufe zusammenfassen.

Beispiel

Im folgenden Beispiel werden zwei Felder auf allen Tabs einer Vorlage durch echte Werte ersetzt, um ein fertiges Dokument zu erstellen.

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());

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(DOCUMENT_ID, 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,
      },
    },
  ];

  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: '1yBx6HSnu_gbV2sk1nChJOFo_g3AizBhr-PpkyKAwcTg',
              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")

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_ID, body={'requests': requests}).execute()

Hinweis: Bei Dokumenten mit mehreren Tabs, ReplaceAllTextRequest wird standardmäßig auf alle Tabs angewendet. Weitere Informationen zum Arbeiten mit Tabs finden Sie in der Anfragedokumentation.

Vorlagen verwalten

Erstellen Sie für Vorlagendokumente, die von der Anwendung definiert und im Besitz der Anwendung sind, die Vorlage mit einem speziellen Konto, das die Anwendung repräsentiert. Dienstkonten 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 Anmeldedaten der Anwendung:

1. Erstellen Sie ein Dokument mit documents.create in der Docs API.
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 darauf 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.