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