Yorumları ve yanıtları yönetme

Yorumlar, kullanıcıların bir dosyayla ilgili geri bildirimleridir. Örneğin, bir kelime işlemci dokümanının okuyucusu, bir cümlenin nasıl yeniden ifade edileceğini önerebilir. İki tür yorum vardır: sabitlenmiş yorumlar ve sabitlenmemiş yorumlar. Sabitlenmiş yorumlar, bir dokümanın belirli bir sürümündeki kelime işlemci dokümanındaki bir cümle gibi belirli bir konumla ilişkilendirilir. Buna karşılık, sabitlenmemiş bir yorum yalnızca dokümanla ilişkilendirilir.

Yanıtlar, yorumlara eklenir ve kullanıcının yoruma verdiği cevabı gösterir. Drive API, kullanıcılarınızın uygulamanız tarafından oluşturulan dokümanlara yorum ve yanıt eklemesine olanak tanır. Yanıt içeren bir yorum, toplu olarak tartışma olarak bilinir.

Alanlar parametresini kullanma

comments kaynağındaki tüm yöntemler (delete hariç) için yanıtta döndürülecek alanları belirtmek üzere fields system parametresini ayarlamanız gerekir. Çoğu Drive kaynağı yönteminde bu işlem yalnızca varsayılan olmayan alanları döndürmek için gereklidir ancak comments kaynağı için zorunludur. fields parametresini atlarsanız yöntem hata döndürür. Daha fazla bilgi için Belirli alanları döndürme başlıklı makaleyi inceleyin.

Yorum sınırlamaları

Drive API ile sabitlenmiş ve sabitlenmemiş yorumlarla çalışırken aşağıdaki kısıtlamalar uygulanır:

Yorum türü Dosya türü
Sabitlenmiş
  • Geliştiriciler, sabitleme spesifikasyonu için kendi biçimlerini tanımlayabilir.
  • Yorum alınırken bağlantı kaydedilir ve döndürülür ancak Google Workspace düzenleyici uygulamaları bu yorumları bağlantısız yorumlar olarak ele alır.
Sabitlenmemiş
  • Google Workspace dokümanlarında desteklenir. Bu dokümanlarda yorumlar "Tüm Yorumlar" görünümünde gösterilir.
  • Sabitlenmemiş yorumlar, Drive dosya önizleyicisinde oluşturulan PDF'lerde gösterilmez ancak kaydedilir ve Drive API aracılığıyla alınabilir.

Dokümanın en son düzeltmesine sabitlenmiş yorum ekleme

Yorum eklediğinizde, yorumu dosyadaki bir bölgeye sabitlemek isteyebilirsiniz. Sabit nokta, bir yorumun atıfta bulunduğu dosyadaki bir bölgeyi tanımlar. comments kaynağı, anchor alanını JSON dizesi olarak tanımlar.

Sabitlenmiş yorum eklemek için:

  1. (İsteğe bağlı). Bir dokümana ait tüm list öğelerini listelemek için revisions kaynağında yöntemini çağırın.revisionID Bu adımı yalnızca bir yorumu en son düzeltme dışındaki bir düzeltmeye sabitlemek istiyorsanız uygulayın. En son düzeltmeyi kullanmak istiyorsanız revisionID için head sürümünü kullanın.

  2. fileID parametresi, yorumu içeren bir comments kaynağı ve revisionID (r) ile bölgeyi (a) içeren bir JSON bağlantı dizesiyle create yöntemini comments kaynağında çağırın.

Aşağıdaki kod örneğinde, sabitlenmiş yorumun nasıl oluşturulacağı gösterilmektedir:

Python


from google.oauth2.credentials import Credentials
from googleapiclient.errors import HttpError

# --- Configuration ---
# The ID of the file to comment on.
# Example: '1_aBcDeFgHiJkLmNoPqRsTuVwXyZ'
FILE_ID = 'FILE_ID'

# The text content of the comment.
COMMENT_TEXT = 'This is an example of an anchored comment.'

