Управление комментариями и ответами

Комментарии — это обратная связь пользователя с файлом, например, когда пользователь текстового редактора предлагает перефразировать предложение. Существует два типа комментариев: закреплённые и незакреплённые . Закреплённый комментарий связан с определённым местом, например, с предложением в текстовом редакторе, в определённой версии документа. Напротив, незакреплённый комментарий связан только с документом.

Примечание: API Google Drive поддерживает только не закреплённые комментарии для BLOB-файлов. Закреплённые комментарии для BLOB-файлов и файлов редактора Google Docs не поддерживаются.

Ответы прикрепляются к комментариям и представляют собой реакцию пользователя на комментарий. API Drive позволяет пользователям добавлять комментарии и ответы к документам, созданным в вашем приложении. Совокупность комментариев и ответов называется обсуждением .

Для всех методов (кроме delete ) ресурса comments необходимо задать системный параметр fields , чтобы указать поля, возвращаемые в ответе. В большинстве методов Drive это действие требуется только для возврата полей, отличных от полей по умолчанию, но для ресурса comments оно обязательно. Если этот параметр пропущен, метод вернёт ошибку. Подробнее см. в разделе Возврат определённых полей .

Добавить незакрепленный комментарий

Чтобы добавить непривязанный комментарий к документу, вызовите метод create с параметром fileId и ресурсом comments , содержащим комментарий.

Комментарий вставляется как обычный текст, но тело ответа содержит поле htmlContent , содержащее контент, отформатированный для отображения.

Важно: рекомендуем проверить наличие у пользователя необходимых прав на добавление комментариев. Кроме того, удалять или редактировать комментарий или ответ может только создатель комментария или ответа. Ошибки возникают, когда пользователь, не имеющий прав создателя, пытается удалить или отредактировать комментарий. Чтобы избежать этих ошибок, проверьте поле author.me ресурса comments , чтобы убедиться, что пользователь, отправивший запрос, является автором комментария, а затем проверьте его права на этот комментарий.

Добавить ответ на комментарий

Чтобы добавить ответ на комментарий, используйте метод replies.create ресурса replies с параметрами fileId и commentId . В теле запроса для добавления ответа используется поле content .

Ответ вставляется как обычный текст, но тело ответа содержит поле htmlContent , содержащее контент, отформатированный для отображения.

Метод возвращает поля, перечисленные в поле fields .

Запрос

В этом примере мы предоставляем параметры пути fileId и commentId , а также несколько полей.

POST https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID/replies?fields=id,comment

Текст запроса

{
  "content": "This is a reply to a comment."
}

Разрешить комментарий

Комментарий может быть решен только путем публикации ответа на комментарий.

Чтобы разрешить комментарий, используйте метод replies.create в ресурсе replies с параметрами fileId и commentId .

В теле запроса поле action используется для разрешения комментария. Вы также можете настроить поле content для добавления ответа, закрывающего комментарий.

Когда комментарий разрешён, Диск отмечает ресурс комментария как resolved: true . В отличие от удалённых комментариев , разрешённые комментарии могут включать поля htmlContent или content .

Когда ваше приложение обрабатывает комментарий, ваш пользовательский интерфейс должен показывать, что комментарий был обработан. Например, ваше приложение может:

• Запретить дальнейшие ответы и скрыть все предыдущие ответы, а также исходный комментарий.
• Скрыть решенные комментарии.

Запрос

В этом примере мы предоставляем параметры пути fileId и commentId , а также несколько полей.

POST https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID/replies?fields=id,comment

Текст запроса

{
  "action": "resolve",
  "content": "This comment has been resolved."
}

Добавить закрепленный комментарий к последней версии документа

При добавлении комментария может потребоваться привязать его к определённой области файла. Якорь определяет версию файла и область файла, на которую ссылается комментарий. Ресурс comments определяет поле anchor как строку JSON.

Примечание: API Диска поддерживает только не закреплённые комментарии для BLOB-файлов. Закреплённые комментарии для BLOB-файлов или файлов редактора Google Docs не поддерживаются.

Важно: якоря неизменяемы, и их положение относительно содержимого документа не может быть гарантировано между редакциями. Мы рекомендуем использовать якоря в документах, где их положение не меняется, например, в файлах изображений или документах, доступных только для чтения.

Чтобы добавить закрепленный комментарий:

1. (Необязательно). Вызовите метод revisions.list , чтобы получить список всех revisionID документа. Выполняйте этот шаг только в том случае, если вы хотите привязать комментарий к любой ревизии, кроме последней. Если вы хотите использовать последнюю ревизию, используйте head для revisionID .

