Scalanie tekstu w dokument

Przydatnym zastosowaniem interfejsu API Dokumentów Google jest scalanie w dokument informacji z jednego lub większej liczby źródeł danych.

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

Szablon to specjalny typ dokumentu, który zawiera ten sam stały tekst we wszystkich dokumentach utworzonych na podstawie szablonu oraz wyznaczone obiekty zastępcze, w których można umieścić inny tekst dynamiczny. Na przykład szablon umowy może zawierać stałe treści oraz miejsca z imieniem i nazwiskiem, adresem odbiorcy oraz innymi informacjami. Aplikacja może następnie scalać dane dotyczące klientów w szablonie, aby tworzyć gotowe dokumenty.

Takie podejście jest przydatne z kilku powodów:

• Projektanci mogą z łatwością dopracować projekt dokumentu za pomocą edytora Dokumentów Google. To znacznie łatwiejsze niż dostrajanie parametrów w aplikacji, aby ustawić wyrenderowany układ.

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

Podstawowy przepis

Oto przykład, jak można skorzystać z interfejsu API Dokumentów do scalenia danych w dokument:

1. Utwórz dokument, używając treści zastępczej, która pomoże Ci dobrać odpowiedni projekt i format. Formatowanie tekstu, które chcesz zastąpić, zostanie zachowane.

2. Zastąp zawartość zastępczą tagiem dla każdego wstawianego elementu. Pamiętaj, by użyć ciągów znaków, które prawdopodobnie nie wystąpią prawidłowo. Dobrym tagiem może być na przykład {{account-holder-name}}.

3. Aby utworzyć kopię dokumentu, w swoim kodzie użyj interfejsu Google Drive API.

4. W swoim kodzie użyj metody batchUpdate() interfejsu API Dokumentów, podając nazwę dokumentu i dołącz znak ReplaceAllTextRequest.

Identyfikatory dokumentów odwołują się do dokumentu i można je pobrać na podstawie adresu URL.

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

Przykład

Przyjrzyjmy się przykładowi, w którym 2 pola w szablonie są zastąpione prawdziwymi wartościami w celu wygenerowania gotowego dokumentu.

Aby to zrobić, możesz użyć poniższego kodu.

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

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

    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 przez aplikację i należących do niej utwórz szablon za pomocą dedykowanego konta reprezentującego aplikację. Dobrym wyborem są konta usługi. Pozwalają one uniknąć komplikacji z zasadami Google Workspace, które ograniczają udostępnianie.

Gdy tworzysz instancje dokumentów na podstawie szablonów, zawsze używaj danych logowania użytkownika. Zapewnia to użytkownikom pełną kontrolę nad dokumentem wynikowym i zapobiega problemom ze skalowaniem związanym z limitami na użytkownika na Dysku.

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

1. Utwórz dokument za pomocą polecenia documents.create w interfejsie API Dokumentów.
2. Zaktualizuj uprawnienia, aby adresaci dokumentu mogli go odczytać za pomocą polecenia permissions.create w interfejsie Drive API.
3. Zaktualizuj uprawnienia, aby umożliwić autorom szablonu zapisywanie w nim za pomocą polecenia permissions.create w interfejsie Drive API.
4. W razie potrzeby zmodyfikuj szablon.

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

1. Utwórz kopię szablonu za pomocą polecenia files.copy w interfejsie Drive API.
2. Zastąp wartości za pomocą polecenia documents.batchUpdate w interfejsie API Dokumentów.