Belge

Bu kılavuzda Google Docs API'yi oluşturan birincil yöntemler, bir dokümana nasıl erişileceği ve doküman oluştururken uygulanan iş akışı gibi kavramlar tanıtılmaktadır.

API yöntemleri

documents kaynağı, Docs API'yi çağırmak için kullandığınız yöntemleri sağlar. 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.
  • Belirtilen bir dokümanın içeriğini almak için documents.get yöntemini kullanın.
  • Belirtilen belgede bir grup 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 documentId gerektirir. documents.create yöntemi, oluşturulan belgenin bir örneğini döndürür. Bu örnekten documentId öğesini okuyabilirsiniz. Docs API istekleri ve yanıt yöntemleri hakkında daha fazla bilgi için, İstekler ve yanıtlar'a bakın.

Belge Kimliği

documentId, belgenin benzersiz tanımlayıcısıdır ve dokümanın URL'sinden türetilebilir. Harfleri, sayıları ve bazı özel karakterleri içeren belirli bir dizedir. Belge adları, belge adı değişse bile sabittir.

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

Aşağıdaki normal ifade, bir Google Dokümanlar URL'sinden documentId öğesini çıkarmak için kullanılabilir:

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

Google Drive API hakkında bilginiz varsa documentId, files kaynağındaki id'a karşılık gelir.

Dokümanları Google Drive'da yönetin

Dokümanlar dosyaları, bulut tabanlı depolama hizmetimiz Google Drive'da depolanır. Docs API'nin kendi bağımsız yöntemleri olsa da, bir kullanıcının Dokümanlar dosyalarıyla etkileşimde bulunmak için genellikle Google Drive API yöntemlerinin 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 başlıklı makaleye göz atın.

Varsayılan olarak, Docs API'yi kullanırken 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 edinmek için Google Drive klasörleriyle çalışma başlıklı makaleye göz atın.

Dokümanlar dosyalarıyla çalışma

Bir kullanıcının Drive'ım bölümünden bir dokümanı almak için genellikle önce dosyanın kimliğini almak üzere Drive'ın files.list yöntemini kullanmanız gerekir. Yöntemin herhangi bir parametre olmadan çağrılması, kullanıcı için kimlikler de dahil olmak üzere tüm dosya ve klasörlerin bir listesini döndürü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'da desteklenen MIME türleri başlıklı makaleye göz atın.

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 hakkında bilgi edindikten sonra, belirtilen dokümanın tam 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 dosyanın documentId ile birlikte doğru dışa aktarma MIME türünü kullanın. Daha fazla bilgi için Google Workspace dokümanı içeriğini dışa aktarma bölümüne bakın.

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

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

Operatör Açıklama Kullanım
drive.files.get Dosyanın meta verilerini kimliğe göre alır. files kaynağının bir örneğini döndürür. Belirli bir dosyanın meta verilerini alma.
drive.files.list Bir kullanıcının dosyalarını alır. Dosya listesi döndürür. Hangi dosyayı değiştirmeniz gerektiğinden emin olamıyorsanız kullanıcı dosyalarının listesini alın.
docs.documents.get Tüm biçimlendirme ve metin 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ığından, yeni bir doküman oluşturmak ve doldurmak basittir. Kavramsal olarak bu, aşağıdaki sıra diyagramında gösterildiği gibi çalışır:

iş akışı ve yeni bir belge oluşturma ve doldurma iş akışı.
Şekil 1. Yeni bir doküman oluşturma ve doldurma iş akışı.

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

  1. Bir uygulama, web sunucusunda documents.create yöntemini çağırır.
  2. Web sunucusu, oluşturulan dokümanın bir örneğini documents kaynağı olarak içeren bir HTTP yanıtı gönderir.
  3. İsteğe bağlı olarak uygulama, belgeyi verilerle doldurmak için bir dizi düzenleme isteğini atomik olarak gerçekleştirmek için documents.batchUpdate yöntemini çağırır.
  4. Web sunucusu bir HTTP yanıtı gönderir. Bazı documents.batchUpdate yöntemleri bir yanıt gövdesine uygulanan istekler hakkında bilgi 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şlemdir. Bir dokümanı güncellemek için anlamlı çağrılar yapmadan önce mevcut durumunu, hangi öğelerin oluşturduğunu, bu öğelerde hangi içeriklerin bulunduğunu ve belgedeki öğelerin sırasını bilmeniz gerekir. Aşağıdaki adım sırası şemasında bunun nasıl çalıştığı gösterilmektedir:

Bir dokümanı güncelleme iş akışı.
Şekil 2. Bir dokümanı güncelleme iş akışı.

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

  1. Bir uygulama, bulunacak dosyanın documentId ile birlikte bir web sunucusunda documents.get yöntemini çağırır.
  2. Web sunucusu, belirtilen dokümanın bir ö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, JSON dosyasını ayrıştırır. Böylece kullanıcı, hangi içeriğin veya biçimin güncelleneceğini belirleyebilir.
  4. Uygulama, belgeyi 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 bir HTTP yanıtı gönderir. Bazı documents.batchUpdate yöntemleri bir yanıt gövdesine uygulanan istekler hakkında bilgi sağlarken bazıları boş bir yanıt gösterir.

Bu şema, aynı belgede diğer ortak çalışanların eşzamanlı güncellemelerinin yapıldığı iş akışları dikkate alınmaz. Daha fazla bilgi için Ortak çalışma planlama en iyi uygulamalar bölümüne bakın.