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

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

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

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

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

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

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

Тип комментария Тип файла
Прикрепленный
  • Разработчики могут определить собственный формат для спецификации привязки.
  • Якорь сохраняется и возвращается при получении комментария, но редакторы Google Workspace рассматривают такие комментарии как комментарии без привязки.
  • При получении комментариев к файлам Google Workspace (таким как Google Docs, Google Sheets или Google Slides), созданным в редакторе, поле anchor содержит внутренние данные привязки, специфичные для редактора (например, строку JSON workbook-range для файлов Sheets). API Google Drive рассматривает эти данные как непрозрачные и не может определить внутренние области документа, координаты ячеек или элементы слайда. Для работы с привязанными комментариями непосредственно к этим типам файлов используйте соответствующие API: Google Docs API , Google Sheets API или Google Slides API .
Без привязки
  • Поддерживается в документах Google Workspace, где они отображаются в режиме «Все комментарии».
  • Комментарии без привязки к источнику не отображаются в PDF-файлах, создаваемых в окне предварительного просмотра файлов Google Drive, хотя они сохраняются и могут быть получены через API Google Drive.

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

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

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

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

  2. Вызовите метод create для ресурса comments , передав ему параметр fileId , ресурс comments , содержащий комментарий, и строку привязки JSON, определенную вашим приложением.

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

Python 

import json

from google.oauth2.credentials import Credentials
from googleapiclient.discovery import build
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 in your application to anchor the comment to.
# Note: Google Workspace editor apps (such as Google Docs, Sheets, and
# Slides) treat comments created using the Drive API as unanchored
# comments. Custom anchors are intended for your own applications or
# custom file viewers.
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 with a custom application-defined anchor.

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

        # Define a custom anchor specification for your application.
        # The Drive API stores the anchor as an opaque string. Your custom
        # application or file viewer can parse this JSON string to position
        # the comment in your UI.
        anchor_data = {
            'line': ANCHOR_LINE,
            'revision': 'head'
        }

        # The comment body. The 'anchor' field must be a serialized
        # JSON string.
        comment_body = {
            'content': COMMENT_TEXT,
            'anchor': json.dumps(anchor_data)
        }

        # 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.discovery import build
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 file in Drive.

    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 .

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