Gelişmiş Dokümanlar Hizmeti

Gelişmiş Dokümanlar hizmeti, Apps Komut Dosyası'nda Google Docs API'yi kullanmanıza olanak tanır. Apps Komut Dosyası'nın yerleşik Dokümanlar hizmetine çok benzer şekilde bu API de komut dosyalarının Google Dokümanlar'da 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ç ekstra özellik sunar.

Referans

Bu hizmet hakkında ayrıntılı bilgi için Docs API referans belgelerini inceleyin. Apps Komut Dosyası'ndaki tüm gelişmiş hizmetler gibi gelişmiş Dokümanlar hizmeti de genel API ile aynı nesneleri, yöntemleri ve parametreleri kullanır. Daha fazla bilgi için Yöntem imzaları nasıl belirlenir? başlıklı makaleye bakın.

Sorunları bildirmek ve diğer destek seçeneklerini öğrenmek için Dokümanlar API'si destek kılavuzuna göz atın.

Örnek kod

Aşağıdaki örnek kod API'nin 1. sürümünü kullanmaktadır.

Doküman 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 metin çiftlerini bulur ve değiştirir. Bu, bir şablon belgesinin kopyasındaki yer tutucuları bir veritabanındaki değerlerle değiştirirken yararlı 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];
    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 metin stilini ayarlama

Bu örnek, dokümanın başına yeni metin ve belirli bir yazı tipi ve boyuttaysa stiller ekler. Verimlilik için mümkün olduğunda birden fazla işlemi tek bir batchUpdate çağrısında gruplandırmanız gerektiğini unutmayın.

advanced/docs.gs
/**
 * Insert text at the beginning of 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
      },
      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ümanın ilk paragrafındaki metni günlüğe 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 body of 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);
    const bodyElements = document.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 iyi uygulamalar

Toplu Güncellemeler

Gelişmiş Dokümanlar hizmetini kullanırken, döngüde batchUpdate çağrısı yapmak yerine birden fazla isteği bir dizide birleştirin.

Yapmayın — batchUpdate adlı kişiyi döngüye alın.

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

Yapılması - 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);