Zarządzanie komentarzami i odpowiedziami

Komentarze to przekazywane przez użytkowników opinie o pliku, np. czytelnik dokumentu edytora tekstu sugerującego, jak przeformułować zdanie. Istnieją 2 typy komentarzy: komentarze zakotwiczone i niezakotwiczone. Zakotwiczony komentarz jest powiązany z konkretną lokalizacją, taką jak zdanie w dokumencie edytującym tekst, w ramach określonej wersji dokumentu. I na odwrót – niezakotwiczony komentarz jest po prostu powiązany z dokumentem.

Uwaga: w przypadku plików blob interfejs Google Drive API obsługuje tylko niezakotwiczone komentarze. Zakotwiczone komentarze do plików blob i edytorów Dokumentów Google nie są obsługiwane.

Odpowiedzi są dołączane do komentarzy i reprezentują odpowiedź użytkownika na ten komentarz. Interfejs Drive API umożliwia użytkownikom dodawanie komentarzy i odpowiedzi do dokumentów utworzonych przez Twoją aplikację. Zbiorczo komentarz z odpowiedziami jest nazywany dyskusją.

Dodaj niezakotwiczony komentarz

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

Komentarz jest wstawiony jako zwykły tekst, ale w treści odpowiedzi znajduje się pole htmlContent z treścią sformatowaną do wyświetlenia.

Ważne: zalecamy sprawdzenie, czy użytkownik ma odpowiednie uprawnienia do dodawania komentarzy. Poza tym tylko twórca komentarza lub odpowiedzi może usunąć lub edytować komentarz lub odpowiedź. Błędy występują, gdy użytkownik, który nie jest twórcą, próbuje usunąć lub edytować komentarz. Aby uniknąć tych błędów, sprawdź pole author.me zasobu komentarzy i upewnij się, że użytkownik przesyłający żądanie jest autorem komentarza, a potem zweryfikuj jego uprawnienia dotyczące komentarza.

Dodawanie odpowiedzi na komentarz

Aby dodać odpowiedź na komentarz, wywołaj metodę replies.create z komentarzem, parametrem fileId i zasobem replies zawierającym odpowiedź.

Odpowiedź jest wstawiona jako zwykły tekst, ale w treści odpowiedzi znajduje się pole htmlContent z treścią sformatowaną do wyświetlenia.

Dodaj zakotwiczony komentarz do najnowszej wersji dokumentu

Po dodaniu komentarza możesz go zakotwiczyć do regionu w pliku. Kotwica określa wersję i region pliku, do którego odnosi się komentarz. Zasób comments definiuje pole anchor jako ciąg znaków JSON.

Uwaga: w przypadku plików blob interfejs Drive API obsługuje tylko niezakotwiczone komentarze. Zakotwiczone komentarze do plików blob i edytorów Dokumentów Google nie są obsługiwane.

Ważne: kotwicy nie można zmienić, a ich położenie względem treści dokumentu nie jest gwarantowane między kolejnymi wersjami. Zalecamy stosowanie kotwic w dokumentach, w których ich pozycja się nie zmienia, takich jak pliki graficzne czy dokumenty tylko do odczytu.

Aby dodać zakotwiczony komentarz:

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

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

Sposób definiowania regionu zależy od typu dokumentu, nad którym pracujesz. Więcej informacji znajdziesz w sekcji Definiowanie regionu.

Uwaga: zalecamy sprawdzenie, czy użytkownik ma odpowiednie uprawnienia do dodawania komentarzy. Poza tym tylko twórca komentarza lub odpowiedzi może usunąć lub edytować komentarz lub odpowiedź. Błędy występują, gdy osoba niebędąca twórcą próbuje usunąć lub edytować komentarz. Aby uniknąć tych błędów, sprawdź pole author.me zasobu komentarzy.

Zdefiniuj region

Jak już wspomnieliśmy, ciąg kotwicy JSON zawiera ciąg revisionID (r) i region (a). Region (a) to tablica JSON zawierająca klasyfikatory regionów określająca format i lokalizację, do których zostanie zakotwiczony komentarz. Klasyfikator może być dwuwymiarowym prostokątem obrazu, linią tekstu w dokumencie lub blokiem czasu w filmie. Aby zdefiniować region, wybierz klasyfikator regionu odpowiadający typowi treści, do których próbujesz się zakotwiczyć. Jeśli na przykład treść zawiera tekst, prawdopodobnie użyjesz klasyfikatora regionów txt lub line.

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

Poniższy przykład przedstawia ciąg kotwicy JSON, który zakotwicza komentarze do wierszy w 2 osobnych obszarach dokumentu:

• Pierwszy obszar rozpoczyna się w linii 12 ('n':12) i obejmuje 3 wiersze ('l':3).
• Drugi obszar obejmuje tylko linię 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.

Ważne: jeśli Twoja aplikacja umożliwia użytkownikom aktualizowanie i udostępnianie wielu wersji dokumentu, komentarze dotyczące starszych wersji mogą nie być już stosowane do zakotwiczonej lokalizacji. Dlatego musisz wyraźnie wskazać w interfejsie wersję, do której należą poszczególne komentarze.

Zakończ komentarz

Użyj metody comment.update, aby ustawić właściwość resolved w zasobie comments na true w przypadku zaadresowania komentarza.

Gdy aplikacja ustawi właściwość resolved na true, w interfejsie aplikacji powinno pojawić się informacja, że komentarz został rozwiązany. Aplikacja może na przykład:

• Nie zezwalaj na kolejne odpowiedzi i przyciemnij wszystkie wcześniejsze odpowiedzi oraz oryginalny komentarz.
• Ukryj zakończone komentarze.

Usuwanie komentarzy

Do usuwania komentarzy używaj metody comments.delete. Gdy komentarz zostanie usunięty, Dysk oznaczy zasób komentarza jako "deleted": "true".

Komentarze do listy

Do wyświetlania komentarzy użyj metody comments.list. Jeśli w wynikach chcesz uwzględnić usunięte komentarze, w polu includedDeleted ustaw wartość true.