# The line number to anchor the comment to.
# Note: Line numbers are based on the revision.
ANCHOR_LINE = 10
# --- End of user-configuration section ---

SCOPES = ["https://www.googleapis.com/auth/drive"]

creds = Credentials.from_authorized_user_file("token.json", SCOPES)

def create_anchored_comment():
    """
    Create an anchored comment on a specific line in a Google Doc.

    Returns:
        The created comment object or None if an error occurred.
    """
    try:
        # Build the Drive API service
        service = build("drive", "v3", credentials=creds)

        # Define the anchor region for the comment.
        # For Google Docs, the region is typically defined by 'line' and 'revision'.
        # Other file types might use different region classifiers.
        anchor = {
            'region': {
                'kind': 'drive#commentRegion',
                'line': ANCHOR_LINE,
                'rev': 'head'
            }
        }

        # The comment body.
        comment_body = {
            'content': COMMENT_TEXT,
            'anchor': anchor
        }

        # Create the comment request.
        comment = (
            service.comments()
            .create(fileId=FILE_ID, fields="*", body=comment_body)
            .execute()
        )

        print(f"Comment ID: {comment.get('id')}")
        return comment

    except HttpError as error:
        print(f"An error occurred: {error}")
        return None

create_anchored_comment()

Drive API, comments dizesini içeren anchor kaynak nesnesinin bir örneğini döndürür.

Sabitlenmemiş yorum ekleme

Bağlanmamış bir yorum eklemek için create yöntemini fileId parametresi ve yorumu içeren bir comments kaynağıyla birlikte çağırın.

Yorum düz metin olarak eklenir ancak yanıt gövdesinde, gösterilecek şekilde biçimlendirilmiş içeriğin bulunduğu bir htmlContent alanı yer alır.

Aşağıdaki kod örneğinde, sabitlenmemiş bir yorumun nasıl oluşturulacağı gösterilmektedir:

Python


from google.oauth2.credentials import Credentials
from googleapiclient.errors import HttpError

# --- Configuration ---
# The ID of the file to comment on.
# Example: '1_aBcDeFgHiJkLmNoPqRsTuVwXyZ'
FILE_ID = 'FILE_ID'

# The text content of the comment.
COMMENT_TEXT = 'This is an example of an unanchored comment.'
# --- End of user-configuration section ---

SCOPES = ["https://www.googleapis.com/auth/drive"]

creds = Credentials.from_authorized_user_file("token.json", SCOPES)

def create_unanchored_comment():
    """
    Create an unanchored comment on a specific line in a Google Doc.

    Returns:
        The created comment object or None if an error occurred.
    """
    try:
        # Build the Drive API service
        service = build("drive", "v3", credentials=creds)

        # The comment body. For an unanchored comment,
        # omit the 'anchor' property.
        comment_body = {
            'content': COMMENT_TEXT
        }

        # Create the comment request.
        comment = (
            service.comments()
            .create(fileId=FILE_ID, fields="*", body=comment_body)
            .execute()
        )

        print(f"Comment ID: {comment.get('id')}")
        return comment

    except HttpError as error:
        print(f"An error occurred: {error}")
        return None

create_unanchored_comment()

Yoruma yanıt ekleme

Yoruma yanıt eklemek için fileId ve commentId parametreleriyle replies kaynağında create yöntemini kullanın. İstek gövdesinde, yanıtı eklemek için content alanı kullanılır.

Yanıt düz metin olarak eklenir ancak yanıt gövdesinde, görüntülenmek üzere biçimlendirilmiş içeriklerin bulunduğu bir htmlContent alanı sağlanır.

Yöntem, fields alanında listelenen alanları döndürür.

İstek

Bu örnekte, fileId ve commentId yol parametreleri ile birden fazla alan sağlanmaktadır.

POST https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID/replies?fields=id,comment

İstek metni

{
  "content": "This is a reply to a comment."
}

Yorumu çözüldü olarak işaretleme

Yorumlar yalnızca yanıtlanarak çözüme kavuşturulabilir.

Bir yorumu çözmek için fileId ve commentId parametreleriyle replies kaynağında create yöntemini kullanın.

