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

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

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

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

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

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

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

תרשים רעיוני של מיזוג.

מתכון בסיסי

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

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

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

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

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

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

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

דוגמה

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

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

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, להגביל את השיתוף.

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

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

  1. יצירת מסמך באמצעות documents.create ב-Docs API.
  2. מעדכנים את ההרשאות כדי לאפשר לנמעני המסמך לקרוא אותו באמצעות permissions.create ב- ממשק ה-API של Drive.
  3. צריך לעדכן את ההרשאות כדי לאפשר למחברי התבנית לכתוב בה באמצעות permissions.create ב- ממשק ה-API של Drive.
  4. עורכים את התבנית לפי הצורך.

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

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