دمج نص في مستند

أحد الاستخدامات المفيدة لواجهة برمجة التطبيقات Google Docs API هو دمج المعلومات من مصدر واحد أو أكثر من مصادر البيانات في مستند.

توضّح هذه الصفحة كيف يمكنك الحصول على بيانات من مصدر خارجي وإدراجها في مستند نموذج حالي.

النموذج هو نوع خاص من المستندات يحتوي على النص الثابت نفسه لجميع المستندات التي تم إنشاؤها من النموذج، بالإضافة إلى عناصر نائبة محددة يمكن وضع نص ديناميكي آخر فيها. على سبيل المثال، قد يحتوي نموذج عقد على محتوى ثابت، بالإضافة إلى مساحات مخصّصة لاسم المستلم وعنوانه وتفاصيل أخرى. يمكن لتطبيقك بعد ذلك دمج البيانات الخاصة بالعميل في النموذج لإنشاء مستندات مكتملة.

هناك عدة أسباب تجعل هذا الأسلوب مفيدًا:

  • يمكن للمصمّمين بسهولة ضبط تصميم المستند باستخدام أداة التحرير في "مستندات Google". وهذا أسهل بكثير من ضبط المَعلمات في تطبيقك لتحديد التنسيق المعروض.

  • إنّ فصل المحتوى عن طريقة عرضه هو مبدأ تصميم معروف وله مزايا عديدة.

مخطط تصوّري لعملية الدمج

وصفة أساسية

في ما يلي مثال على كيفية استخدام Docs API لدمج البيانات في مستند:

  1. أنشئ مستندك باستخدام محتوى عناصر نائبة لمساعدتك في التصميم والتنسيق. يتم الاحتفاظ بأي تنسيق نص تريد استبداله.

  2. لكل عنصر ستدرجه، استبدِل المحتوى النائب بعلامة احرص على استخدام سلاسل من غير المحتمل أن تحدث بشكل طبيعي. على سبيل المثال، قد تكون {{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 التي تفرض قيودًا على المشاركة.

عند إنشاء نُسخ من المستندات من النماذج، استخدِم دائمًا بيانات اعتماد المستخدم النهائي. ويمنح ذلك المستخدمين تحكّمًا كاملاً في المستند الناتج ويمنع حدوث مشاكل في التوسّع مرتبطة بالحدود القصوى المسموح بها لكل مستخدم في Drive.

لإنشاء نموذج باستخدام حساب خدمة، اتّبِع الخطوات التالية باستخدام بيانات اعتماد التطبيق:

  1. أنشئ مستندًا باستخدام طريقة documents.create في Docs API.
  2. عدِّل الأذونات للسماح لمستلمي المستند بقراءته باستخدام permissions.create في واجهة برمجة تطبيقات Drive.
  3. عدِّل الأذونات للسماح لمؤلفي النماذج بالكتابة إليها باستخدام permissions.create في Drive API.
  4. عدِّل النموذج حسب الحاجة.

لإنشاء نسخة من المستند، اتّبِع الخطوات التالية باستخدام بيانات اعتماد المستخدم:

  1. أنشئ نسخة من النموذج باستخدام files.copy في Drive API.
  2. استبدِل القيم باستخدام documents.batchUpdate في Docs API.