Menggabungkan teks menjadi dokumen

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

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

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

Ada beberapa alasan mengapa pendekatan ini berguna:

• Desainer dapat dengan mudah menyesuaikan desain dokumen menggunakan editor Google Dokumen. Cara ini jauh lebih mudah daripada menyesuaikan parameter di aplikasi Anda untuk menetapkan tata letak yang dirender.

• Memisahkan konten dari presentasi adalah prinsip desain yang dikenal luas dan memiliki banyak manfaat.

Resep dasar

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

1. Buat dokumen menggunakan konten placeholder untuk membantu Anda dengan desain dan format. Semua format teks yang ingin Anda ganti akan dipertahankan.

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

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

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

Contoh

Pertimbangkan contoh berikut, yang mengganti 2 kolom di semua tab template dengan nilai sebenarnya untuk menghasilkan dokumen yang sudah selesai.

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

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

  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);
            });
      });

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 oleh aplikasi, buat template menggunakan akun khusus yang mewakili aplikasi. Akun layanan merupakan pilihan yang baik dan menghindari komplikasi dengan kebijakan Google Workspace yang membatasi 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.batchUpdate di Docs API.