Gelişmiş Dokümanlar Hizmeti

Gelişmiş Dokümanlar hizmeti, Apps Komut Dosyası'nda Google Dokümanlar API'yi kullanmanıza olanak tanır. Apps Komut Dosyası'nın yerleşik Dokümanlar hizmetine benzer şekilde bu API, komut dosyalarının Google Dokümanlar'daki içeriği okumasına, düzenlemesine ve biçimlendirmesine olanak tanır. Çoğu durumda yerleşik hizmetin kullanımı daha kolaydır ancak bu gelişmiş hizmet birkaç ek özellik sunar.

Referans

Bu hizmetle ilgili ayrıntılı bilgi için Dokümanlar API'sinin referans belgelerine bakın. Apps Komut Dosyası'ndaki tüm gelişmiş hizmetler gibi, gelişmiş Dokümanlar hizmeti de herkese açık API ile aynı nesneleri, yöntemleri ve parametreleri kullanır. Daha fazla bilgi için Yöntem imzaları nasıl belirlenir? başlıklı makaleyi inceleyin.

Sorunları bildirmek ve diğer destek seçeneklerini öğrenmek için Docs API destek kılavuzuna bakın.

Örnek kod

Aşağıdaki örnek kodda API'nin 1. sürümü kullanılmaktadır.

Belge oluştur

Bu örnek, yeni bir doküman oluşturur.

advanced/docs.gs
/**
 * Create a new document.
 * @see https://developers.google.com/docs/api/reference/rest/v1/documents/create
 * @return {string} documentId
 */
function createDocument() {
  try {
    // Create document with title
    const document = Docs.Documents.create({'title': 'My New Document'});
    console.log('Created document with ID: ' + document.documentId);
    return document.documentId;
  } catch (e) {
    // TODO (developer) - Handle exception
    console.log('Failed with error %s', e.message);
  }
}

Metin bulma ve değiştirme

Bu örnek, bir dokümandaki tüm sekmelerde metin çiftlerini bulup değiştirir. Bu, bir şablon belgesinin kopyasındaki yer tutucuları bir veritabanındaki değerlerle değiştirirken faydalı olabilir.

advanced/docs.gs
/**
 * Performs "replace all".
 * @param {string} documentId The document to perform the replace text operations on.
 * @param {Object} findTextToReplacementMap A map from the "find text" to the "replace text".
 * @return {Object} replies
 * @see https://developers.google.com/docs/api/reference/rest/v1/documents/batchUpdate
 */
function findAndReplace(documentId, findTextToReplacementMap) {
  const requests = [];
  for (const findText in findTextToReplacementMap) {
    const replaceText = findTextToReplacementMap[findText];
    // One option for replacing all text is to specify all tab IDs.
    const request = {
      replaceAllText: {
        containsText: {
          text: findText,
          matchCase: true
        },
        replaceText: replaceText,
        tabsCriteria: {
          tabIds: [TAB_ID_1, TAB_ID_2, TAB_ID_3],
        }
      }
    };
    // Another option is to omit TabsCriteria if you are replacing across all tabs.
    const request = {
      replaceAllText: {
        containsText: {
          text: findText,
          matchCase: true
        },
        replaceText: replaceText
      }
    };
    requests.push(request);
  }
  try {
    const response = Docs.Documents.batchUpdate({'requests': requests}, documentId);
    const replies = response.replies;
    for (const [index] of replies.entries()) {
      const numReplacements = replies[index].replaceAllText.occurrencesChanged || 0;
      console.log('Request %s performed %s replacements.', index, numReplacements);
    }
    return replies;
  } catch (e) {
    // TODO (developer) - Handle exception
    console.log('Failed with error : %s', e.message);
  }
}

Metin ekleme ve stilini belirleme

Bu örnek, dokümandaki ilk sekmenin başına yeni metin ekler ve belirli bir yazı tipi ve boyutta biçimlendirir. Mümkün olduğunda verimlilik için birden fazla işlemi tek bir batchUpdate çağrısında toplu olarak göndermeniz gerektiğini unutmayın.

advanced/docs.gs
/**
 * Insert text at the beginning of the first tab in the document and then style
 * the inserted text.
 * @param {string} documentId The document the text is inserted into.
 * @param {string} text The text to insert into the document.
 * @return {Object} replies
 * @see https://developers.google.com/docs/api/reference/rest/v1/documents/batchUpdate
 */
function insertAndStyleText(documentId, text) {
  const requests = [{
    insertText: {
      location: {
        index: 1,
        // A tab can be specified using its ID. When omitted, the request is
        // applied to the first tab.
        // tabId: TAB_ID
      },
      text: text
    }
  },
  {
    updateTextStyle: {
      range: {
        startIndex: 1,
        endIndex: text.length + 1
      },
      textStyle: {
        fontSize: {
          magnitude: 12,
          unit: 'PT'
        },
        weightedFontFamily: {
          fontFamily: 'Calibri'
        }
      },
      fields: 'weightedFontFamily, fontSize'
    }
  }];
  try {
    const response =Docs.Documents.batchUpdate({'requests': requests}, documentId);
    return response.replies;
  } catch (e) {
    // TODO (developer) - Handle exception
    console.log('Failed with an error %s', e.message);
  }
}

İlk paragrafı oku

Bu örnek, dokümandaki ilk sekmenin ilk paragrafının metnini kaydeder. Docs API'deki paragrafların yapılandırılmış yapısı nedeniyle bu işlem, birden fazla alt öğenin metnini birleştirmeyi içerir.

advanced/docs.gs
/**
 * Read the first paragraph of the first tab in a document.
 * @param {string} documentId The ID of the document to read.
 * @return {Object} paragraphText
 * @see https://developers.google.com/docs/api/reference/rest/v1/documents/get
 */
function readFirstParagraph(documentId) {
  try {
    // Get the document using document ID
    const document = Docs.Documents.get(documentId, {'includeTabsContent': true});
    const firstTab = document.tabs[0];
    const bodyElements = firstTab.documentTab.body.content;
    for (let i = 0; i < bodyElements.length; i++) {
      const structuralElement = bodyElements[i];
      // Print the first paragraph text present in document
      if (structuralElement.paragraph) {
        const paragraphElements = structuralElement.paragraph.elements;
        let paragraphText = '';

        for (let j = 0; j < paragraphElements.length; j++) {
          const paragraphElement = paragraphElements[j];
          if (paragraphElement.textRun !== null) {
            paragraphText += paragraphElement.textRun.content;
          }
        }
        console.log(paragraphText);
        return paragraphText;
      }
    }
  } catch (e) {
    // TODO (developer) - Handle exception
    console.log('Failed with error %s', e.message);
  }
}

En İyi Uygulamalar

Toplu Güncellemeler

Gelişmiş Dokümanlar hizmetini kullanırken batchUpdate işlevini döngü içinde çağırmak yerine birden fazla isteği bir dizide birleştirin.

Yapmayın: batchUpdate işlevini döngü içinde çağırmayın.

var textToReplace = ['foo', 'bar'];
for (var i = 0; i < textToReplace.length; i++) {
  Docs.Documents.batchUpdate({
    requests: [{
      replaceAllText: ...
    }]
  }, docId);
}

Yapılacaklar: Bir dizi güncellemeyle batchUpdate işlevini çağırın.

var requests = [];
var textToReplace = ['foo', 'bar'];
for (var i = 0; i < textToReplace.length; i++) {
  requests.push({ replaceAllText: ... });
}

Docs.Documents.batchUpdate({
  requests: requests
}, docId);