מיזוג טקסט למסמך

אחד מהיישומים השימושיים של Google Docs API הוא מיזוג מידע ממקור נתונים אחד או יותר למסמך.

בדף הזה מוסבר איך לקחת נתונים ממקור חיצוני ולהוסיף אותם למסמך תבנית קיים.

template הוא סוג מיוחד של מסמך, שמכיל את אותו טקסט קבוע לכל המסמכים שנוצרו מהתבנית, לצד ערכי placeholder ייעודיים שבהם אפשר להוסיף טקסט דינמי אחר. לדוגמה, תבנית חוזה עשויה לכלול תוכן קבוע, לצד המקומות שבהם אפשר לראות את השם, הכתובת ופרטים נוספים של המקבל. לאחר מכן, האפליקציה יכולה למזג נתונים ספציפיים ללקוחות באמצעות התבנית כדי ליצור מסמכים סופיים.

הגישה הזו שימושית מכמה סיבות:

  • מעצבים יכולים לשפר ולחדד את העיצוב של מסמך בקלות באמצעות עורך Google Docs. הדרך הזו פשוטה יותר מכוונון של פרמטרים באפליקציה להגדרת הפריסה המעובדת.

  • הפרדת התוכן מהמצגת היא עיקרון עיצובי ידוע, עם יתרונות רבים.

תרשים קונספט של מיזוג.

מתכון בסיסי

הנה דוגמה לאופן שבו אפשר להשתמש ב-Docs API כדי למזג נתונים למסמך:

  1. צרו מסמך באמצעות תוכן Placeholder כדי לעזור לכם בעיצוב ובפורמט. כל עיצוב הטקסט שרוצים להחליף יישמר.

  2. לכל רכיב שרוצים להוסיף, מחליפים את תוכן ה-placeholder בתג. חשוב להשתמש במחרוזות שלא סביר שהן יתרחשו כרגיל. לדוגמה, {{account-holder-name}} יכול להיות תג טוב.

  3. בקוד, משתמשים ב-Google Drive API כדי ליצור עותק של המסמך.

  4. בקוד, משתמשים ב-method batchUpdate() של ה-Docs API עם שם המסמך וכוללים ReplaceAllTextRequest.

מזהי המסמכים מפנים למסמך והם יכולים להיות נגזרים מכתובת ה-URL

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

דוגמה

לפניכם דוגמה, שמחליפה 2 שדות בתבנית בערכים ממשיים כדי ליצור מסמך סופי.

כדי לבצע את המיזוג הזה, אפשר להשתמש בקוד שבהמשך.

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

ניהול התבניות

אם מדובר במסמכי תבנית שהאפליקציה מגדירה ובבעלותה, צריך ליצור את התבנית באמצעות חשבון ייעודי שמייצג את האפליקציה. מומלץ להשתמש בחשבונות שירות, וכך להימנע מסיבוכים עם המדיניות של Google Workspace שמגבילה את השיתוף.

כשיוצרים מכונות של מסמכים מתבניות, חשוב להשתמש תמיד בפרטי הכניסה של משתמשי הקצה. כך למשתמשים יש שליטה מלאה על המסמך שמתקבל ומניעת בעיות בהתאמה לעומס (scaling) הקשורות למגבלות לכל משתמש ב-Drive.

כדי ליצור תבנית באמצעות חשבון שירות, מבצעים את השלבים הבאים עם פרטי הכניסה לאפליקציה:

  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.