Zarządzanie komentarzami i odpowiedziami

Komentarze to opinie użytkowników na temat pliku, np. czytelnik dokumentu tekstowego sugeruje, jak przeformułować zdanie. Istnieją 2 rodzaje komentarzy: zakotwiczone i niezakotwiczone. Zakotwiczony komentarz jest powiązany z konkretnym miejscem, np. zdaniem w dokumencie tekstowym, w określonej wersji dokumentu. Z kolei niezakotwiczony komentarz jest powiązany tylko z dokumentem.

Odpowiedzi są dołączane do komentarzy i stanowią reakcję użytkownika na komentarz. Interfejs Drive API umożliwia użytkownikom dodawanie komentarzy i odpowiedzi do dokumentów utworzonych przez Twoją aplikację. Komentarz wraz z odpowiedziami jest nazywany dyskusją.

Używanie parametru fields

W przypadku wszystkich metod (z wyjątkiem delete) w zasobie comments musisz ustawić parametr fields system, aby określić pola, które mają być zwracane w odpowiedzi. W większości metod zasobu Drive to działanie jest wymagane tylko w przypadku zwracania pól innych niż domyślne, ale jest obowiązkowe w przypadku zasobu comments. Jeśli pominiesz parametr fields, metoda zwróci błąd. Więcej informacji znajdziesz w artykule Zwracanie określonych pól.

Ograniczenia dotyczące komentarzy

Podczas pracy z zakotwiczonymi i niezakotwiczonymi komentarzami w interfejsie Drive API obowiązują te ograniczenia:

Typ komentarzy Typ pliku
Zakotwiczona
  • Deweloperzy mogą zdefiniować własny format specyfikacji elementu kotwiczącego.
  • Kotwica jest zapisywana i zwracana podczas pobierania komentarza, ale aplikacje edytora Google Workspace traktują te komentarze jako niezakotwiczone.
Nieprzypięte
  • Są one obsługiwane w dokumentach Google Workspace, w których będą widoczne w widoku „Wszystkie komentarze”.
  • Nieprzytwierdzone komentarze nie są wyświetlane w plikach PDF renderowanych w przeglądarce plików na Dysku, ale są zapisywane i można je pobrać za pomocą interfejsu Drive API.

Dodawanie zakotwiczonego komentarza do najnowszej wersji dokumentu

Gdy dodajesz komentarz, możesz go przypiąć do regionu w pliku. Kotwica określa region w pliku, do którego odnosi się komentarz. Zasób comments określa pole anchor jako ciąg znaków JSON.

Aby dodać komentarz zakotwiczony:

  1. Opcjonalnie: Wywołaj metodę list w zasobie revisions, aby wyświetlić wszystkie revisionID w dokumencie. Wykonaj ten krok tylko wtedy, gdy chcesz przypiąć komentarz do wersji innej niż najnowsza. Jeśli chcesz użyć najnowszej wersji, użyj head w przypadku revisionID.

  2. Wywołaj metodę create w zasobie comments z parametrem fileID, zasobem comments zawierającym komentarz i ciągiem zakotwiczenia JSON zawierającym revisionID (r) i region (a).

Poniższy przykładowy kod pokazuje, jak utworzyć komentarz zakotwiczony:

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()

Interfejs Drive API zwraca instancję obiektu zasobu comments, która zawiera ciąg znaków anchor.

Dodawanie niezakotwiczonego komentarza

Aby dodać niezakotwiczony komentarz, wywołaj metodę create z parametrem fileId i zasobem comments zawierającym komentarz.

Komentarz jest wstawiany jako zwykły tekst, ale treść odpowiedzi zawiera pole htmlContent z treścią sformatowaną do wyświetlania.

Poniższy przykładowy kod pokazuje, jak utworzyć niezakotwiczony komentarz:

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()

Dodawanie odpowiedzi na komentarz

Aby dodać odpowiedź na komentarz, użyj metody create w zasobie replies z parametrami fileId i commentId. Treść żądania używa pola content do dodania odpowiedzi.

