Menggabungkan teks menjadi dokumen

Panduan ini menjelaskan cara menggunakan Google Dokumen API untuk menggabungkan informasi dari satu atau beberapa sumber data eksternal ke dalam dokumen template yang ada.

Template adalah jenis dokumen yang berisi teks tetap dan placeholder untuk konten dinamis. Misalnya, template kontrak dapat berisi teks tetap dengan tempat penampung untuk nama dan alamat penerima. Kemudian, aplikasi menggabungkan data khusus pengguna ke dalam template untuk membuat dokumen yang sudah selesai.

Ada beberapa alasan mengapa pendekatan ini berguna:

• Desainer dapat menyesuaikan desain dokumen menggunakan Google Dokumen. Cara ini lebih sederhana daripada menyesuaikan parameter di aplikasi Anda untuk menyetel tata letak yang dirender.

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

Gambar 1. Menggabungkan data ke dalam template untuk membuat dokumen.

Cara kerja penggabungan dokumen

Berikut adalah contoh cara menggunakan Docs API untuk menggabungkan data ke dalam dokumen:

1. Buat dokumen Anda menggunakan konten placeholder untuk membantu Anda dalam desain dan format. Format teks yang ingin Anda ganti akan tetap dipertahankan.

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

3. Dalam 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 dapat diperoleh dari URL:

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

Catatan: Anda dapat melakukan beberapa penggantian dalam permintaan batchUpdate yang sama agar lebih efisien. Untuk mengetahui informasi selengkapnya tentang cara mengelompokkan panggilan API, lihat praktik terbaik permintaan batch.

Kelola template

Untuk dokumen template yang ditentukan dan dimiliki oleh aplikasi, buat template menggunakan akun khusus yang mewakili aplikasi. Akun layanan adalah pilihan yang tepat dan menghindari komplikasi 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 terkait batas per pengguna di Google 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 file 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. Mengganti nilai menggunakan documents.batchUpdate di Docs API.

Contoh: Menggabungkan data ke dalam template

Contoh kode berikut menunjukkan cara mengganti dua kolom di semua tab template dengan nilai sebenarnya untuk membuat dokumen yang sudah selesai:

Gambar 2. Mengganti placeholder tag dengan nilai.

Untuk melakukan penggabungan ini, gunakan kode berikut:

Java

String customerName = "Alice";
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy/MM/dd");
String date = formatter.format(LocalDate.now());

// Make a copy of the template document using the Drive API.
String copyTitle = "Merged Document";
File copyMetadata = new File().setName(copyTitle);
File documentCopyFile =
        driveService.files().copy(DOCUMENT_ID, copyMetadata).execute();
String documentCopyId = documentCopyFile.getId();

List 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(documentCopyId, 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,
      },
    },
  ];

  // Make a copy of the template document using the Drive API.
  let copyTitle = 'Merged Document';
  driveService.files.copy({
    fileId: '1yBx6HSnu_gbV2sk1nChJOFo_g3AizBhr-PpkyKAwcTg',
    resource: {
      name: copyTitle,
    },
  }, (err, driveResponse) => {
    if (err) return console.log('The Drive API returned an error: ' + err);
    let documentCopyId = driveResponse.data.id;

    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: documentCopyId,
                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")

# Make a copy of the template document using the Drive API.
copy_title = 'Merged Document'
body = {
    'name': copy_title
}
drive_response = drive_service.files().copy(
    fileId=DOCUMENT_ID, body=body).execute()
document_copy_id = drive_response.get('id')

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_copy_id, body={'requests': requests}).execute()

Catatan: Untuk dokumen dengan beberapa tab, ReplaceAllTextRequest secara default berlaku untuk semua tab. Untuk mengetahui informasi selengkapnya tentang cara menggunakan tab, lihat dokumentasi permintaan.

Menangani daftar dan tabel dinamis

Penggabungan dokumen standar menggunakan ReplaceAllTextRequest untuk mengganti setiap placeholder sekali pakai (seperti {{customer-name}} atau {{date}}). Namun, jika data Anda menyertakan daftar item dinamis (seperti baris dalam invoice, daftar produk yang dipesan, atau tabel dinamis), Anda tidak dapat menggunakan penggantian teks standar karena jumlah item tidak diketahui selama desain template.

Untuk menangani konten daftar dinamis, gunakan salah satu strategi berikut.

Opsi 1: Menambahkan baris ke tabel template

Jika dokumen template Anda sudah berisi tabel yang diformat (misalnya, dengan baris header dan satu baris placeholder), Anda dapat meng-clone dan mengisi baris secara dinamis untuk setiap item dalam daftar:

1. Baca struktur template: Gunakan metode documents.get untuk menemukan tabel dan mengidentifikasi indeks baris template.
2. Menyisipkan baris baru: Untuk setiap item dalam daftar data Anda (kecuali item pertama, yang dapat menggunakan kembali baris template yang ada), panggil InsertTableRowRequest untuk menyisipkan baris baru di bawah baris template.
3. Mengisi data sel: Isi sel di baris template dengan mengganti tempat penampungnya. Untuk baris yang baru dibuat, gunakan InsertTextRequest untuk menyisipkan teks yang sesuai ke lokasi koordinat setiap sel.

Untuk contoh cara menyisipkan baris tabel, lihat Bekerja dengan tabel.

Opsi 2: Mengganti tag dengan tabel yang dibuat

Jika Anda ingin membuat tabel dari awal secara terprogram:

1. Tempatkan tag placeholder: Gunakan satu tag (seperti {{invoice-table}}) dalam dokumen template untuk menandai tempat daftar harus ditempatkan.
2. Temukan placeholder: Gunakan operasi penelusuran untuk menemukan indeks awal tag.
3. Hapus placeholder: Gunakan DeleteContentRangeRequest untuk menghapus teks {{invoice-table}}.
4. Menyisipkan tabel: Kirim InsertTableRequest pada indeks awal tersebut, yang menentukan jumlah baris dan kolom berdasarkan sumber data Anda.
5. Menulis nilai: Isi setiap sel tabel secara berurutan.

Untuk contoh penyisipan tabel secara terprogram, lihat Bekerja dengan tabel.

Topik terkait

• Pembuatan email massal dengan Docs API