Doküman

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ğı, Dokümanlar API'sini çağırmak için kullandığınız yöntemleri sağlar. Aşağıdaki yöntemler, Dokümanlar belgeleri oluşturmanıza, okumanıza ve güncellemenize olanak tanır:

  • Doküman 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.
  • 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 dokümanı 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 değerini 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, dokümanın 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. Belge adı değişse bile belge 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 ayıklamak için kullanılabilir:

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

Google Drive API'yi biliyorsanız documentId, files kaynağındaki id ile aynıdır.

Dokümanları Google Drive'da yönetin

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

Docs API kullanılırken varsayılan olarak yeni doküman, kullanıcının Drive'daki kök klasörüne kaydedilir. Dosyaları Drive klasörlerine 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'ın desteklediği MIME türleri başlıklı makaleyi inceleyin.

Drive'ımda yalnızca 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 değerini öğrendikten sonra, belirtilen dokümanın tam ö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 belge bayt içeriğini dışa aktarmak için Drive'ın files.export yöntemini, dışa aktarılacak dosyanın documentId değerini ve 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 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 biriyle döndürülen veriler açıklanmaktadır:

Operatör Açıklama Kullanım
drive.files.get Dosyanın kimliğine göre meta verilerini 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. Dosyaların listesini döndürür. Hangi dosyayı değiştirmeniz gerektiğinden emin değilseniz kullanıcı dosyalarının listesini alın.
docs.documents.get Tüm biçimlendirme ve metinler 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şelenmeniz gereken mevcut içerik olmadığı ve doküman durumunu değiştirebilecek ortak çalışan olmadığından yeni bir doküman oluşturmak ve doldurmak kolaydır. Bu işlem, kavramsal olarak aşağıdaki sıra şemasında gösterildiği gibi çalışır:

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

Şekil 1'de, documents kaynağıyla etkileşime giren bir kullanıcının aşağıdaki bilgi akışı gösterilmektedir:

  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, dokümanı veri ile 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, 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şıktır. Bir dokümanı güncellemek için anlamlı çağrılar yapabilmeniz için dokümanın mevcut durumunu (dokümanı oluşturan öğeler, bu öğelerdeki içerik ve doküman içindeki öğelerin sırası) bilmeniz gerekir. Aşağıdaki sıra şeması, bunun nasıl çalıştığını gösterir:

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 bir kullanıcının aşağıdaki bilgi akışı vardır:

  1. Bir uygulama, web sunucusunda documents.get yöntemini, bulunacak dosyanın documentId ile ç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ğin veya biçimin güncelleneceğini belirleyebilmesi için JSON'u 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 bir HTTP yanıtı gönderir. Bazı documents.batchUpdate yöntemleri, uygulanan istekler hakkında bilgi içeren bir yanıt gövdesi sağlarken diğerleri boş bir yanıt gösterir.

Bu şema, diğer ortak çalışanlar tarafından aynı dokümanda eşzamanlı güncellemelerin yapıldığı iş akışlarını dikkate almaz. Daha fazla bilgi için Ortak çalışma için plan yapma en iyi uygulamalar bölümünü inceleyin.