Odpowiedź jest wstawiana jako zwykły tekst, ale treść odpowiedzi zawiera pole htmlContent z treścią sformatowaną do wyświetlania.

Metoda zwraca pola wymienione w polu fields.

Żądanie

W tym przykładzie podajemy parametry ścieżki fileId i commentId oraz kilka pól.

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

Treść żądania

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

Kończenie wątku komentarza

Komentarz można rozwiązać tylko przez opublikowanie odpowiedzi na niego.

Aby rozwiązać komentarz, użyj metody create w zasobie replies z parametrami fileId i commentId.

Treść żądania używa pola action do rozwiązania komentarza. Możesz też ustawić pole content, aby dodać odpowiedź, która zamknie komentarz.

Gdy komentarz zostanie zamknięty, Dysk oznaczy zasób comments jako resolved: true. W przeciwieństwie do usuniętych komentarzy zamknięte komentarze mogą zawierać pola htmlContent lub content.

Gdy aplikacja rozwiąże problem zgłoszony w komentarzu, interfejs powinien wskazywać, że został on rozwiązany. Na przykład aplikacja może:

  • Zablokuj możliwość dodawania kolejnych odpowiedzi i przyciemnij wszystkie poprzednie odpowiedzi oraz oryginalny komentarz.
  • Ukryj zakończone komentarze.

Żądanie

W tym przykładzie podajemy parametry ścieżki fileId i commentId oraz kilka pól.

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

Treść żądania

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

Pobieranie komentarza

Aby uzyskać komentarz do pliku, użyj metody get w zasobie comments z parametrami fileId i commentId. Jeśli nie znasz identyfikatora komentarza, możesz wyświetlić listę wszystkich komentarzy za pomocą metody list.

Metoda zwraca instancję zasobu comments.

Aby uwzględnić w wynikach usunięte komentarze, ustaw parametr zapytania includedDeleted na true.

Żądanie

W tym przykładzie podajemy parametry ścieżki fileId i commentId oraz kilka pól.

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

Wyświetlanie listy komentarzy

Aby wyświetlić listę komentarzy w pliku, użyj metody list w zasobie comments z parametrem fileId. Metoda zwraca listę komentarzy.

Aby dostosować paginację lub filtrowanie komentarzy, przekaż te parametry zapytania:

  • includeDeleted: ustaw na true, aby uwzględnić usunięte komentarze. Usunięte komentarze nie zawierają pól htmlContent ani content.

  • pageSize: maksymalna liczba komentarzy do zwrócenia na stronie.

  • pageToken: token strony otrzymany z poprzedniego wywołania listy. Podaj ten token, aby pobrać następną stronę.

  • startModifiedTime: minimalna wartość pola modifiedTime w przypadku komentarzy do wyników.

Żądanie

W tym przykładzie podajemy parametr ścieżki fileId, parametr zapytania includeDeleted i kilka pól.

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

Aktualizowanie komentarza

Aby zaktualizować komentarz w pliku, użyj metody update w zasobie comments z parametrami fileId i commentId. Aby zaktualizować komentarz, w treści żądania użyj pola content.

Pole logiczne resolved w zasobie comments jest tylko do odczytu. Komentarz można zamknąć tylko przez opublikowanie odpowiedzi na niego. Więcej informacji znajdziesz w artykule Rozwiązywanie problemów z komentarzami.

Metoda zwraca pola wymienione w parametrze zapytania fields.

Żądanie

W tym przykładzie podajemy parametry ścieżki fileId i commentId oraz kilka pól.

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

Treść żądania

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

Usuwanie komentarzy

Aby usunąć komentarz do pliku, użyj metody delete w zasobie comments z parametrami fileId i commentId.

Gdy komentarz zostanie usunięty, Dysk oznaczy zasób komentarza jako deleted: true. Usunięte komentarze nie zawierają pól htmlContent ani content.

Żądanie

W tym przykładzie podajemy parametry ścieżki fileId i commentId.

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