Zarządzanie komentarzami i odpowiedziami

Komentarze to opinie użytkowników na temat pliku, np. sugestie od czytelnika dokumentu edytora tekstu dotyczące 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ą.

W przypadku wszystkich metod (z wyjątkiem delete) zasobu comments musisz ustawić fields parametry systemowe, aby określić pola do zwrócenia w odpowiedzi. W przypadku większości metod w usłudze Drive to działanie jest wymagane tylko do zwracania pól innych niż domyślne, ale jest obowiązkowe w przypadku zasobu comments. Jeśli pominiesz ten parametr, metoda zwróci błąd. Więcej informacji znajdziesz w sekcji Zwracanie określonych pól.

Dodawanie niezakotwiczonego komentarza

Aby dodać do dokumentu niezakotwiczoną adnotację, wywołaj metodę create z parametrem fileId i zasobem comments zawierającym adnotację.

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.

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 komentarzy. 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ść dalszych odpowiedzi i przyciemnić wszystkie poprzednie odpowiedzi oraz oryginalny komentarz;
  • ukrywać zakończone komentarze.

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 ostatniej 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 dla dokumentu. Wykonaj ten krok tylko wtedy, gdy chcesz zakotwiczyć komentarz do wersji innej niż najnowsza. Jeśli chcesz użyć najnowszej wersji, użyj wartości head dla parametru revisionID.

  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 definiowania 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 zaczepu 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 regionalny klasyfikator, który odpowiada rodzajowi treści, do których chcesz dołączyć etykietę. Na przykład, jeśli 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 true.

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, podaj 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.

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.

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 artykule Rozwiązywanie komentarzy.

Metoda zwraca pola wymienione w parametrze zapytania fields.

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.

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