İstek gövdesinde, yorumu çözmek için action alanı kullanılır. Ayrıca, yorumu kapatan bir yanıt eklemek için content alanını da ayarlayabilirsiniz.

Bir yorum çözümlendiğinde Drive, comments kaynağını resolved: true olarak işaretler. Silinen yorumlardan farklı olarak, çözülen yorumlar htmlContent veya content alanlarını içerebilir.

Uygulamanız bir yorumu çözdüğünde kullanıcı arayüzünüz, yorumun ele alındığını belirtmelidir. Örneğin, uygulamanız:

  • Başka yanıt verilmesine izin vermeyin ve önceki tüm yanıtların yanı sıra ilk yorumu soluklaştırın.
  • Sonlandırılan yorumları gizle'yi tıklayın.

İstek

Bu örnekte, fileId ve commentId yol parametreleri ile birden fazla alan sağlanmaktadır.

POST https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID/replies?fields=id,comment

İstek metni

{
  "action": "resolve",
  "content": "This comment has been resolved."
}

Yorum alma

Bir dosyayla ilgili yorum almak için get yöntemini comments kaynağında fileId ve commentId parametreleriyle birlikte kullanın. Yorum kimliğini bilmiyorsanız list yöntemini kullanarak tüm yorumları listeleyebilirsiniz.

Yöntem, comments kaynağının bir örneğini döndürür.

Silinen yorumları sonuçlara dahil etmek için includedDeleted sorgu parametresini true olarak ayarlayın.

İstek

Bu örnekte, fileId ve commentId yol parametreleri ile birden fazla alan sağlanmaktadır.

GET https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID?fields=id,comment,modifiedTime,resolved

Yorumları listeleme

Bir dosyadaki yorumları listelemek için list yöntemini comments kaynağında fileId parametresiyle kullanın. Yöntem, yorum listesi döndürür.

Yorumların sayfalandırmasını özelleştirmek veya yorumları filtrelemek için aşağıdaki sorgu parametrelerini iletin:

  • includeDeleted: Silinen yorumları dahil etmek için true olarak ayarlayın. Silinen yorumlar htmlContent veya content alanlarını içermez.

  • pageSize: Sayfa başına döndürülecek maksimum yorum sayısı.

  • pageToken: Önceki bir liste çağrısından alınan sayfa jetonu. Sonraki sayfayı almak için bu jetonu sağlayın.

  • startModifiedTime: Sonuç yorumları için modifiedTime alanının minimum değeri.

İstek

Bu örnekte, fileId yol parametresini, includeDeleted sorgu parametresini ve birden fazla alanı sağlıyoruz.

GET https://www.googleapis.com/drive/v3/files/FILE_ID/comments?includeDeleted=true&fields=(id,comment,kind,modifiedTime,resolved)

Yorumu güncelleme

Bir dosyayla ilgili yorumu güncellemek için fileId ve commentId parametreleriyle comments kaynağında update yöntemini kullanın. İstek gövdesinde, yorumu güncellemek için content alanı kullanılır.

comments kaynağındaki boolean resolved alanı salt okunurdur. Yorumlar yalnızca yanıtlanarak çözüme kavuşturulabilir. Daha fazla bilgi için Yorumları yanıtlama başlıklı makaleyi inceleyin.

Yöntem, fields sorgu parametresinde listelenen alanları döndürür.

İstek

Bu örnekte, fileId ve commentId yol parametreleri ile birden fazla alan sağlanmaktadır.

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID?fields=id,comment

İstek metni

{
  "content": "This comment is now updated."
}

Yorum silme

Bir dosyayla ilgili yorumu silmek için fileId ve commentId parametreleriyle comments kaynağında delete yöntemini kullanın.

Bir yorum silindiğinde Drive, yorum kaynağını deleted: true olarak işaretler. Silinen yorumlar htmlContent veya content alanlarını içermez.

İstek

Bu örnekte, fileId ve commentId yol parametreleri sağlanmaktadır.

DELETE https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID