Doküman

Bu kılavuzda, Google Dokümanlar API'sini oluşturan temel yöntemler, bir belgeye erişme ve belge oluştururken kullanılan iş akışı gibi kavramlar tanıtılmaktadır.

API yöntemleri

documents kaynağı, Dokümanlar API'sini çağırmak için kullandığınız yöntemleri sağlar. Aşağıdaki yöntemlerle Dokümanlar dosyaları oluşturabilir, okuyabilir ve güncelleyebilirsiniz:

  • Doküman oluşturmak için documents.create yöntemini kullanın.
  • Belirtilen bir belgenin içeriğini almak için documents.get yöntemini kullanın.
  • Belirli bir dokümanda 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 documentId gerektirir. documents.create yöntemi, oluşturulan dokümanın bir örneğini döndürür. Bu örnekten documentId okunabilir. Docs API istekleri ve yanıt yöntemleri hakkında daha fazla bilgi için İstekler ve yanıtlar başlıklı makaleyi inceleyin.

Belge Kimliği

documentId, dokümanın benzersiz tanımlayıcısıdır ve dokümanın URL'sinden elde edilebilir. Harfler, sayılar 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

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

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

Google Drive API'yi biliyorsanız documentId, files kaynağında id ile eşleşir.

Dokümanları Google Drive'da yönetin

Dokümanlar dosyaları, bulut tabanlı depolama hizmetimiz olan Google Drive'da depolanır. Dokümanlar API'sinin kendi bağımsız yöntemleri olsa da genellikle bir kullanıcının Dokümanlar dosyalarıyla etkileşim kurmak için Google Drive API yöntemlerini de kullanmak 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ı makaleyi inceleyin.

Varsayılan olarak, Dokümanlar API'si kullanılırken yeni bir doküman, kullanıcının Drive'daki kök klasörüne 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.

Work with Docs files

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

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

Yalnızca Drive'ım içindeki 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 başlıklı makaleyi inceleyin.

documentId değerini öğrendikten sonra, belirtilen belgenin tam bir örneğini almak için documents.get yöntemini kullanın. Daha fazla bilgi için İstekler ve yanıtlar başlıklı makaleyi inceleyin.

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

Get ve List yöntemlerini karşılaştırma

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

İşletmeci 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 dosyanın meta verilerini alma.
drive.files.list Bir kullanıcının dosyalarını alır. Dosya listesini döndürür. Hangi dosyayı değiştirmeniz gerektiğinden emin olmadığınızda kullanıcı dosyalarının listesini alın.
docs.documents.get Belirtilen dokümanın tüm biçimlendirme ve metinleri içeren 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ı alma.

Belge oluşturma iş akışı

Endişelenecek mevcut içerik ve doküman durumunu değiştirebilecek ortak çalışan olmadığından yeni bir doküman oluşturmak ve doldurmak kolaydır. Kavramsal olarak bu işlem, aşağıdaki sıra şemasında gösterildiği gibi çalışır:

Yeni bir doküman 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ının bilgi akışı şu şekildedir:

  1. Bir uygulama, web sunucusunda documents.create yöntemini çağırır.
  2. Web sunucusu, oluşturulan belgenin bir örneğini documents kaynağı olarak içeren bir HTTP yanıtı gönderir.
  3. İsteğe bağlı olarak, uygulama, dokümanı verilerle doldurmak için bir dizi düzenleme isteğini atomik olarak gerçekleştirmek üzere documents.batchUpdate yöntemini çağırır.
  4. Web sunucusu bir HTTP yanıtı gönderir. Bazı documents.batchUpdate yöntemler uygulanan isteklerle ilgili bilgileri içeren bir yanıt gövdesi sağlarken diğerleri boş bir yanıt gösterir.

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

Mevcut bir dokümanı güncellemek daha karmaşıktır. Bir belgeyi güncellemek için anlamlı çağrılar yapmadan önce belgenin mevcut durumunu bilmeniz gerekir: Hangi öğelerden oluştuğu, bu öğelerde hangi içeriğin bulunduğu ve öğelerin belgedeki sırası. Aşağıdaki sıra şeması, bu işlemin nasıl çalıştığını gösterir:

Belgeyi güncelleme iş akışı.
Şekil 2. Doküman güncelleme iş akışı.

Şekil 2'de, documents kaynağıyla etkileşimde bulunan bir kullanıcının bilgi akışı şu şekildedir:

  1. Bir uygulama, bulunacak dosyanın documentId ile birlikte bir web sunucusunda documents.get yöntemini çağırır.
  2. Web sunucusu, belirtilen belgenin 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, kullanıcının hangi içeriği veya biçimi güncelleyeceğini belirleyebilmesi için JSON'u ayrıştırır.
  4. Uygulama, dokümanı güncellemek için bir dizi düzenleme isteğini atomik olarak gerçekleştirmek üzere documents.batchUpdate yöntemini çağırır.
  5. Web sunucusu bir HTTP yanıtı gönderir. Bazı documents.batchUpdate yöntemler uygulanan isteklerle ilgili bilgileri içeren bir yanıt gövdesi sağlarken diğerleri boş bir yanıt gösterir.

Bu şemada, aynı dokümanda diğer ortak çalışanlar tarafından eşzamanlı güncellemelerin yapıldığı iş akışları dikkate alınmaz. Daha fazla bilgi için en iyi uygulamalar bölümündeki İşbirliği planlama başlıklı makaleyi inceleyin.