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

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

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

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

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

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

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

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

מתכון בסיסי

דוגמה לשימוש ב-Docs API למיזוג נתונים למסמך:

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

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

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

  4. בקוד, משתמשים בשיטה 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<>();
// 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();

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,
      },
    },
  ];

  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 = [
        # 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()

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

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

כשאתם יוצרים מופעים של מסמכים מתבניות, תמיד צריך להשתמש בפרטי הכניסה של משתמשי הקצה. כך המשתמשים יכולים לשלוט במסמך שנוצר, ומונעים בעיות שקשורות להרחבת היקף העבודה עקב מגבלות לכל משתמש ב-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.