ผสานข้อความลงในเอกสาร

คู่มือนี้อธิบายวิธีใช้ Google Docs API เพื่อผสานข้อมูลจากแหล่งข้อมูลภายนอกอย่างน้อย 1 แหล่งลงในเอกสารเทมเพลตที่มีอยู่

เทมเพลตคือเอกสารประเภทหนึ่งที่มีข้อความคงที่และตัวยึดตำแหน่งสำหรับเนื้อหาแบบไดนามิก ตัวอย่างเช่น เทมเพลตสัญญาอาจมีข้อความคงที่พร้อมตัวยึดตำแหน่งสำหรับชื่อและที่อยู่ของผู้รับ จากนั้นแอปจะผสานข้อมูลเฉพาะของผู้ใช้ลงในเทมเพลตเพื่อสร้างเอกสารที่เสร็จสมบูรณ์

แนวทางนี้มีประโยชน์ด้วยเหตุผลหลายประการ ดังนี้

  • นักออกแบบสามารถปรับแต่งการออกแบบเอกสารโดยใช้ Google เอกสาร ซึ่งทำได้ง่ายกว่าการปรับพารามิเตอร์ในแอปเพื่อตั้งค่าเลย์เอาต์ที่แสดง

  • การแยกเนื้อหาออกจากงานนำเสนอเป็นหลักการออกแบบที่รู้จักกันดีซึ่งมีประโยชน์มากมาย

แผนภาพแสดงวิธีผสานข้อมูลจากแหล่งที่มาลงในเทมเพลตเพื่อ สร้างเอกสาร
รูปที่ 1 การผสานข้อมูลลงในเทมเพลตเพื่อสร้างเอกสาร

วิธีทำงานของการผสานเอกสาร

ตัวอย่างวิธีใช้ Docs API เพื่อผสานข้อมูลลงในเอกสาร

  1. สร้างเอกสารโดยใช้เนื้อหาตัวยึดตำแหน่งเพื่อช่วยในการออกแบบและจัดรูปแบบ ระบบจะเก็บการจัดรูปแบบข้อความที่คุณต้องการแทนที่ไว้

  2. สำหรับองค์ประกอบแต่ละรายการที่คุณจะแทรก ให้แทนที่เนื้อหาตัวยึดตำแหน่งด้วยแท็ก ตรวจสอบว่าใช้สตริงที่ไม่มีแนวโน้มที่จะเกิดขึ้นตามปกติ ตัวอย่างเช่น {{account-holder-name}} อาจเป็นแท็กที่ดี

  3. ใช้ Google Drive API ในโค้ดเพื่อทำสำเนาเอกสาร

  4. ใช้เมธอด batchUpdate ของ Docs API กับชื่อเอกสารในโค้ดและใส่ ReplaceAllTextRequest

รหัสเอกสารจะอ้างอิงเอกสารและสามารถได้มาจาก URL ดังนี้

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

จัดการเทมเพลต

สำหรับเอกสารเทมเพลตที่แอปกำหนดและเป็นเจ้าของ ให้สร้างเทมเพลตโดยใช้บัญชี เฉพาะที่แสดงถึงแอป บัญชี บริการเป็นตัวเลือกที่ดี และหลีกเลี่ยงความซับซ้อนของนโยบาย Google Workspace ที่จำกัดการแชร์

เมื่อสร้างอินสแตนซ์ของเอกสารจากเทมเพลต ให้ใช้ข้อมูลเข้าสู่ระบบของผู้ใช้ปลายทางเสมอ วิธีนี้ช่วยให้ผู้ใช้ควบคุมเอกสารที่ได้ได้อย่างเต็มที่และป้องกันปัญหาการปรับขนาดที่เกี่ยวข้องกับขีดจำกัดต่อผู้ใช้ใน Google ไดรฟ์

หากต้องการสร้างเทมเพลตโดยใช้บัญชีบริการ ให้ทำตามขั้นตอนต่อไปนี้ด้วยข้อมูลเข้าสู่ระบบของแอป

  1. สร้างเอกสารโดยใช้ documents.create ใน Docs API
  2. อัปเดตสิทธิ์เพื่อให้ผู้รับเอกสารอ่านเอกสารได้โดยใช้ permissions.create ใน Drive API
  3. อัปเดตสิทธิ์เพื่อให้ผู้เขียนเทมเพลตเขียนเอกสารได้โดยใช้ permissions.create ใน Drive API
  4. แก้ไขเทมเพลตตามต้องการ

