Scalanie tekstu w dokument

Jednym z przydatnych zastosowań interfejsu Google Docs API jest scalanie informacji z co najmniej 2 źródeł danych w dokument.

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

Szablon to specjalny typ dokumentu zawierającego ten sam stały tekst w przypadku wszystkich dokumentów utworzonych na podstawie szablonu, a także wyznaczone miejsca zastępcze, w których można umieścić inny tekst dynamiczny. Szablon umowy może na przykład zawierać stały tekst oraz miejsca na imię i nazwisko odbiorcy, adres i inne dane. Następnie aplikacja może scalić dane klienta z szablonem, aby utworzyć gotowe dokumenty.

Jest kilka powodów, dla których to podejście jest przydatne:

  • Projektanci mogą łatwo dostosować wygląd dokumentu za pomocą edytora Dokumentów Google. Jest to znacznie łatwiejsze niż dostosowanie parametrów w aplikacji w celu ustawienia renderowanego układu.

  • Oddzielenie treści od prezentacji to znana zasada projektowania, która niesie ze sobą wiele korzyści.

Schemat koncepcyjny scalania.

Podstawowy przepis

Oto przykład użycia interfejsu Docs API do scalania danych w dokumencie:

  1. Utwórz dokument, korzystając z treści zastępczych, które ułatwią Ci projektowanie i formatowanie. Zachowane jest formatowanie tekstu, który chcesz zastąpić.

  2. W przypadku każdego elementu, który chcesz wstawić, zastąp zawartość zastępczą tagiem. Używaj ciągów znaków, które rzadko występują w normalnych warunkach. Na przykład tag {{account-holder-name}} może być dobrym tagiem.

  3. W kodzie użyj interfejsu Google Drive API, aby utworzyć kopię dokumentu.

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

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

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

Przykład

Rozważ ten przykład, w którym 2 pola we wszystkich kartach szablonu są zastępowane rzeczywistymi wartościami, aby wygenerować gotowy dokument.

Aby przeprowadzić takie 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<>();
// 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()

Zarządzaj szablonami

W przypadku dokumentów szablonowych zdefiniowanych i zarządzanych przez aplikację utwórz szablon za pomocą dedykowanego konta reprezentującego aplikację. Konta usługi to dobry wybór, który pozwala uniknąć komplikacji związanych z zasadami Google Workspace ograniczającymi udostępnianie.

Podczas tworzenia instancji dokumentów na podstawie szablonów zawsze używaj danych logowania użytkownika końcowego. Daje to użytkownikom pełną kontrolę nad powstałym dokumentem 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, korzystając z kwalifikacji aplikacji:

  1. Utwórz dokument za pomocą wywołania documents.create w interfejsie Docs API.
  2. Zaktualizuj uprawnienia, aby umożliwić odbiorcom dokumentu odczyt za pomocą interfejsu permissions.create w interfejsie Drive API.
  3. Zaktualizuj uprawnienia, aby autorzy szablonów mogli je modyfikować za pomocą funkcji permissions.create w interfejsie Drive API.
  4. W razie potrzeby zmodyfikuj szablon.

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

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