Belge

Bu kılavuzda, Google Docs API'yi oluşturan birincil yöntemler, dokümana erişim ve doküman oluştururken iş akışı gibi kavramlar açıklanmaktadır.

API yöntemleri

documents kaynağı, Docs API'yi çağırmak için kullandığınız yöntemleri sunar. Aşağıdaki yöntemler Dokümanlar dokümanlarını oluşturmanıza, okumanıza ve güncellemenize olanak tanır:

  • Belge oluşturmak için documents.create yöntemini kullanın.
  • Belirli bir dokümanın içeriğini almak için documents.get yöntemini kullanın.
  • Belirli bir belgede bir dizi güncellemeyi atomik olarak gerçekleştirmek için documents.batchUpdate yöntemini kullanın.

documents.get ve documents.batchUpdate yöntemleri, hedef belgeyi belirtmek için parametre olarak bir documentId gerektirir. documents.create yöntemi, oluşturulan dokümanın bir örneğini döndürür. Bu örnekten documentId dosyasını okuyabilirsiniz. Docs API istekleri ve yanıt yöntemleri hakkında daha fazla bilgi için İstekler ve yanıtlar bölümüne bakın.

Belge Kimliği

documentId, belgenin benzersiz tanımlayıcısıdır ve dokümanın URL'sinden türetilebilir. Harf, sayı ve bazı özel karakterler içeren belirli bir dizedir. Doküman adı değişse bile doküman kimlikleri sabit kalır.

https://docs.google.com/document/d/DOCUMENT_ID/edit

Bir Google Dokümanlar URL'sinden documentId öğesini ayıklamak için aşağıdaki normal ifade kullanılabilir:

/document/d/([a-zA-Z0-9-_]+)

Google Drive API hakkında bilgi sahibiyseniz files kaynağındaki documentId, id öğesine karşılık gelir.

Dokümanları Google Drive'da yönetin

Dokümanlar dosyaları, bulut tabanlı depolama hizmetimiz olan Google Drive'da depolanır. Docs API kendi bağımsız yöntemlerine sahip olsa da, bir kullanıcının Dokümanlar dosyalarıyla etkileşime geçmek için genellikle Google Drive API yöntemlerinin de kullanılması gerekir. Örneğin, Dokümanlar dosyalarını kopyalamak için Drive API'nin files.copy yöntemini kullanın. Daha fazla bilgi için Mevcut bir dokümanı kopyalama bölümüne bakın.

Dokümanlar API'si kullanılırken varsayılan olarak kullanıcının Drive'daki kök klasörüne yeni bir doküman kaydedilir. Dosyaları Drive klasörüne kaydetme seçenekleri vardır. Daha fazla bilgi için Google Drive klasörleriyle çalışma başlıklı makaleyi inceleyin.

Dokümanlar dosyalarıyla çalışma

Bir kullanıcının Drive'ım bölümündeki bir dokümanı almak için genellikle ilk olarak Drive'ın files.list yöntemini kullanarak dosyanın kimliğini geri almanız gerekir. Yöntem herhangi bir parametre olmadan çağrıldığında kullanıcı için kimlikler de dahil olmak üzere tüm dosya ve klasörlerin bir listesi döndürülür.

Bir dokümanın MIME türü, veri türünü ve biçimini belirtir. Dokümanlar için MIME türü biçimi application/vnd.google-apps.document şeklindedir. MIME türlerinin listesi için Google Workspace ve Google Drive tarafından desteklenen MIME türleri başlıklı makaleyi inceleyin.

Yalnızca Drive'ım bölümündeki Dokümanlar dosyalarını MIME türüne göre aramak için aşağıdaki sorgu dizesi filtresini ekleyin:

q: mimeType = 'application/vnd.google-apps.document'

Sorgu dizesi filtreleri hakkında daha fazla bilgi için Dosya ve klasör arama bölümüne bakın.

documentId öğesini öğrendikten sonra, belirtilen dokümanın eksiksiz bir örneğini almak için documents.get yöntemini kullanın. Daha fazla bilgi için İstekler ve yanıtlar bölümüne bakın.

Google Workspace doküman baytı içeriğini dışa aktarmak için Drive'ın files.export yöntemini kullanarak dışa aktarılacak dosyanın documentId'ını ve dışa aktarma MIME türünü doğru şekilde belirleyin. Daha fazla bilgi için Google Workspace doküman içeriğini dışa aktarma başlıklı makaleyi inceleyin.

