Metni dokümanda birleştirme

Bu kılavuzda, bir veya daha fazla harici veri kaynağındaki bilgileri mevcut bir şablon dokümanında birleştirmek için Google Dokümanlar API'sinin nasıl kullanılacağı açıklanmaktadır.

Şablon, sabit metin ve dinamik içerik için yer tutucular içeren bir belge türüdür. Örneğin, bir sözleşme şablonu, alıcının adı ve adresi için yer tutucular içeren sabit metinler içerebilir. Uygulama daha sonra, son belgeyi oluşturmak için kullanıcıya özel verileri şablonla birleştirir.

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

• Tasarımcılar, Google Dokümanlar'ı kullanarak bir dokümanın tasarımında ince ayarlar yapabilir. Bu, oluşturulan düzeni ayarlamak için uygulamanızdaki parametreleri ayarlamaktan daha basittir.

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

Belge birleştirme özelliğinin işleyiş şekli

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 <tag> ile 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/DOCUMENT_ID/edit

Şablonları yönetin

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

Ş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 Google 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. Docs API'de documents.create kullanarak doküman oluşturun.
2. Drive API'de permissions.create kullanarak doküman alıcılarının dokümanı okumasına izin verecek şekilde izinleri güncelleyin.
3. İzinleri, şablon yazarlarının Drive API'deki permissions.create kullanarak şablona yazmasına izin verecek şekilde 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 kullanarak şablonun bir kopyasını oluşturun.
2. Docs API'de documents.batchUpdate kullanarak değerleri değiştirin.

Örnek: Verileri şablonda birleştirme

Aşağıdaki kod örneğinde, tamamlanmış bir belge oluşturmak için şablondaki tüm sekmelerde iki alanın gerçek değerlerle nasıl değiştirileceği gösterilmektedir:

Bu birleştirme işlemini gerçekleştirmek için aşağıdaki kodu kullanın:

String customerName = "Alice";
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy/MM/dd");
String date = formatter.format(LocalDate.now());

// Make a copy of the template document using the Drive API.
String copyTitle = "Merged Document";
File copyMetadata = new File().setName(copyTitle);
File documentCopyFile =
        driveService.files().copy(DOCUMENT_ID, copyMetadata).execute();
String documentCopyId = documentCopyFile.getId();

List 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(documentCopyId, body.setRequests(requests)).execute();

  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,
      },
    },
  ];

  // Make a copy of the template document using the Drive API.
  let copyTitle = 'Merged Document';
  driveService.files.copy({
    fileId: '1yBx6HSnu_gbV2sk1nChJOFo_g3AizBhr-PpkyKAwcTg',
    resource: {
      name: copyTitle,
    },
  }, (err, driveResponse) => {
    if (err) return console.log('The Drive API returned an error: ' + err);
    let documentCopyId = driveResponse.data.id;

    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: documentCopyId,
                resource: {
                  requests,
                },
              },
              (err, {data}) => {
                if (err) return console.log('The API returned an error: ' + err);
                console.log(data);
              });
        });
  });

customer_name = 'Alice'
date = datetime.datetime.now().strftime("%y/%m/%d")

# Make a copy of the template document using the Drive API.
copy_title = 'Merged Document'
body = {
    'name': copy_title
}
drive_response = drive_service.files().copy(
    fileId=DOCUMENT_ID, body=body).execute()
document_copy_id = drive_response.get('id')

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_copy_id, body={'requests': requests}).execute()

Dinamik listeleri ve tabloları işleme

Standart belge birleştirme, tek seferlik yer tutucuları (ör. {{customer-name}} veya {{date}}) değiştirmek için ReplaceAllTextRequest kullanır. Ancak verilerinizde dinamik bir öğe listesi (ör. faturadaki satırlar, sipariş edilen ürünlerin listesi veya dinamik bir tablo) varsa şablon tasarımı sırasında öğe sayısı bilinmediğinden standart metin değiştirme özelliğini kullanamazsınız.

Dinamik liste içeriğini işlemek için aşağıdaki stratejilerden birini kullanın.

1. seçenek: Satırları bir şablon tablosuna ekleme

Şablon belgenizde zaten biçimlendirilmiş bir tablo varsa (örneğin, başlık satırı ve tek bir yer tutucu satır içeren), listenizdeki her öğe için satırları dinamik olarak klonlayıp doldurabilirsiniz:

1. Şablon yapısını okuyun: Tabloyu bulmak ve şablon satırının documents.get yöntemini kullanarak dizinini belirlemek için kullanın.
2. Yeni satırlar ekleme: Verilerinize göre listedeki her öğe için (mevcut şablon satırını yeniden kullanabilen ilk öğe hariç) InsertTableRowRequest işlevini çağırarak şablon satırının altına yeni bir satır ekleyin.
3. Hücre verilerini doldurma: Şablon satırındaki hücreleri yer tutucularını değiştirerek doldurun. Yeni oluşturulan satırlarda, ilgili metni her hücrenin koordinat konumuna eklemek için InsertTextRequest kullanın.

Tablo satırlarını ekleme örnekleri için Tablolarla çalışma başlıklı makaleyi inceleyin.

2. seçenek: Etiketi oluşturulan bir tabloyla değiştirme

Tabloyu programlı bir şekilde sıfırdan oluşturmak istiyorsanız:

1. Yer tutucu etiket yerleştirin: Listenin nereye gideceğini işaretlemek için şablon belgesinde tek bir etiket (ör. {{invoice-table}}) kullanın.
2. Yer tutucuyu bulun: Etiketin başlangıç dizinini bulmak için arama işlemi kullanın.
3. Yer tutucuyu silme: DeleteContentRangeRequest kullanarak {{invoice-table}} metnini kaldırın.
4. Tabloyu ekleyin: Başlangıç dizininde InsertTableRequest gönderin. Satır ve sütun sayısını veri kaynağınıza göre belirleyin.
5. Değerleri yazma: Her tablo hücresini sırayla doldurun.

Tabloları programatik olarak ekleme örnekleri için Tablolarla çalışma başlıklı makaleyi inceleyin.

İlgili konular

• Docs API ile e-posta birleştirme