Google Dokümanlar, ortak çalışanların yorum yazarak ve onay bekleyen ertelenmiş düzenlemeler olarak önerilerde bulunarak ortak çalışma yapmasına olanak tanır.
API'yi kullanarak önerilen değişiklikleri doküman metninde satır içi olarak görüntüleyebilirsiniz. Geliştirici Önizlemesi'nde yorum ve öneri dizilerini programatik olarak okuyabilir, oluşturabilir, yanıtlayabilir, güncelleyebilir veya silebilirsiniz.
Doküman içeriğini getirmek için documents.get yöntemini kullandığınızda içerikte çözümlenmemiş öneriler olabilir. documents.get'nin önerileri nasıl temsil edeceğini kontrol etmek için isteğe bağlı SuggestionsViewMode parametresini kullanın. Bu parametreyle aşağıdaki filtre koşulları kullanılabilir:
SUGGESTIONS_INLINEile içerik alın. Böylece, silinmeyi veya eklenmeyi bekleyen metinler dokümanda görünür.- Tüm öneriler kabul edilmiş şekilde içeriği önizleme olarak alma
- İçeriği önizleme olarak, öneriler olmadan ve tüm öneriler reddedilmiş şekilde alma.
SuggestionsViewMode sağlamazsanız Google Dokümanlar API'si, mevcut kullanıcının ayrıcalıklarına uygun bir varsayılan ayar kullanır.
Öneriler ve dizinler
SuggestionsViewMode karakterinin önemli olmasının bir nedeni, yanıttaki dizinlerin, aşağıda gösterildiği gibi öneri olup olmamasına bağlı olarak değişebilmesidir.
| Öneriler içeren içerik | Önerisiz içerik |
|---|---|
{
"tabs": [
{
"documentTab": {
"body": {
"content": [
{
"startIndex": 1,
"endIndex": 31,
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 31,
"textRun": {
"content": "Text preceding the suggestion\n",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
},
{
"startIndex": 31,
"endIndex": 51,
"paragraph": {
"elements": [
{
"startIndex": 31,
"endIndex": 50,
"textRun": {
"content": "Suggested insertion",
"suggestedInsertionIds": [
"suggest.vcti8ewm4mww"
],
"textStyle": {}
}
},
{
"startIndex": 50,
"endIndex": 51,
"textRun": {
"content": "\n",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
},
{
"startIndex": 51,
"endIndex": 81,
"paragraph": {
"elements": [
{
"startIndex": 51,
"endIndex": 81,
"textRun": {
"content": "Text following the suggestion\n",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
}
}
}
]
},
|
{
"tabs": [
{
"documentTab": {
"body": {
"content": [
{
"startIndex": 1,
"endIndex": 31,
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 31,
"textRun": {
"content": "Text preceding the suggestion\n",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
},
{
"startIndex": 31,
"endIndex": 32,
"paragraph": {
"elements": [
{
"startIndex": 31,
"endIndex": 32,
"textRun": {
"content": "\n",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
},
{
"startIndex": 32,
"endIndex": 62,
"paragraph": {
"elements": [
{
"startIndex": 32,
"endIndex": 62,
"textRun": {
"content": "Text following the suggestion\n",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
}
}
}
]
},
|
Yukarıdaki yanıtta, "Öneriden sonraki metin" satırını içeren paragrafta SuggestionsViewMode kullanıldığında oluşan fark gösteriliyor. Değer SUGGESTIONS_INLINE olarak ayarlandığında ParagraphElement öğesinin startIndex değeri 51'den başlar ve endIndex değeri 81'de durur. Öneri olmadan startIndex ve endIndex aralığı 32-62'dir.
Öneriler olmadan içerik alma
Aşağıdaki kısmi kod örneğinde, SuggestionsViewMode parametresi PREVIEW_WITHOUT_SUGGESTIONS olarak ayarlanarak tüm öneriler (varsa) reddedilmiş şekilde bir dokümanın nasıl önizleme olarak alınacağı gösterilmektedir.
Java
final string SUGGEST_MODE = "PREVIEW_WITHOUT_SUGGESTIONS"; Document doc = service .documents() .get(DOCUMENT_ID) .setIncludeTabsContent(true) .setSuggestionsViewMode(SUGGEST_MODE) .execute();
Python
SUGGEST_MODE = "PREVIEW_WITHOUT_SUGGESTIONS" result = ( service.documents() .get( documentId=DOCUMENT_ID, includeTabsContent=True, suggestionsViewMode=SUGGEST_MODE, ) .execute() )
SuggestionsViewMode parametresinin atlanması, parametre değeri olarak DEFAULT_FOR_CURRENT_ACCESS değerinin sağlanmasına eşdeğerdir.
Stil önerileri
Dokümanlarda stil önerileri de olabilir. Bunlar, içerikteki değişikliklerden ziyade biçimlendirme ve sunumla ilgili önerilen değişikliklerdir.
Metin ekleme veya silme işlemlerinin aksine, bunlar dizinleri kaydırmaz. TextRun karakterini daha küçük parçalara ayırabilirler ancak yalnızca önerilen stil değişikliğiyle ilgili ek açıklamalar eklerler.
Bu tür ek açıklamalardan biri olan SuggestedTextStyle, 2 bölümden oluşur:
textStyle: Metnin, önerilen değişiklikten sonra nasıl biçimlendirildiğini açıklar ancak neyin değiştiğini belirtmez.Önerinin
textStylealanlarını nasıl değiştirdiğini belirtentextStyleSuggestionState.
Bunu, önerilen stil değişikliğini içeren aşağıdaki doküman sekmesi alıntısında görebilirsiniz:
[01] "paragraph": {
[02] "elements": [
[03] {
[04] "endIndex": 106,
[05] "startIndex": 82,
[06] "textRun": {
[07] "content": "Some text that does not ",
[08] "textStyle": {}
[09] }
[10] },
[11] {
[12] "endIndex": 115,
[13] "startIndex": 106,
[14] "textRun": {
[15] "content": "initially",
[16] "suggestedTextStyleChanges": {
[17] "suggest.xymysbs9zldp": {
[18] "textStyle": {
[19] "backgroundColor": {},
[20] "baselineOffset": "NONE",
[21] "bold": true,
[22] "fontSize": {
[23] "magnitude": 11,
[24] "unit": "PT"
[25] },
[26] "foregroundColor": {
[27] "color": {
[28] "rgbColor": {}
[29] }
[30] },
[31] "italic": false,
[32] "smallCaps": false,
[33] "strikethrough": false,
[34] "underline": false
[35] },
[36] "textStyleSuggestionState": {
[37] "boldSuggested": true,
[38] "weightedFontFamilySuggested": true
[39] }
[40] }
[41] },
[42] "textStyle": {
[43] "italic": true
[44] }
[45] }
[46] },
[47] {
[48] "endIndex": 143,
[49] "startIndex": 115,
[50] "textRun": {
[51] "content": " contain any boldface text.\n",
[52] "textStyle": {}
[53] }
[54] }
[55] ],
[56] "paragraphStyle": {
[57] "direction": "LEFT_TO_RIGHT",
[58] "namedStyleType": "NORMAL_TEXT"
[59] }
[60] }
Yukarıdaki örnekte paragraf, 6, 14 ve 50. satırlardan başlayan 3 metin çalıştırmasından oluşuyor. Ortadaki metin çalıştırmasını inceleyin:
- 16. satır:
suggestedTextStyleChangesnesnesi var. - 18. satır:
textStyle, çeşitli biçimlendirmeleri belirtir. - 36. satır:
textStyleSuggestionState, bu spesifikasyonun yalnızca kalın yazılan kısmının öneri olduğunu gösterir. - 42. satır: Bu metin çalıştırmasının italik stili, mevcut belgenin bir parçasıdır (ve öneriden etkilenmez).
Öneriye yalnızca textStyleSuggestionState bölümünde true olarak ayarlanan stil özellikleri dahil edilir.
Yorum oluşturma ve yönetme
documents.batchUpdate yöntemini kullanarak yorum ve yanıt ekleyebilir, yorumları düzenleyebilir, yorumları veya yanıtları silebilirsiniz.
Yorum veya öneri içeren toplu güncellemeler yaparken olası kısmi hataları izlemeniz gerekir. Daha fazla bilgi için Yorum ve öneri güncelleme durumu başlıklı makaleyi inceleyin.
Yorum ekleme
Yorum dizisi eklemek için InsertCommentRequest nesnesini kullanın. Yorum metni içeriğini ve yorumun eklendiği bir bağlantı konumu (ör. aralık) sağlamanız gerekir.
Aşağıdaki JSON örneği, belirtilen aralığa atanmamış bir yorum dizisi ekler:
{
"requests": [
{
"insertComment": {
"content": "This is a comment added via the API.",
"range": {
"startIndex": 10,
"endIndex": 25
}
}
}
]
}
assigneeEmailAddress alanına e-posta adresini girerek yorumu belirli bir kullanıcıya atayabilirsiniz:
{
"requests": [
{
"insertComment": {
"content": "Please review this paragraph.",
"assigneeEmailAddress": "user@example.com",
"range": {
"startIndex": 10,
"endIndex": 25
}
}
}
]
}
Yanıt ekleme veya işlem yapma
Bir yorum veya öneri dizisini yanıtlamak ya da bir diziyi çözmek veya yeniden açmak için AddCommentReplyRequest simgesini kullanın.
Yanıt, Post nesnesiyle gösterilir.
Post nesnesi, yanıt content'yi içerir ve isteğe bağlı olarak bir commentAction belirtebilir (iş parçacığını RESOLVE veya REOPEN için).
Aşağıda, mevcut bir yorum dizisine verilen örnek yanıtlar yer almaktadır:
{
"requests": [
{
"addCommentReply": {
"commentId": "comment_thread_id",
"post": {
"content": "Replying to the comment thread."
}
}
}
]
}
Aşağıdaki örnekte, içerik gerektirmeyen bir yorum dizisi çözülüyor:
{
"requests": [
{
"addCommentReply": {
"commentId": "comment_thread_id",
"post": {
"commentAction": "RESOLVE"
}
}
}
]
}
Yayını düzenleme
Yazdığınız bir gönderinin metin içeriğini düzenlemek için UpdateCommentPostRequest simgesini kullanın.
İş parçacığı kimliğini (commentId veya suggestionId), düzenlemek istediğiniz yayının postId değerini ve yeni düz metni content belirtmeniz gerekir.
Öneri dizisinin ana gönderisini düzenleyemeyeceğinizi unutmayın (çünkü bu gönderiler, öneri modunda yapılan düzenlemelerle oluşturulur).
{
"requests": [
{
"updateCommentPost": {
"commentId": "comment_thread_id",
"postId": "post_id",
"content": "This is the updated comment text."
}
}
]
}
Yorumları ve yanıtları silme
- Yorum dizisini silme: Yorum dizisinin tamamını kaldırmak için
DeleteCommentRequestsimgesini kullanın. Yorum dizisini yalnızca dizinin ilk yayınının yazarıysanız silebilirsiniz. - Yanıt silme: Belirli bir yanıt yayınını silmek için
DeleteCommentReplyRequestsimgesini kullanın. Yalnızca kendi yanıtlarınızı silebilirsiniz. İşlemler veya atananlar içeren yanıt gönderilerini silemezsiniz.
Aşağıdaki örnekte bir yorum dizisi silinir:
{
"requests": [
{
"deleteComment": {
"commentId": "comment_thread_id"
}
}
]
}
Yazma önerileri ve öneri dizilerini yönetme
Düzenlemeleri doğrudan düzenleme yerine öneri olarak yazabilir ve öneri dizilerini programatik olarak kabul edebilir, reddedebilir veya silebilirsiniz.
Önerileri içeren toplu güncellemeler yaparken olası kısmi hataları izlemeniz gerekir. Daha fazla bilgi için Yorum ve öneri güncelleme durumu başlıklı makaleyi inceleyin.
Öneri modunu kullanarak öneri oluşturma
Düzenlemeleri öneri olarak uygulamak için toplu güncelleme isteğinizde WriteControl nesnesinin writeMode alanını SUGGEST olarak ayarlayın. İstekteki tüm güncellemeler öneri olarak işlenir.
{
"requests": [
{
"insertText": {
"text": "suggested insertion text",
"location": {
"index": 1
}
}
}
],
"writeControl": {
"writeMode": "SUGGEST"
}
}
Öneri modunda desteklenmeyen istekler
WriteMode.SUGGEST kullanılırken aşağıdaki istek türleri desteklenmez ve hata döndürür:
AddDocumentTabCreateNamedRangeDeleteFooterDeleteHeaderDeleteNamedRangeDeleteTabUpdateDocumentTabPropertiesUpdateTableColumnProperties
Ayrıca, doküman biçimi veya üstbilgi/altbilgi ayarlarıyla ilgili değişiklik önermezsiniz. UpdateDocumentStyle'da aşağıdaki stil türleri için öneriler desteklenmez:
documentFormatuseEvenPageHeaderFooteruseFirstPageHeaderFooter
Öneri dizilerini kabul etme, reddetme veya silme
Aşağıdaki istekleri kullanarak öneri ileti dizilerini yönetebilirsiniz:
- Öneriyi kabul etme: Öneriyi kabul etmek için
AcceptSuggestionRequesttuşunu kullanın. Bu işlem için dokümana düzenleme erişimi gerekir. - Öneriyi reddetme: Öneriyi reddetmek için
RejectSuggestionRequestsimgesini kullanın. Bunun için dokümana düzenleme erişiminizin olması veya önerinin yazarı olmanız gerekir. - Öneriyi silme: Öneriyi silmek için
DeleteSuggestionRequestsimgesini kullanın. Bunun için önerinin yazarı olmanız gerekir.
Aşağıdaki örnekte bir öneri ileti dizisi kabul ediliyor:
{
"requests": [
{
"acceptSuggestion": {
"suggestionId": "suggestion_thread_id"
}
}
]
}
Yorum ve öneri güncelleme durumu
Yorum veya öneri dizilerinin kaydedilmesini gerektiren isteklerde (ör. yorum ekleme, yanıt ekleme veya öneride bulunma) kısmi hatalar yaşanabilir. Bu gibi durumlarda, doküman modelindeki değişiklikler (ör. metin ekleme veya silme) Dokümanlar modeline başarıyla işlenebilir ancak ilişkili yorumlar veya öneriler kaydedilemeyebilir.
Yorum veya öneri güncellemelerinin başarıyla uygulanıp uygulanmadığını BatchUpdateDocumentResponse bölümündeki commentUpdateState alanını kontrol ederek doğrulayabilirsiniz.
Aşağıdaki durumlar CommentUpdateState içinde döndürülür:
NO_UPDATES_REQUESTED: Toplu işlemde yorum veya öneri güncellemeleri istenmedi.ALL_SAVED: İstenen tüm yorum veya öneri güncellemeleri başarıyla uygulandı.ALL_FAILED_UNKNOWN_REASON: Dokümanlar model değişiklikleri kaydedilmiş olsa bile, istenen tüm yorum veya öneri güncellemeleri kaydedilemedi.