Doküman

Bu kılavuzda, Google Dokümanlar API'yi oluşturan birincil yöntemler, bir dokümana erişme ve doküman oluştururken 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ö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 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 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. Dokümanlar API istek 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 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

Kullanıcının Drive'ım bölümündeki bir dokümanı almak için genellikle önce Drive'ın files.list yöntemini kullanarak dosyanın kimliğini almanız gerekir. Yöntemi herhangi bir parametre olmadan çağırmak, kullanıcının kimlikleri dahil tüm dosya ve klasörlerinin 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'tür. 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 başlıklı makaleyi inceleyin.

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 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 bir yöntemle birlikte 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 dosyanın meta verilerini 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ı alma

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şturmak ve 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 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.

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 (hangi öğelerden oluştuğunu, bu öğelerde hangi içeriğin bulunduğunu ve dokümandaki öğelerin sırasını) 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 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ö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 planlama başlıklı en iyi uygulamalar bölümüne bakın.