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

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

Примечание. В файлах больших двоичных объектов API Google Диска поддерживает только незакрепленные комментарии. Прикрепленные комментарии к файлам больших двоичных объектов или файлам редактора Документов Google не поддерживаются.

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

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

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

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

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

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

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

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

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

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

Примечание. В файлах больших двоичных объектов API Drive поддерживает только незакрепленные комментарии. Прикрепленные комментарии к файлам больших двоичных объектов или файлам редактора Документов Google не поддерживаются.

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

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

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

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

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

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

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

Как упоминалось ранее, строка привязки 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 или идентификатор конкретной ревизии.

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

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

Используйте метод comment.update , чтобы установить для resolved в ресурсе comments значение true , когда комментарий был обработан.

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

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

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

Используйте метод comments.delete для удаления комментариев. Когда комментарий удаляется, Диск помечает ресурс комментария как "deleted": "true" .

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

Используйте метод comments.list для вывода списка комментариев. Если вы хотите включить в результаты удаленные комментарии, установите для поля includedDeleted значение true .