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:
Şekil 1'de, documents
kaynağıyla etkileşimde bulunan bir kullanıcı aşağıdaki bilgi akışına sahiptir:
- Uygulama, bir web sunucusunda
documents.create
yöntemini çağırır. - Web sunucusu, oluşturulan dokümanın örneğini
documents
kaynağı olarak içeren bir HTTP yanıtı gönderir. - İ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. - 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:
Şekil 2.'de, documents
kaynağıyla etkileşime giren bir kullanıcı aşağıdaki bilgi akışına sahiptir:
- Bir uygulama, bulunacak dosyanın
documentId
ile birlikte web sunucusundadocuments.get
yöntemini çağırır. - 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. - 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.
- 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. - 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.
İlgili konular
- Google Dokümanlar dokümanının yapısı
- İstekler ve yanıtlar
- Yapısal düzenleme kuralları ve davranışları
- En iyi sonuçları elde etmek için en iyi uygulamalar