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 übernehmen und in ein vorhandenes Vorlagendokument einfügen können.

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

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

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

  • Die Trennung von Inhalt und Darstellung ist ein bekanntes Designprinzip mit vielen Vorteilen.

Konzeptionelles Diagramm einer Zusammenführung.

Ein einfaches Rezept

Hier sehen Sie 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 Element, das Sie einfügen, den Platzhalterinhalt durch ein Tag. Verwenden Sie Strings, die normalerweise nicht vorkommen. {{account-holder-name}} ist beispielsweise ein guter 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 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 tatsächliche Werte ersetzt, um ein fertiges Dokument zu generieren.

Sie können den folgenden Code verwenden, um diesen Vorgang auszufü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 für Vorlagendokumente, die von der Anwendung definiert und ihr gehören, 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 Endnutzeranmeldedaten. So haben Nutzer die volle Kontrolle über das resultierende Dokument und es werden Skalierungsprobleme im Zusammenhang mit nutzerspezifischen Limits in Drive vermieden.

So erstellen Sie eine Vorlage mit einem Dienstkonto:

  1. Erstellen Sie ein Dokument mit documents.create in der Docs API.
  2. Aktualisieren Sie die Berechtigungen, damit die Dokumentempfänger das Dokument 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.