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

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

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

Используйте параметр fields

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

Ограничения комментариев

При работе с закрепленными и незакрепленными комментариями с помощью API Диска применяются следующие ограничения:

Тип комментария Тип файла
На якоре
  • Разработчики могут определить собственный формат для спецификации якоря.
  • Якорь сохраняется и возвращается при извлечении комментария, однако приложения-редакторы Google Workspace рассматривают такие комментарии как незакрепленные.
Незакрепленный
  • Поддерживается в документах Google Workspace, где они отображаются в представлении «Все комментарии».
  • Незакрепленные комментарии не отображаются в PDF-файлах, просматриваемых в средстве предварительного просмотра файлов Диска, хотя они сохраняются и могут быть извлечены через API Диска.

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

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

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

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

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

В следующем примере кода показано, как создать закрепленный комментарий:

Питон 


from google.oauth2.credentials import Credentials
from googleapiclient.errors import HttpError

# --- Configuration ---
# The ID of the file to comment on.
# Example: '1_aBcDeFgHiJkLmNoPqRsTuVwXyZ'
FILE_ID = 'FILE_ID'

# The text content of the comment.
COMMENT_TEXT = 'This is an example of an anchored comment.'

# The line number to anchor the comment to.
# Note: Line numbers are based on the revision.
ANCHOR_LINE = 10
# --- End of user-configuration section ---

SCOPES = ["https://www.googleapis.com/auth/drive"]

creds = Credentials.from_authorized_user_file("token.json", SCOPES)

def create_anchored_comment():
    """
    Create an anchored comment on a specific line in a Google Doc.

    Returns:
        The created comment object or None if an error occurred.
    """
    try:
        # Build the Drive API service
        service = build("drive", "v3", credentials=creds)

        # Define the anchor region for the comment.
        # For Google Docs, the region is typically defined by 'line' and 'revision'.
        # Other file types might use different region classifiers.
        anchor = {
            'region': {
                'kind': 'drive#commentRegion',
                'line': ANCHOR_LINE,
                'rev': 'head'
            }
        }

        # The comment body.
        comment_body = {
            'content': COMMENT_TEXT,
            'anchor': anchor
        }

        # Create the comment request.
        comment = (
            service.comments()
            .create(fileId=FILE_ID, fields="*", body=comment_body)
            .execute()
        )

        print(f"Comment ID: {comment.get('id')}")
        return comment

    except HttpError as error:
        print(f"An error occurred: {error}")
        return None

create_anchored_comment()

API Диска возвращает экземпляр объекта ресурса comments , который включает строку anchor .

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

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

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

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

Питон 


from google.oauth2.credentials import Credentials
from googleapiclient.errors import HttpError

# --- Configuration ---
# The ID of the file to comment on.
# Example: '1_aBcDeFgHiJkLmNoPqRsTuVwXyZ'
FILE_ID = 'FILE_ID'

# The text content of the comment.
COMMENT_TEXT = 'This is an example of an unanchored comment.'
# --- End of user-configuration section ---

SCOPES = ["https://www.googleapis.com/auth/drive"]

creds = Credentials.from_authorized_user_file("token.json", SCOPES)

def create_unanchored_comment():
    """
    Create an unanchored comment on a specific line in a Google Doc.

    Returns:
        The created comment object or None if an error occurred.
    """
    try:
        # Build the Drive API service
        service = build("drive", "v3", credentials=creds)

        # The comment body. For an unanchored comment,
        # omit the 'anchor' property.
        comment_body = {
            'content': COMMENT_TEXT
        }

        # Create the comment request.
        comment = (
            service.comments()
            .create(fileId=FILE_ID, fields="*", body=comment_body)
            .execute()
        )

        print(f"Comment ID: {comment.get('id')}")
        return comment

    except HttpError as error:
        print(f"An error occurred: {error}")
        return None

create_unanchored_comment()

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

Чтобы добавить ответ на комментарий, используйте метод 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."
}

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

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

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

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

Когда комментарий разрешён, Диск отмечает ресурс comments как 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."
}

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

Чтобы получить комментарий к файлу, используйте метод 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