Эта страница переведена с помощью Cloud Translation API.

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

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

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

Установка параметра fields необходима для перечисления полей, которые будут возвращаться в ответе при вызове каждого метода, указанного в ресурсе 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.

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

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

То, как вы определяете регион, зависит от типа содержимого документа, с которым вы работаете. Дополнительную информацию см. в разделе Определение региона .

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

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

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

В следующем примере показана строка привязки 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 для обновления комментария.

Метод возвращает поля, перечисленные в параметре запроса 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