Metni dokümanda birleştirme

Google Docs API'nin yararlı bir uygulaması, bir veya daha fazla veri kaynağındaki bilgileri bir dokümanda birleştirmektir.

Bu sayfada, harici bir kaynaktan nasıl veri alıp mevcut bir şablon dokümanına nasıl ekleyebileceğiniz anlatılmaktadır.

Şablon, şablondan oluşturulan tüm dokümanlar için aynı sabit metni ve başka dinamik metinlerin yerleştirilebileceği belirlenmiş yer tutucuları içeren özel bir belge türüdür. Örneğin, bir sözleşme şablonunda alıcının adı, adresi ve diğer ayrıntılarla birlikte sabit içerik bulunabilir. Uygulamanız bitmiş belgeler oluşturmak için daha sonra müşteriye özel verileri şablonda birleştirebilir.

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

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

  • Sunumdan içerik ayırmak, birçok faydası olan yaygın bir tasarım ilkesidir.

Birleştirmenin kavramsal diyagramı.

Basit bir tarif

Aşağıda, verileri bir dokümanda birleştirmek için Docs API'yi nasıl kullanabileceğinize dair bir örnek verilmiştir:

  1. Tasarım ve biçim konusunda size yardımcı olması için yer tutucu içeriği kullanarak belgenizi oluşturun. Değiştirmek istediğiniz tüm metin biçimlendirmeleri korunur.

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

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

  4. Kodunuzda, doküman adıyla 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

Tamamlanmış bir belge oluşturmak için şablondaki 2 alanı gerçek değerlerle değiştiren 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<>();
        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()

Şablonları yönetin

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

Şablonlardan doküman örnekleri oluşturduğunuzda her zaman son kullanıcı kimlik bilgilerini kullanın. Bu, kullanıcılara oluşturulan doküman üzerinde tam kontrol sağlar ve Drive'daki kullanıcı başına sınırlarla ilgili ölçeklendirme sorunlarını önler.

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

  1. Docs API'de documents.create dosyasını kullanarak bir belge oluşturun.
  2. İzinleri, belge alıcılarının Drive API'de permissions.create dosyasını kullanarak okumasına izin verecek şekilde güncelleyin.
  3. Şablon yazarlarının Drive API'de permissions.create dosyasını kullanarak yazmasına izin vermek için 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'de files.copy dosyasını kullanarak şablonun bir kopyasını oluşturun.
  2. Docs API'de documents.batchUpdate kullanarak değerleri değiştirin.