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

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

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

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

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

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

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

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

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

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

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

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

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

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

Python 


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 Google Drive возвращает экземпляр объекта ресурса comments , который включает в себя строку anchor .

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

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

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

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

Python 


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 так, чтобы добавить ответ, закрывающий комментарий.

Когда комментарий разрешен, Google Drive помечает ресурс 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 .

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

Запрос

В этом примере мы указываем параметры пути fileId и commentId . 

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