Menggabungkan teks menjadi dokumen

Salah satu penerapan Google Docs API yang berguna adalah menggabungkan informasi dari satu atau beberapa sumber data ke dalam dokumen.

Halaman ini menjelaskan cara mengambil data dari sumber eksternal dan memasukkannya ke dalam dokumen template yang ada.

Template adalah jenis dokumen khusus yang berisi teks tetap yang sama untuk semua dokumen yang dibuat dari template tersebut, beserta placeholder yang ditetapkan tempat teks dinamis lainnya dapat ditempatkan. Misalnya, template kontrak mungkin memiliki konten tetap, beserta tempat untuk nama, alamat penerima, dan 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 di aplikasi Anda untuk menyetel tata letak yang dirender.

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

Diagram konseptual penggabungan.

Resep dasar

Berikut ini 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 desain dan format. Format teks apa pun yang ingin Anda ganti akan dipertahankan.

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

  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 mereferensikan dokumen dan dapat berasal dari URL

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

Contoh

Pertimbangkan contoh berikut, yang mengganti 2 kolom dalam template dengan nilai nyata untuk menghasilkan dokumen 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<>();
        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()

Kelola template

Untuk dokumen template yang ditentukan dan dimiliki aplikasi, buat template menggunakan akun khusus yang mewakili aplikasi. Akun layanan adalah pilihan yang bagus dan menghindari masalah dengan kebijakan Google Workspace yang membatasi aktivitas berbagi.

Saat Anda membuat instance dokumen dari template, selalu gunakan kredensial pengguna akhir. Tindakan ini memberi pengguna kontrol penuh atas dokumen yang dihasilkan dan mencegah masalah penskalaan yang terkait dengan batas per pengguna 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 template menggunakan files.copy di Drive API.
  2. Ganti nilai menggunakan documents.androidTest di Docs API.