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: zakotwiczone i niezakotwiczone. Komentarz zakotwiczony jest powiązany z konkretnym miejscem, np. z konkretnym 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 Google Drive API umożliwia użytkownikom dodawanie komentarzy i odpowiedzi do dokumentów utworzonych przez Twoją aplikację. Komentarz z odpowiedziami jest nazywany dyskusją.

Używanie parametru fields

W przypadku wszystkich metod (z wyjątkiem delete) w zasobie comments musisz ustawić parametrfields systemowy to określić pola, które mają zostać zwrócone w odpowiedzi. W większości metod zasobów Dysku Google ta czynność jest wymagana tylko w przypadku, gdy chcesz zwrócić pola inne niż domyślne, ale w przypadku zasobu comments jest ona obowiązkowa. 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 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.
  • Podczas pobierania komentarzy w plikach Google Workspace (takich jak Dokumenty, Arkusze lub Prezentacje Google) utworzonych w edytorze pole anchor zawiera wewnętrzne dane kotwicy specyficzne dla edytora (np. ciąg JSON workbook-range w plikach Arkuszy). Interfejs Drive API traktuje te dane jako nieprzezroczyste i nie może rozpoznawać wewnętrznych regionów dokumentu, współrzędnych komórek ani elementów slajdów. Aby pracować z komentarzami zakotwiczonymi bezpośrednio w tych typach plików, użyj odpowiednich interfejsów API: Google Docs API, Google Sheets API lub Google Slides API.
Niezakotwiczone
  • Obsługiwane w dokumentach Google Workspace, które wyświetlają 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

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.

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 i ciągiem JSON kotwicy zdefiniowanym przez Twoją aplikację.

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

Python

import json

from google.oauth2.credentials import Credentials
from googleapiclient.discovery import build
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 in your application to anchor the comment to.
# Note: Google Workspace editor apps (such as Google Docs, Sheets, and
# Slides) treat comments created using the Drive API as unanchored
# comments. Custom anchors are intended for your own applications or
# custom file viewers.
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 with a custom application-defined anchor.

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

        # Define a custom anchor specification for your application.
        # The Drive API stores the anchor as an opaque string. Your custom
        # application or file viewer can parse this JSON string to position
        # the comment in your UI.
        anchor_data = {
            'line': ANCHOR_LINE,
            'revision': 'head'
        }

        # The comment body. The 'anchor' field must be a serialized
        # JSON string.
        comment_body = {
            'content': COMMENT_TEXT,
            'anchor': json.dumps(anchor_data)
        }

        # 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.

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 pole htmlContent z treścią sformatowaną do wyświetlania.

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

Python


from google.oauth2.credentials import Credentials
from googleapiclient.discovery import build
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 file in Drive.

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

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 Google 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 includeDeleted 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 filtrować komentarze, 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 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 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 niego. 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 Google 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