Scalanie tekstu w dokument

Interfejsu API Dokumentów Google może być scalanie informacji z jednego lub kilku źródeł danych w jeden dokument.

Na tej stronie opisujemy, jak pobrać dane z zewnętrznego źródła i wstawić je do istniejącego szablonu dokumentu.

Szablon to specjalny typ dokumentu, który zawiera ten sam stały tekst we wszystkich dokumentach utworzonych na jego podstawie, a także wyznaczone obiekty zastępcze umożliwiające umieszczenie innego tekstu dynamicznego. Na przykład szablon umowy może zawierać stałą treść wraz z miejscami na imię i nazwisko odbiorcy, jego adres oraz inne informacje. Aplikacja może następnie scalić z szablonem dane dotyczące klienta, aby utworzyć gotowe dokumenty.

Ta metoda jest przydatna z kilku powodów:

  • Projektanci mogą w łatwy sposób dostosowywać projekt dokumentów za pomocą edytora Dokumentów Google. To znacznie łatwiejsze niż dostrajanie parametrów w aplikacji, aby ustawić renderowany układ.

  • Oddzielenie treści od prezentacji to powszechnie znana zasada projektowania, która ma wiele zalet.

Schemat koncepcyjny scalania.

Podstawowy przepis

Oto przykład użycia interfejsu API Dokumentów do scalenia danych w dokument:

  1. Utwórz dokument z użyciem treści zastępczych, aby ułatwić projektowanie i format. Formatowanie tekstu, które chcesz zastąpić, zostanie zachowane.

  2. W przypadku każdego wstawianego elementu zastąp treść symbolu zastępczego tagiem. Pamiętaj, by używać ciągów znaków, które rzadko występują. Dobrym tagiem może być np. {{account-holder-name}}.

  3. Utwórz kopię dokumentu za pomocą interfejsu Google Drive API.

  4. W kodzie użyj metody batchUpdate() interfejsu Docs API z nazwą dokumentu i dodaj ReplaceAllTextRequest.

Identyfikatory dokumentów odwołują się do dokumentów i mogą pochodzić z adresu URL

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

Przykład

Rozważmy przykład poniżej. W celu wygenerowania gotowego dokumentu 2 pola w szablonie zostaną zastąpione rzeczywistymi wartościami.

Aby przeprowadzić scalanie, możesz użyć poniższego kodu.

Java

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

        List<Request> requests = new ArrayList<>();
        requests.add(new Request()
                .setReplaceAllText(new ReplaceAllTextRequest()
                        .setContainsText(new SubstringMatchCriteria()
                                .setText("{{customer-name}}")
                                .setMatchCase(true))
                        .setReplaceText(customerName)));
        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 = [
    {
      replaceAllText: {
        containsText: {
          text: '{{customer-name}}',
          matchCase: true,
        },
        replaceText: customerName,
      },
    },
    {
      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 = [
         {
            'replaceAllText': {
                'containsText': {
                    'text': '{{customer-name}}',
                    'matchCase':  'true'
                },
                'replaceText': customer_name,
            }}, {
            'replaceAllText': {
                'containsText': {
                    'text': '{{date}}',
                    'matchCase':  'true'
                },
                'replaceText': str(date),
            }
        }
    ]

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

Zarządzaj szablonami

W przypadku dokumentów szablonów zdefiniowanych i należących do aplikacji utwórz szablon za pomocą dedykowanego konta reprezentującego aplikację. Konta usługi to dobry wybór. Uniknij komplikacji związanych z zasadami Google Workspace, które ograniczają udostępnianie.

Podczas tworzenia instancji dokumentów na podstawie szablonów zawsze używaj danych logowania użytkownika. Daje to użytkownikom pełną kontrolę nad wynikowym dokumentem i zapobiega problemom ze skalowaniem związanych z limitami na Dysku poszczególnych użytkowników.

Aby utworzyć szablon za pomocą konta usługi, wykonaj te czynności z danymi logowania do aplikacji:

  1. Utwórz dokument, korzystając z metody documents.create w interfejsie Docs API.
  2. Zaktualizuj uprawnienia, aby odbiorcy dokumentu mogli je odczytywać, korzystając z metody permissions.create w interfejsie Drive API.
  3. Zaktualizuj uprawnienia, aby umożliwić autorom szablonu zapisywanie w nim za pomocą metody permissions.create w interfejsie Drive API.
  4. Zmodyfikuj szablon.

Aby utworzyć instancję dokumentu, wykonaj te czynności z użyciem danych logowania użytkownika:

  1. Utwórz kopię szablonu, korzystając z pliku files.copy w interfejsie Drive API.
  2. Zastąp wartości za pomocą polecenia documents.batchUpdate w interfejsie Docs API.