Metni dokümanda birleştirme

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

Bu sayfada, harici bir kaynaktan alınan verileri mevcut bir şablon belgesine nasıl ekleyeceğiniz açıklanmaktadır.

Şablon, şablondan oluşturulan tüm dokümanlar için aynı sabit metni ve diğer dinamik metinlerin yerleştirilebileceği belirli yer tutucuları içeren özel bir doküman türüdür. Örneğin, bir sözleşme şablonunda sabit içeriklerin yanı sıra alıcının adı, adresi ve diğer ayrıntılar için alanlar bulunabilir. Uygulamanız, tamamlanmış dokümanlar oluşturmak için müşteriye özgü verileri şablonla birleştirebilir.

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

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

  • İçeriği sunudan ayırmak, birçok avantajı olan iyi bilinen bir tasarım ilkesine dayanır.

Birleştirmenin kavramsal şeması.

Temel bir tarif

Verileri bir dokümanda birleştirmek için Dokümanlar API'yi nasıl kullanabileceğinize dair bir örnek aşağıda verilmiştir:

  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 metin biçimlendirmeleri korunur.

  2. Ekleyeceğiniz her öğe için yer tutucu içeriği bir etiketle değiştirin. Normalde oluşması olası olmayan dizelerden 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

Bitmiş bir belge oluşturmak için şablonun tüm sekmelerindeki 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<>();
// 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 şablonu, uygulamayı temsil eden özel bir hesap kullanarak oluşturun. Hizmet hesapları, paylaşımı kısıtlayan Google Workspace politikalarıyla ilgili komplikasyonları önleyen iyi bir seçimdir.

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

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

  1. Dokümanlar API'sinde documents.create işlevini kullanarak bir doküman oluşturun.
  2. Drive API'de permissions.create işlevini kullanarak doküman alıcılarının dokümanı okumasına izin verecek şekilde izinleri güncelleyin.
  3. Drive API'de permissions.create'i kullanarak şablon yazarlarının şablona yazmaları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 işlevini kullanarak şablonun bir kopyasını oluşturun.
  2. Dokümanlar API'sinde documents.batchUpdate yöntemini kullanarak değerleri değiştirin.