Metni dokümanda birleştirme

Google Dokümanlar API'sinin faydalı uygulamalarından biri, bir veya daha fazla veri kaynağındaki bilgileri bir dokümanda birleştirmektir.

Bu sayfada, harici bir kaynaktan alınan verilerin mevcut bir şablon belgesine nasıl eklenebileceği açıklanmaktadır.

Şablon, şablondan oluşturulan tüm dokümanlarda aynı sabit metni içeren özel bir doküman türüdür. Ayrıca, diğer dinamik metinlerin yerleştirilebileceği belirlenmiş yer tutucular da içerir. Örneğin, bir sözleşme şablonunda alıcının adı, adresi ve diğer ayrıntıları için yerlerin yanı sıra sabit içerik de bulunabilir. Uygulamanız daha sonra müşteriye özel verileri şablonla birleştirerek tamamlanmış belgeler oluşturabilir.

Bu yaklaşımın faydalı olmasının birkaç nedeni vardır:

  • Tasarımcılar, Google Dokümanlar düzenleyicisini kullanarak doküman tasarımında kolayca ince ayar yapabilir. Bu, oluşturulan düzeni ayarlamak için uygulamanızdaki parametreleri ayarlamaktan çok daha kolaydır.

  • İçeriği sunumdan ayırmak, birçok avantajı olan iyi bilinen bir tasarım ilkesidir.

Birleştirmenin kavramsal şeması.

Temel bir yemek tarifi

Dokümanlar API'sini kullanarak verileri bir dokümanda nasıl birleştirebileceğinize dair bir örneği aşağıda bulabilirsiniz:

  1. Tasarım ve biçimlendirme konusunda size yardımcı olması için yer tutucu içerik kullanarak dokümanınızı oluşturun. Değiştirmek istediğiniz tüm metin biçimlendirmeleri korunur.

  2. Ekleyeceğiniz her öğe için yer tutucu içeriği bir etiketle değiştirin. Normalde oluşması muhtemel olmayan dizeler kullandığınızdan emin olun. Örneğin, {{account-holder-name}} iyi bir etiket olabilir.

  3. Kodunuzda, dokümanın kopyasını oluşturmak için Google Drive API'yi kullanın.

  4. Kodunuzda, doküman adıyla birlikte Docs API'nin batchUpdate() yöntemini kullanın ve bir ReplaceAllTextRequest ekleyin.

Doküman kimlikleri bir dokümana referans verir ve URL'den türetilebilir.

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

Örnek

Bir şablonun tüm sekmelerindeki 2 alanı gerçek değerlerle değiştirerek tamamlanmış bir belge oluşturan aşağıdaki örneği inceleyin.

Bu birleştirme işlemini gerçekleştirmek için aşağıdaki kodu kullanabilirsiniz.

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

Şablonları yönetin

Uygulamanın tanımladığı ve sahip olduğu şablon dokümanları için uygulamayı temsil eden özel bir hesap kullanarak şablon oluşturun. Hizmet hesapları, paylaşımı kısıtlayan Google Workspace politikalarıyla ilgili sorunları önlemek için iyi bir seçimdir.

Şablonlardan doküman örnekleri oluştururken her zaman son kullanıcı kimlik bilgilerini kullanın. Bu sayede kullanıcılar, ortaya çıkan doküman üzerinde tam kontrol sahibi olur ve Drive'daki kullanıcı başına sınırlarla ilgili ölçeklendirme sorunları önlenir.

Hizmet hesabı kullanarak şablon oluşturmak için uygulama kimlik bilgileriyle aşağıdaki adımları uygulayın:

  1. Dokümanlar API'sindeki documents.create yöntemini kullanarak doküman oluşturun.
  2. Drive API'deki permissions.create yöntemini kullanarak doküman alıcılarının dokümanı okumasına izin verecek şekilde izinleri güncelleyin.
  3. Drive API'de permissions.create kullanarak şablon yazarlarının yazmasına izin verecek şekilde izinleri güncelleyin.
  4. Şablonu gerektiği gibi düzenleyin.

Dokümanın bir örneğini oluşturmak için kullanıcı kimlik bilgileriyle aşağıdaki adımları uygulayın:

  1. Drive API'deki files.copy'yi kullanarak şablonun bir kopyasını oluşturun.
  2. Docs API'de documents.batchUpdate kullanarak değerleri değiştirin.