Get ve List yöntemlerini karşılaştırın

Aşağıdaki tabloda, Drive ve Dokümanlar yöntemleri arasındaki farklar ve her biriyle döndürülen veriler açıklanmaktadır:

Operatör Açıklama Kullanım
drive.files.get Bir dosyanın meta verilerini kimliğe göre alır. files kaynağının bir örneğini döndürür. Belirli bir dosya için meta verileri alma.
drive.files.list Kullanıcının dosyalarını alır. Bir dosya listesi döndürür. Hangi dosyayı değiştirmeniz gerektiğinden emin değilseniz kullanıcı dosyalarının listesini alabilirsiniz.
docs.documents.get Tüm biçimlendirme ve metin de dahil olmak üzere, belirtilen dokümanın en son sürümünü alır. documents kaynağının bir örneğini döndürür. Belirli bir doküman kimliğine ait dokümanı alın.

Doküman oluşturma iş akışı

Endişelenecek mevcut bir içerik ve doküman durumunu değiştirebilecek ortak çalışan olmadığı için yeni bir doküman oluşturma ve doldurma işlemi oldukça kolaydır. Kavramsal olarak bu, aşağıdaki dizi diyagramında gösterildiği gibi çalışır:

İş akışı ile yeni bir belge oluşturmak ve doldurmak.
Şekil 1. Yeni bir doküman oluşturup doldurmak için iş akışı.

Şekil 1'de, documents kaynağıyla etkileşimde bulunan bir kullanıcı aşağıdaki bilgi akışına sahiptir:

  1. Uygulama, bir web sunucusunda documents.create yöntemini çağırır.
  2. Web sunucusu, oluşturulan dokümanın örneğini documents kaynağı olarak içeren bir HTTP yanıtı gönderir.
  3. İsteğe bağlı olarak, uygulama documents.batchUpdate yöntemini çağırarak belgeyi verilerle doldurmak için bir dizi düzenleme isteğini atomik olarak gerçekleştirir.
  4. Web sunucusu, HTTP yanıtı gönderir. Bazı documents.batchUpdate yöntemleri, uygulanan istekler hakkında bilgi içeren bir yanıt gövdesi sağlarken, bazıları boş bir yanıt gösterir.

Doküman güncelleme iş akışı

Mevcut bir dokümanı güncellemek daha karmaşık bir iştir. Bir dokümanı güncellemek için anlamlı çağrılar yapmadan önce, dokümanın mevcut durumunu bilmeniz gerekir: belgenin hangi öğeler oluşturduğunu, bu öğelerde hangi içeriğin bulunduğu ve dokümandaki öğelerin sırası. Aşağıdaki dizi şemasında bunun nasıl çalıştığı gösterilmektedir:

iş akışını takip edebilir.
Şekil 2. Doküman güncelleme iş akışı.

Şekil 2.'de, documents kaynağıyla etkileşime giren bir kullanıcı aşağıdaki bilgi akışına sahiptir:

  1. Bir uygulama, bulunacak dosyanın documentId ile birlikte web sunucusunda documents.get yöntemini çağırır.
  2. Web sunucusu, belirtilen dokümanın örneğini documents kaynağı olarak içeren bir HTTP yanıtı gönderir. Döndürülen JSON; belge içeriğini, biçimlendirmeyi ve diğer özellikleri içerir.
  3. Uygulama, kullanıcının hangi içeriği veya biçimi güncelleyeceğini belirleyebilmesi için JSON dosyasını ayrıştırır.
  4. Uygulama, dokümanı güncellemek amacıyla bir dizi düzenleme isteğini atomik olarak gerçekleştirmek için documents.batchUpdate yöntemini çağırır.
  5. Web sunucusu, HTTP yanıtı gönderir. Bazı documents.batchUpdate yöntemleri, uygulanan istekler hakkında bilgi içeren bir yanıt gövdesi sağlarken, bazıları boş bir yanıt gösterir.

Bu diyagramda, diğer ortak çalışanların yaptığı güncellemelerin aynı belgede yapıldığı iş akışları dikkate alınmamıştır. Daha fazla bilgi için Ortak çalışma için plan yapma en iyi uygulamalar bölümünü inceleyin.