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.
Podstawowy przepis
Oto przykład użycia interfejsu API Dokumentów do scalenia danych w dokument:
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.
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}}
.Utwórz kopię dokumentu za pomocą interfejsu Google Drive API.
W kodzie użyj metody
batchUpdate()
interfejsu Docs API z nazwą dokumentu i dodajReplaceAllTextRequest
.
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:
- Utwórz dokument, korzystając z metody documents.create w interfejsie Docs API.
- Zaktualizuj uprawnienia, aby odbiorcy dokumentu mogli je odczytywać, korzystając z metody permissions.create w interfejsie Drive API.
- Zaktualizuj uprawnienia, aby umożliwić autorom szablonu zapisywanie w nim za pomocą metody permissions.create w interfejsie Drive API.
- Zmodyfikuj szablon.
Aby utworzyć instancję dokumentu, wykonaj te czynności z użyciem danych logowania użytkownika:
- Utwórz kopię szablonu, korzystając z pliku files.copy w interfejsie Drive API.
- Zastąp wartości za pomocą polecenia documents.batchUpdate w interfejsie Docs API.