2. Вызовите метод create с параметром fileID , ресурсом comments , содержащим комментарий, и строкой привязки JSON, содержащей revisionID ( r ) и регион ( a ).

Способ определения области зависит от типа содержимого документа, с которым вы работаете. Подробнее см. в разделе Определение области .

Примечание: Рекомендуем проверить наличие у пользователя необходимых прав на добавление комментариев. Кроме того, удалять или редактировать комментарий или ответ может только создатель комментария или ответа. Ошибки возникают, когда пользователь, не являющийся создателем, пытается удалить или отредактировать комментарий. Чтобы избежать этих ошибок, проверьте поле author.me ресурса комментариев .

Определить регион

Как упоминалось ранее, строка привязки JSON содержит revisionID ( r ) и область ( a ). Область ( a ) — это JSON-массив, содержащий классификаторы областей, определяющие формат и местоположение привязки комментария. Классификатор может быть двумерным прямоугольником для изображения, строкой текста в документе или длительностью видео. Чтобы определить область, выберите классификатор области , соответствующий типу контента, к которому вы пытаетесь привязать комментарий. Например, если ваш контент — текст, вы, вероятно, будете использовать классификатор области txt или line .

Список классификаторов регионов в API Drive см. в разделе Классификаторы регионов .

В следующем примере показана строка привязки JSON, которая привязывает комментарии к строкам в двух отдельных областях документа:

• Первая область начинается с 12-й строки ( 'n':12 ) и продолжается три строки ( 'l':3 ).
• Вторая область охватывает только строку 18 ( 'n':18, 'l':1 `).

    {
      'r': 'REVISION_ID',
      'a': [
      {
        'line':
        {
          'n': 12,
          'l': 3,
        }
      },
      {
        'line':
        {
          'n': 18,
          'l': 1,
        }
      }]
    }

Замените REVISION_ID на head или идентификатор конкретной ревизии.

Важно: Если ваше приложение позволяет пользователям обновлять и делиться несколькими версиями документа, комментарии к более старым версиям могут перестать применяться к привязанному месту. Поэтому необходимо чётко указывать в пользовательском интерфейсе, к какой версии относится каждый комментарий.

Получить комментарий

Чтобы получить комментарий к файлу, используйте метод get ресурса comments с параметрами fileId и commentId . Если вы не знаете идентификатор комментария, вы можете получить список всех комментариев с помощью метода list .

Метод возвращает экземпляр ресурса comments .

Чтобы включить удаленные комментарии в результаты, установите для параметра запроса includedDeleted значение true .

Запрос

В этом примере мы предоставляем параметры пути fileId и commentId , а также несколько полей.

GET https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID?fields=id,comment,modifiedTime,resolved

Список комментариев

Чтобы вывести список комментариев к файлу, используйте метод list ресурса comments с параметром fileId . Метод возвращает список комментариев.

Передайте следующие параметры запроса для настройки пагинации или фильтрации комментариев:

• includeDeleted : Установите значение true , чтобы включить удалённые комментарии. Удалённые комментарии не включают поля htmlContent и content .

• pageSize : максимальное количество комментариев, возвращаемых на странице.

• pageToken : токен страницы, полученный при предыдущем вызове списка. Укажите этот токен для получения следующей страницы.

• startModifiedTime : минимальное значение поля modifiedTime для комментариев к результату.

Запрос

В этом примере мы предоставляем параметр пути fileId , параметр запроса includeDeleted и несколько полей.

GET https://www.googleapis.com/drive/v3/files/FILE_ID/comments?includeDeleted=true&fields=(id,comment,kind,modifiedTime,resolved)

Обновить комментарий

Чтобы обновить комментарий к файлу, используйте метод update ресурса comments с параметрами fileId и commentId . В теле запроса для обновления комментария используется поле content .

Поле resolved » в ресурсе comments доступно только для чтения. Комментарий можно разрешить, только отправив ответ на другой комментарий. Подробнее см. в разделе «Решить проблему комментария» .

Метод возвращает поля, перечисленные в параметре запроса fields .

Запрос

В этом примере мы предоставляем параметры пути fileId и commentId , а также несколько полей.

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID?fields=id,comment

Текст запроса

{
  "content": "This comment is now updated."
}

Удалить комментарий

Чтобы удалить комментарий к файлу, используйте метод delete ресурса comments с параметрами fileId и commentId .

При удалении комментария Диск отмечает ресурс комментария как deleted: true . Удалённые комментарии не содержат поля htmlContent и content .

Запрос

В этом примере мы предоставляем параметры пути fileId и commentId .

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