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, öneriler olmadan ve tüm öneriler reddedilmiş şekilde önizleme olarak alma.
SuggestionsViewMode değerini sağlamazsanız Google Dokümanlar API'si, mevcut kullanıcının ayrıcalıklarına uygun bir varsayılan ayar kullanır.
Bir doküman getirilirken yorumların dahil edilip edilmeyeceğini kontrol etmek için isteğe bağlı commentsViewMode parametresini kullanın. commentsViewMode özelliğini COMMENTS_VIEW_MODE_INCLUDED olarak ayarlarsanız includeTabsContent özelliğini de true olarak ayarlamanız gerekir. Ayrıca, tabs alanına (veya herhangi bir alt alana) referans veren bir alan maskesi kullanırsanız API, isteği includeTabsContent alanını true olarak ayarlamışsınız gibi değerlendirir.
Öneriler ve dizinler
SuggestionsViewMode simgesinin önemli olmasının bir nedeni, yanıttaki dizinlerin öneri olup olmamasına bağlı olarak değişebilmesidir. Bu durum, aşağıdaki örnekte gösterilmiştir.
| Ö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"
}
}
}
]
}
}
}
]
},
|
Önceki yanıttaki "Text following the
suggestion" 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.
Öneri 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 de SuggestedTextStyle şeklindedir ve 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] }
Önceki örnekte paragraf, 6, 14 ve 50. satırlarda başlayan üç 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).
Ayrıca, Post nesnesinde yeni bir assigneeEmail belirterek yorum dizisini yeniden atayabilirsiniz.
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"
}
}
}
]
}
Aşağıdaki JSON örneğinde, yorum dizisinin nasıl yeniden atanacağı gösterilmektedir:
{
"requests": [
{
"addCommentReply": {
"commentId": "comment_thread_id",
"post": {
"content": "Replying to the comment thread.",
"assigneeEmail": "user@example.com"
}
}
}
]
}
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. Yalnızca yorum dizisinin ilk gönderisinin yazarıysanız yorum dizisini 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"
}
}
]
}
Öneri yazma ve öneri dizilerini yönetme
Düzenlemeleri doğrudan düzenleme olarak değil, ö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 ve 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.