Zarządzanie komentarzami i odpowiedziami

Komentarze to opinie użytkowników na temat pliku, np. sugestia od czytelnika dokumentu edytora tekstu dotycząca tego, jak przeformułować zdanie. Istnieją 2 typy komentarzy: zakotwiczone i niezakotwiczone. Komentarz zakotwiczony jest powiązany z konkretną lokalizacją, np. zdaniem w dokumencie edytora tekstu, w określonej wersji dokumentu. Natomiast niezakotwiczony komentarz jest powiązany tylko z dokumentem.

Odpowiedzi są dołączane do komentarzy i reprezentują odpowiedź użytkownika na dany komentarz. Interfejs API Dysku umożliwia użytkownikom dodawanie komentarzy i odpowiedzi do dokumentów utworzonych przez Twoją aplikację. Komentarze z odpowiedziami nazywane są dyskusją.

Aby określić, które pola mają być zwracane w odpowiedzi podczas wywoływania każdej metody wymienionej w zasobie comments, musisz ustawić parametr fields. Jeśli pominiesz ten parametr, metoda zwróci błąd. Aby zwrócić konkretne pola, zapoznaj się z artykułem Zwracanie określonych pól.

Dodawanie niezakotwiczonego komentarza

Aby dodać do dokumentu 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.

Dodawanie odpowiedzi na komentarz

Aby dodać odpowiedź na komentarz, użyj metody replies.create() zasobu 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.

Pokaż przykład

Wyślij prośbę

W tym przykładzie podajemy parametry ścieżki fileId i commentId oraz wiele 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 komentarz.

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

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

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

Gdy aplikacja rozwiąże problem, interfejs użytkownika powinien wskazywać, że komentarz został rozwiązany. Aplikacja może na przykład:

  • zablokować możliwość dodawania kolejnych odpowiedzi i przyciemnić wszystkie wcześniejsze odpowiedzi oraz oryginalny komentarz.
  • ukrywać zakończone komentarze.

Pokaż przykład

Wyślij prośbę

W tym przykładzie podajemy parametry ścieżki fileId i commentId oraz wiele 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."
}

Dodawanie zakotwiczonego komentarza do najnowszej wersji dokumentu

Dodając komentarz, możesz go przypiąć do wybranego obszaru w pliku. Ankiety określają wersję pliku i region w pliku, do którego odnosi się komentarz. Zasób comments definiuje pole anchor jako ciąg znaków JSON.

Aby dodać zakotwiczony komentarz:

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

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

Sposób zdefiniowania regionu zależy od typu treści dokumentu, z którym pracujesz. Więcej informacji znajdziesz w artykule Definiowanie regionu.

Definiowanie regionu

Jak już wspomnieliśmy, ciąg zakotwiczenia JSON zawiera element revisionID (r) i region (a). Region (a) to tablica JSON zawierająca klasyfikatory regionów określające format i lokalizację, do których jest zakotwiczony komentarz. Klasyfikator może być dwuwymiarowym prostokątem w przypadku obrazu, linią tekstu w dokumencie lub czasem trwania w filmie. Aby zdefiniować region, wybierz region klasyfikator, który odpowiada rodzajowi treści, do których chcesz dołączyć kotwicę. Jeśli na przykład Twoje treści to tekst, użyjesz prawdopodobnie klasyfikatora regionów txt lub line.

Listę klasyfikatorów regionów w interfejsie Drive API znajdziesz w artykule o klasyfikatorach regionów.

Ten przykład pokazuje ciąg zakotwiczenia JSON, który zakotwicza komentarze do linii w 2 oddzielnych obszarach dokumentu:

  • Pierwszy obszar zaczyna się w wierszu 12 ('n':12) i zajmuje 3 wiersze ('l':3).
  • Drugi obszar obejmuje tylko wiersz 18 ('n':18, 'l':1).
    {
      'r': 'REVISION_ID',
      'a': [
      {
        'line':
        {
          'n': 12,
          'l': 3,
        }
      },
      {
        'line':
        {
          'n': 18,
          'l': 1,
        }
      }]
    }

Zastąp REVISION_ID wartością head lub identyfikatorem konkretnej wersji.

Pobieranie komentarza

Aby uzyskać komentarz do pliku, użyj metody get() zasobu comments z parametrami fileId i commentId. Jeśli nie znasz identyfikatora komentarza, możesz wyświetlić wszystkie komentarze, korzystając z metody list().

Metoda zwraca instancję zasobu comments.

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

Pokaż przykład

Wyślij prośbę

W tym przykładzie podajemy parametry ścieżki fileId i commentId oraz wiele 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 metody list() zasobu comments z parametrem fileId. Metoda zwraca listę komentarzy.

Aby dostosować podział na strony lub filtrowanie komentarzy, prześlij te parametry zapytania:

  • includeDeleted: ustaw na true, aby uwzględnić usunięte komentarze. Usunięta 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ć kolejną stronę.

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

Pokaż przykład

Wyślij prośbę

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() zasobu comments z parametrami fileId i commentId. Aby zaktualizować komentarz, treść żądania używa pola content.

Metoda zwraca pola wymienione w parametrze zapytania fields.

Pokaż przykład

Wyślij prośbę

W tym przykładzie podajemy parametry ścieżki fileId i commentId oraz wiele 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. Usuwane komentarze nie zawierają pól htmlContent ani content.

Pokaż przykład

Wyślij prośbę

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

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