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

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 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 ten parametr, metoda zwróci błąd. Więcej informacji znajdziesz w artykule 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ź do komentarza, użyj metody replies.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.

Wyślij prośbę

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ć problem z komentarzem, użyj metody replies.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 go jakoresolved: true. W przeciwieństwie do usuniętych komentarzy zakończone 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.

Wyślij prośbę

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."
}

Dodawanie zakotwiczonego komentarza do najnowszej wersji dokumentu

Gdy dodajesz komentarz, możesz go przypiąć do regionu w pliku. Punkt zakotwiczenia określa wersję pliku i 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 powiązany:

  1. Opcjonalnie: Wywołaj metodę revisions.list, aby wyświetlić listę wszystkich 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 z parametrem fileID, zasobem comments zawierającym komentarz i ciągiem zakotwiczenia JSON zawierającym revisionID (r) i region (a).

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

Określanie regionu

Jak wspomnieliśmy wcześniej, ciąg zakotwiczenia JSON zawiera revisionID (r) i region (a). Region (a) to tablica JSON zawierająca klasyfikatory regionów określające format i lokalizację, do której jest zakotwiczony komentarz. Klasyfikator może być dwuwymiarowym prostokątem na obrazie, wierszem tekstu w dokumencie lub przedziałem czasu w filmie. Aby zdefiniować region, wybierz klasyfikator regionu, który pasuje do typu treści, do których chcesz przypisać kotwicę. Jeśli na przykład Twoje treści to tekst, prawdopodobnie użyjesz klasyfikatora regionu txt lub line.

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

Poniższy przykład pokazuje ciąg JSON z kotwicą, która przytwierdza komentarze do wierszy w 2 osobnych obszarach dokumentu:

  • Pierwszy obszar zaczyna się w wierszu 12 ('n':12) i obejmuje 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 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.

Wyślij prośbę

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.

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 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 problemu z komentarzem.

Metoda zwraca pola wymienione w parametrze zapytania fields.

Wyślij prośbę

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.

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