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.

Eine Vorlage ist ein spezieller Dokumenttyp, der für alle aus der Vorlage erstellten Dokumente denselben festen Text sowie bestimmte Platzhalter enthält, in die anderer dynamischer Text eingefügt werden kann. Eine Vertragsvorlage kann beispielsweise einen 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.

Dieser Ansatz ist aus mehreren Gründen nützlich:

  • Mit dem Google Docs-Editor können Designer das Design eines Dokuments ganz einfach optimieren. Das ist viel einfacher als die Parameter in Ihrer App zu optimieren, um das gerenderte Layout festzulegen.

  • Die Trennung von Inhalt und Präsentation ist ein bekanntes Designprinzip mit vielen Vorteilen.

Konzeptionelles Diagramm einer Zusammenführung.

Ein einfaches Rezept

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 Platzhaltern, um das Design und das Format zu planen. Die Textformatierung, die Sie ersetzen möchten, bleibt erhalten.

  2. Ersetzen Sie für jedes Element, das Sie einfügen, den Platzhalterinhalt durch ein Tag. Verwenden Sie Strings, die normalerweise nicht vorkommen. {{account-holder-name}} könnte beispielsweise ein geeignetes Tag sein.

  3. Erstellen Sie in Ihrem Code mit der Google Drive API eine Kopie des Dokuments.

  4. Verwenden Sie in Ihrem Code die Methode batchUpdate() der Docs API mit dem Dokumentnamen und fügen Sie ein ReplaceAllTextRequest ein.

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

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

Beispiel

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

Sie können den folgenden Code verwenden, um diese Zusammenführung durchzuführen.

Java

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

List<Request> 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(documentId, 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()

Vorlagen verwalten

Erstellen Sie Vorlagendokumente, die von der Anwendung definiert und ihr gehören, mit einem speziellen Konto, das die Anwendung darstellt. Dienstkonten sind eine gute Wahl und Sie vermeiden damit Komplikationen mit Google Workspace-Richtlinien, die die Freigabe einschränken.

Verwenden Sie beim Erstellen von Dokumentinstanzen aus Vorlagen immer Anmeldedaten von Endnutzern. So haben Nutzer die volle Kontrolle über das resultierende Dokument und es treten keine Skalierungsprobleme aufgrund von Limits pro Nutzer in Drive auf.

Wenn Sie eine Vorlage mit einem Dienstkonto erstellen möchten, führen Sie die folgenden Schritte mit den Anmeldedaten der Anwendung aus:

  1. Erstellen Sie ein Dokument mit documents.create in der Docs API.
  2. Aktualisieren Sie die Berechtigungen, damit die Empfänger des Dokuments es lesen können, indem Sie permissions.create in der Drive API verwenden.
  3. Aktualisieren Sie die Berechtigungen, damit Vorlagenautoren mithilfe von permissions.create in der Drive API darauf schreiben können.
  4. Bearbeiten Sie die Vorlage nach Bedarf.

Führen Sie die folgenden Schritte mit den Nutzeranmeldedaten aus, um eine Instanz des Dokuments zu erstellen:

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