Zarządzanie komentarzami i odpowiedziami

Komentarze to opinie użytkowników dotyczące pliku, np. sugestie czytelnika dokumentu tekstowego dotyczące zmiany brzmienia zdania. Istnieją 2 rodzaje komentarzy: komentarze zakotwiczone i komentarze niezakotwiczone. Komentarz zakotwiczony jest powiązany z konkretnym miejscem, np. zdaniem w dokumencie tekstowym, w określonej wersji dokumentu. Z kolei komentarz niezakotwiczony 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 z odpowiedziami jest określany jako dyskusja.

Używanie parametru fields

W przypadku wszystkich metod (z wyjątkiem delete) w zasobie comments musisz ustawić parametrfields systemowy aby określić pola, które mają być zwracane w odpowiedzi. W większości metod zasobów Dysku ta czynność jest wymagana tylko w przypadku zwracania pól innych niż domyślne, ale w przypadku zasobu comments jest obowiązkowa. Jeśli pominiesz parametr fields, metoda zwróci błąd. Więcej informacji znajdziesz w sekcji Zwracanie określonych pól.

Ograniczenia dotyczące komentarzy

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

Typ komentarzy	Typ pliku
Zakotwiczone	Deweloperzy mogą zdefiniować własny format specyfikacji kotwicy. Kotwica jest zapisywana i zwracana podczas pobierania komentarza, ale aplikacje edytora Google Workspace traktują te komentarze jako niezakotwiczone.
Niezakotwiczone	Obsługiwane w dokumentach Google Workspace, które będą wyświetlać je w widoku „Wszystkie komentarze”. Komentarze niezakotwiczone 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 komentarza zakotwiczonego do najnowszej wersji dokumentu

Podczas dodawania komentarza możesz go zakotwiczyć w regionie pliku. Kotwica określa region w pliku, do którego odnosi się komentarz. Zasób comments definiuje pole anchor jako ciąg JSON.

Ważne: kotwice są niezmienne, a ich położenie względem treści dokumentu nie jest gwarantowane między wersjami. Zalecamy używanie kotwic w dokumentach, w których położenie się nie zmienia, np. w plikach graficznych lub dokumentach tylko do odczytu.

Aby dodać komentarz zakotwiczony:

1. Opcjonalnie: wywołaj metodę list w zasobie revisions, aby wyświetlić listę wszystkich revisionID dokumentu. Wykonaj ten krok tylko wtedy, gdy chcesz zakotwiczyć komentarz w wersji innej niż najnowsza. Jeśli chcesz użyć najnowszej wersji, użyj head jako revisionID.

2. Wywołaj metodę create w zasobie comments z parametrem fileID , zasobem comments zawierającym komentarz oraz ciągiem 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 anchor.

Uwaga: zalecamy sprawdzenie, czy użytkownik ma odpowiednie uprawnienia do dodawania komentarzy. Ponadto tylko autor komentarza lub odpowiedzi może usunąć lub edytować komentarz lub odpowiedź. Błędy występują, gdy osoba, która nie jest autorem, próbuje usunąć lub edytować komentarz. Aby uniknąć tych błędów, sprawdź pole author.me w zasobie komentarzy.

Dodawanie komentarza niezakotwiczonego

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

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

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

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

Ważne: zalecamy sprawdzenie, czy użytkownik ma odpowiednie uprawnienia do dodawania komentarzy. Ponadto tylko autor komentarza lub odpowiedzi może usunąć lub edytować komentarz lub odpowiedź. Błędy występują, gdy użytkownik, który nie jest autorem, próbuje usunąć lub edytować komentarz. Aby uniknąć tych błędów, sprawdź pole author.me w zasobie comments, aby upewnić się, że użytkownik wysyłający żądanie jest autorem komentarza, a następnie sprawdź jego uprawnienia względem komentarza.

Dodawanie odpowiedzi do komentarza

Aby dodać odpowiedź do komentarza, użyj create metody w replies zasobie z fileId i commentId parametrami. 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świetlenia.

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 zamknąć tylko przez opublikowanie odpowiedzi na komentarz.

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

Treść żądania używa pola action do zamknięcia komentarza. Możesz też ustawić pole content, aby dodać odpowiedź, która zamyka 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 zamknie komentarz, interfejs użytkownika powinien wskazywać, że komentarz został rozwiązany. Na przykład aplikacja może:

• Zablokować dalsze odpowiedzi i przyciemnić wszystkie poprzednie odpowiedzi oraz oryginalny komentarz.
• Ukryć 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 pobrać komentarz do pliku, użyj get metody 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ć usunięte komentarze w wynikach, ustaw includedDeleted parametr zapytania 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 do pliku, użyj list metody w zasobie comments z fileId parametrem. 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 komentarzach wynikowych.

Żądanie

W tym przykładzie podajemy parametr ścieżki fileId, parametr zapytania includeDeleted oraz 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 do pliku, użyj metody update w zasobie comments z parametrami fileId i commentId. Treść żądania używa pola content do zaktualizowania komentarza.

Pole logiczne resolved w zasobie comments jest tylko do odczytu. Komentarz można zamknąć tylko przez opublikowanie odpowiedzi na komentarz. Więcej informacji znajdziesz w sekcji Kończenie wątku komentarza.

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

Powiązane artykuły

• Omówienie plików i folderów
• Zarządzanie wersjami plików