Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.
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 untuk menetapkan tata letak yang dirender.
Memisahkan konten dari presentasi adalah prinsip desain yang sudah dikenal dengan banyak manfaat.
Resep dasar
Berikut adalah contoh cara menggunakan Docs API untuk menggabungkan data ke dalam dokumen:
Buat dokumen menggunakan konten placeholder untuk membantu Anda dengan desain dan format. Semua format teks yang ingin Anda ganti akan dipertahankan.
Untuk setiap elemen yang akan disisipkan, ganti konten placeholder dengan tag. Pastikan untuk menggunakan string yang tidak mungkin terjadi secara normal. Misalnya, {{account-holder-name}} mungkin merupakan tag yang baik.
Dalam kode Anda, gunakan Google Drive API untuk membuat salinan dokumen.
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.
Java
StringcustomerName="Alice";DateTimeFormatterformatter=DateTimeFormatter.ofPattern("yyyy/MM/dd");Stringdate=formatter.format(LocalDate.now());List<Request>requests=newArrayList<>();// One option for replacing all text is to specify all tab IDs.requests.add(newRequest().setReplaceAllText(newReplaceAllTextRequest().setContainsText(newSubstringMatchCriteria().setText("{{customer-name}}").setMatchCase(true)).setReplaceText(customerName).setTabsCriteria(newTabsCriteria().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(newRequest().setReplaceAllText(newReplaceAllTextRequest().setContainsText(newSubstringMatchCriteria().setText("{{date}}").setMatchCase(true)).setReplaceText(date)));BatchUpdateDocumentRequestbody=newBatchUpdateDocumentRequest();service.documents().batchUpdate(documentId,body.setRequests(requests)).execute();
Node.js
letcustomerName='Alice';letdate=yyyymmdd()letrequests=[// 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)returnconsole.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 template menggunakan akun khusus yang mewakili aplikasi. Akun layanan adalah 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. Hal 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:
[[["Mudah dipahami","easyToUnderstand","thumb-up"],["Memecahkan masalah saya","solvedMyProblem","thumb-up"],["Lainnya","otherUp","thumb-up"]],[["Informasi yang saya butuhkan tidak ada","missingTheInformationINeed","thumb-down"],["Terlalu rumit/langkahnya terlalu banyak","tooComplicatedTooManySteps","thumb-down"],["Sudah usang","outOfDate","thumb-down"],["Masalah terjemahan","translationIssue","thumb-down"],["Masalah kode / contoh","samplesCodeIssue","thumb-down"],["Lainnya","otherDown","thumb-down"]],["Terakhir diperbarui pada 2025-08-01 UTC."],[],[],null,["One useful application of the Google Docs API is to merge information from one\nor more data sources into a document.\n\nThis page outlines how you can take data from an external source and insert it\ninto an existing template document.\n\nA *template* is a special type of document containing the same fixed text for\nall documents created from the template, along with designated placeholders\nwhere other dynamic text can be placed. For example, a contract template might\nhave fixed content, along with spots for the receiver's name, address, and other\ndetails. Your app can then merge customer-specific data into the template to\ncreate finished documents.\n\nThere are several reasons why this approach is useful:\n\n- It's easy for designers to fine-tune a document's design using the\n Google Docs editor. This is much easier than tuning parameters in your app\n to set the rendered layout.\n\n- Separating content from presentation is a well-known design principle with\n many benefits.\n\nA basic recipe\n\nHere's an example of how you can use the Docs API to merge data into a\ndocument:\n\n1. Create your document using placeholder content to help you with the design\n and format. Any text formatting you want to replace is preserved.\n\n2. For each element you'll be inserting, replace the placeholder content with a\n tag. Be sure to use strings that are unlikely to occur normally. For\n example,\n `{{account-holder-name}}` might be a good tag.\n\n3. In your code, use the Google Drive API to make a copy of the document.\n\n4. In your code, use the Docs API's\n [`batchUpdate()`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate)\n method with the document name and include a\n [`ReplaceAllTextRequest`](/workspace/docs/api/reference/rest/v1/documents/request#replacealltextrequest).\n\nDocument IDs reference a document and they can be derived from the URL \n\n```\nhttps://docs.google.com/document/d/documentId/edit\n```\n| You can perform multiple replacements in the same BatchUpdate request for efficiency. See [batch request best practices](/workspace/docs/api/how-tos/batch) for how to batch API calls together\n\nExample\n\nConsider the following example, which replaces 2 fields across all tabs of a\ntemplate with real values to generate a finished document.\n\nTo perform this merge, you can use the code below. \n\nJava \n\n```java\nString customerName = \"Alice\";\nDateTimeFormatter formatter = DateTimeFormatter.ofPattern(\"yyyy/MM/dd\");\nString date = formatter.format(LocalDate.now());\n\nList\u003cRequest\u003e requests = new ArrayList\u003c\u003e();\n// One option for replacing all text is to specify all tab IDs.\nrequests.add(new Request()\n .setReplaceAllText(new ReplaceAllTextRequest()\n .setContainsText(new SubstringMatchCriteria()\n .setText(\"{{customer-name}}\")\n .setMatchCase(true))\n .setReplaceText(customerName)\n .setTabsCriteria(new TabsCriteria()\n .addTabIds(TAB_ID_1)\n .addTabIds(TAB_ID_2)\n .addTabIds(TAB_ID_3))));\n// Another option is to omit TabsCriteria if you are replacing across all tabs.\nrequests.add(new Request()\n .setReplaceAllText(new ReplaceAllTextRequest()\n .setContainsText(new SubstringMatchCriteria()\n .setText(\"{{date}}\")\n .setMatchCase(true))\n .setReplaceText(date)));\n\nBatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest();\nservice.documents().batchUpdate(documentId, body.setRequests(requests)).execute();\n```\n\nNode.js \n\n```javascript\n let customerName = 'Alice';\n let date = yyyymmdd()\n let requests = [\n // One option for replacing all text is to specify all tab IDs.\n {\n replaceAllText: {\n containsText: {\n text: '{{customer-name}}',\n matchCase: true,\n },\n replaceText: customerName,\n tabsCriteria: {\n tabIds: [TAB_ID_1, TAB_ID_2, TAB_ID_3],\n },\n },\n },\n // Another option is to omit TabsCriteria if you are replacing across all tabs.\n {\n replaceAllText: {\n containsText: {\n text: '{{date}}',\n matchCase: true,\n },\n replaceText: date,\n },\n },\n ];\n\n google.options({auth: auth});\n google\n .discoverAPI(\n 'https://docs.googleapis.com/$discovery/rest?version=v1&key={YOUR_API_KEY}')\n .then(function(docs) {\n docs.documents.batchUpdate(\n {\n documentId: '1yBx6HSnu_gbV2sk1nChJOFo_g3AizBhr-PpkyKAwcTg',\n resource: {\n requests,\n },\n },\n (err, {data}) =\u003e {\n if (err) return console.log('The API returned an error: ' + err);\n console.log(data);\n });\n });\n```\n\nPython \n\n```python\ncustomer_name = 'Alice'\ndate = datetime.datetime.now().strftime(\"%y/%m/%d\")\n\nrequests = [\n # One option for replacing all text is to specify all tab IDs.\n {\n 'replaceAllText': {\n 'containsText': {\n 'text': '{{customer-name}}',\n 'matchCase': 'true'\n },\n 'replaceText': customer_name,\n 'tabsCriteria': {\n 'tabIds': [TAB_ID_1, TAB_ID_2, TAB_ID_3],\n },\n }},\n # Another option is to omit TabsCriteria if you are replacing across all tabs.\n {\n 'replaceAllText': {\n 'containsText': {\n 'text': '{{date}}',\n 'matchCase': 'true'\n },\n 'replaceText': str(date),\n }\n }\n]\n\nresult = service.documents().batchUpdate(\n documentId=document_id, body={'requests': requests}).execute()\n```\n| **Note:** For documents with multiple [tabs](/workspace/docs/api/how-tos/tabs), [`ReplaceAllTextRequest`](/workspace/docs/api/reference/rest/v1/documents/request#replacealltextrequest) by default applies to all tabs. See the request documentation for more information about how to work with tabs.\n\nManage templates\n\nFor template documents the application defines and owns, create\nthe template using a dedicated account representing the application.\n[Service accounts](/identity/protocols/application-default-credentials)\nare a good choice and avoid complications with Google Workspace policies that\nrestrict sharing.\n\nWhen you create instances of documents from templates, always use\nend-user credentials. This gives users full control over the\nresulting document and prevents scaling issues related to per-user\nlimits in Drive.\n\nTo create a template using a service account, perform the following steps with\nthe application credentials:\n\n1. Create a document using [documents.create](/workspace/docs/api/reference/rest/v1/documents/create) in the Docs API.\n2. Update the permissions to allow the document recipients to read it using [permissions.create](/workspace/drive/api/v3/reference/permissions/create) in the Drive API.\n3. Update the permissions to allow template authors to write to it using [permissions.create](/workspace/drive/api/v3/reference/permissions/create) in the Drive API.\n4. Edit the template as required.\n\nTo create an instance of the document, perform the following steps with the user\ncredentials:\n\n1. Create a copy of the template using [files.copy](/workspace/drive/v3/reference/files/copy) in the Drive API.\n2. Replace values using [documents.batchUpdate](/workspace/docs/api/reference/rest/v1/documents/batchUpdate) in the Docs API."]]
