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

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

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

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

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

  • למעצבים קל לשפר את העיצוב של מסמך באמצעות עורך 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 ב-API של Docs.
  2. מעדכנים את ההרשאות כדי לאפשר לנמעני המסמך לקרוא אותו באמצעות permissions.create ב-Drive API.
  3. מעדכנים את ההרשאות כדי לאפשר לכותבי התבניות לכתוב לקובץ באמצעות permissions.create ב-Drive API.
  4. עורכים את התבנית לפי הצורך.

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

  1. יוצרים עותק של התבנית באמצעות files.copy ב-Drive API.
  2. מחליפים ערכים באמצעות documents.batchUpdate ב-API של Docs.