หากต้องการสร้างอินสแตนซ์ของเอกสาร ให้ทำตามขั้นตอนต่อไปนี้ด้วยข้อมูลเข้าสู่ระบบของผู้ใช้

  1. สร้างสำเนาเทมเพลตโดยใช้ files.copyใน Drive API
  2. แทนที่ค่าโดยใช้ documents.batchUpdate ใน Docs API

ตัวอย่าง: ผสานข้อมูลลงในเทมเพลต

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีแทนที่ 2 ฟิลด์ในทุกแท็บของเทมเพลตด้วยค่าจริงเพื่อสร้างเอกสารที่เสร็จสมบูรณ์

รูปภาพแสดงเทมเพลตเอกสารที่มีตัวยึดตำแหน่งแท็กและเอกสารที่ผสานแล้ว
รูปที่ 2 การแทนที่ตัวยึดตำแหน่งแท็กด้วยค่า

หากต้องการทำการผสานนี้ ให้ใช้โค้ดต่อไปนี้

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

จัดการรายการและตารางแบบไดนามิก

การผสานเอกสารมาตรฐานจะใช้ ReplaceAllTextRequest เพื่อแทนที่ตัวยึดตำแหน่งแบบครั้งเดียว (เช่น {{customer-name}} หรือ {{date}}) แต่หากข้อมูลมีรายการแบบไดนามิก (เช่น บรรทัดในใบแจ้งหนี้ รายการผลิตภัณฑ์ที่สั่งซื้อ หรือตารางแบบไดนามิก) คุณจะใช้การแทนที่ข้อความมาตรฐานไม่ได้เนื่องจาก ไม่ทราบจำนวนรายการในระหว่างการออกแบบเทมเพลต

หากต้องการจัดการเนื้อหารายการแบบไดนามิก ให้ใช้กลยุทธ์ใดกลยุทธ์หนึ่งต่อไปนี้

ตัวเลือกที่ 1: เพิ่มแถวลงในตารางเทมเพลต

หากเอกสารเทมเพลตมีตารางที่จัดรูปแบบไว้แล้ว (เช่น มีแถวส่วนหัวและแถวตัวยึดตำแหน่งเดียว) คุณสามารถโคลนและป้อนข้อมูลแถวแบบไดนามิกสำหรับแต่ละรายการในรายการได้โดยทำดังนี้

  1. อ่านโครงสร้างเทมเพลต: ใช้เมธอด documents.get เพื่อค้นหาตารางและระบุ ดัชนีของแถวเทมเพลต
  2. แทรกแถวใหม่: สำหรับแต่ละรายการในรายการข้อมูลของคุณ (ยกเว้นรายการแรก รายการที่สามารถใช้แถวเทมเพลตที่มีอยู่ซ้ำได้) ให้เรียกใช้ InsertTableRowRequest เพื่อแทรกแถวใหม่ใต้แถวเทมเพลต
  3. ป้อนข้อมูลเซลล์: ป้อนข้อมูลลงในเซลล์ในแถวเทมเพลตโดยการแทนที่ตัวยึดตำแหน่ง สำหรับแถวที่สร้างขึ้นใหม่ ให้ใช้ InsertTextRequest เพื่อแทรกข้อความที่เกี่ยวข้องลงในตำแหน่งพิกัดของแต่ละเซลล์

ดูตัวอย่างวิธีแทรกแถวตารางได้ที่หัวข้อการใช้ ตาราง

ตัวเลือกที่ 2: แทนที่แท็กด้วยตารางที่สร้างขึ้น

หากต้องการสร้างตารางตั้งแต่ต้นโดยใช้โปรแกรม ให้ทำดังนี้

  1. วางแท็กตัวยึดตำแหน่ง: ใช้แท็กเดียว (เช่น {{invoice-table}}) ในเอกสารเทมเพลต เพื่อทำเครื่องหมายตำแหน่งที่ควรวางรายการ
  2. ค้นหาตัวยึดตำแหน่ง: ใช้การดำเนินการค้นหาเพื่อค้นหา ดัชนีเริ่มต้น ของแท็ก
  3. ลบตัวยึดตำแหน่ง: ใช้ DeleteContentRangeRequest เพื่อนำข้อความ {{invoice-table}} ออก
  4. แทรกตาราง: ส่ง InsertTableRequest ที่ดัชนีเริ่มต้นนั้น โดยระบุจำนวนแถวและคอลัมน์ตาม แหล่งข้อมูล
  5. เขียนค่า: ป้อนข้อมูลลงในเซลล์ตารางแต่ละเซลล์ตามลำดับ

ดูตัวอย่างการแทรกตารางโดยใช้โปรแกรมได้ที่หัวข้อการใช้ ตาราง