Menggabungkan teks menjadi dokumen

Salah satu aplikasi Google Docs API yang berguna adalah menggabungkan informasi dari satu atau lebih banyak sumber data ke dalam dokumen.

Laman ini menjelaskan bagaimana Anda dapat mengambil data dari sumber eksternal dan menyisipkannya ke dalam dokumen {i>template<i} yang sudah ada.

Template adalah jenis dokumen khusus yang berisi teks tetap yang sama untuk semua dokumen yang dibuat dari template, beserta placeholder yang ditentukan di mana teks dinamis lainnya dapat ditempatkan. Misalnya, template kontrak mungkin memiliki konten tetap, bersama dengan tempat untuk nama, alamat, dan penerima detail lainnya. Aplikasi Anda kemudian dapat menggabungkan data khusus pelanggan ke dalam template untuk membuat dokumen yang sudah jadi.

Ada beberapa alasan mengapa pendekatan ini berguna:

  • Sangat mudah bagi desainer untuk menyempurnakan desain dokumen menggunakan editor Google Dokumen. Ini jauh lebih mudah daripada menyesuaikan parameter aplikasi Anda untuk mengatur tata letak yang dirender.

  • Memisahkan konten dari presentasi adalah desain yang sudah dikenal prinsip dengan banyak manfaat.

Diagram konseptual penggabungan.

Resep dasar

Berikut contoh bagaimana Anda dapat menggunakan Docs API untuk menggabungkan data ke dalam dokumen:

  1. Buat dokumen Anda menggunakan konten {i>placeholder<i} untuk membantu Anda dalam hal desain dan format. Pemformatan teks apa pun yang ingin Anda ganti akan dipertahankan.

  2. Untuk setiap elemen yang akan Anda sisipkan, ganti konten {i>placeholder<i} dengan . Pastikan untuk menggunakan string yang cenderung tidak muncul secara normal. Misalnya, {{account-holder-name}} mungkin adalah tag yang bagus.

  3. Di kode Anda, gunakan Google Drive API untuk membuat salinan dokumen.

  4. Dalam kode Anda, gunakan metode batchUpdate() Docs API dengan nama dokumen dan sertakan ReplaceAllTextRequest

ID dokumen merujuk ke dokumen dan bisa diambil dari URL

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

Contoh

Perhatikan contoh berikut, yang menggantikan 2 kolom di semua tab {i>template<i} dengan nilai nyata untuk menghasilkan dokumen yang sudah jadi.

Untuk melakukan penggabungan ini, Anda dapat menggunakan kode di bawah.

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

Kelola template

Untuk dokumen template yang ditentukan dan dimiliki aplikasi, buat {i>template<i} menggunakan akun khusus yang mewakili aplikasi. Akun layanan adalah pilihan yang baik dan menghindari masalah dengan kebijakan Google Workspace yang membatasi berbagi.

Saat Anda membuat instance dokumen dari template, selalu gunakan kredensial pengguna akhir. Hal ini memberi pengguna kontrol penuh atas dokumen yang dihasilkan dan mencegah masalah penskalaan yang terkait dengan per pengguna batasan data di Drive.

Untuk membuat template menggunakan akun layanan, lakukan langkah-langkah berikut dengan kredensial aplikasi:

  1. Buat dokumen menggunakan documents.create di Docs API.
  2. Perbarui izin untuk mengizinkan penerima dokumen membacanya menggunakan permissions.create di Drive API.
  3. Perbarui izin untuk mengizinkan penulis template menulis ke template tersebut menggunakan permissions.create di Drive API.
  4. Edit template sesuai kebutuhan.

Untuk membuat instance dokumen, lakukan langkah-langkah berikut dengan kredensial pengguna:

  1. Buat salinan {i>template<i} menggunakan files.copy di Drive API.
  2. Ganti nilai menggunakan documents.batchUpdate di Docs API.