Перейти к основному содержимому

Защита листов

Доступ к таблице выдаётся на уровне документа, но у отдельного листа внутри таблицы может стоять защита. API это учитывает: токен наследует права того пользователя, которому он принадлежит. Если пользователю лист закрыт, его токен (и подключённый им AI-агент) видит ровно то же ограничение.

Это касается и подключений через MCP: агент обращается к тому же API, поэтому правила защиты действуют одинаково.

Скрытие значений листа​

В настройках защиты листа можно скрыть значения от конкретных пользователей (видят только те, кто в списке разрешённых, и владелец таблицы).

Если значения листа скрыты от пользователя токена, чтение диапазона этого листа отклоняется:

  • GET /documents/{document}/values/{range} — ответ 403 с кодом "error": "sheet_protected";
  • GET /documents/{document}/values/batchGet — ответ 200, для такого диапазона приходят поле error с текстом причины и поле errorCode со значением sheet_protected, остальные диапазоны отдаются нормально.

Вебхуки учитывают то же правило: уведомление не содержит ячеек листа, значения которого скрыты от пользователя, создавшего подписку. Таких ячеек нет в cells, ranges и changes, они не входят в cellCount, а если других изменений нет, уведомление не отправляется.

Защита от редактирования​

Через API защита проверяется по правилам приложения с одним отличием: владельца таблицы защита в API не ограничивает (см. ниже). Например, владелец может через API переименовать защищённый лист, хотя в интерфейсе это закрыто.

Правила:

  • Защищённый лист. Записывать можно только в ячейки, которые в настройках защиты оставлены открытыми (исключения). Если для исключений указан список участников, то только этим участникам; без списка — всем, у кого есть право редактировать таблицу.
  • Защищённый диапазон. Записывать в него могут только участники из его списка.

Запрос, который затрагивает хотя бы одну закрытую ячейку, возвращает 403, и ничего не записывается:

  • PUT /documents/{document}/values/{range};
  • POST /documents/{document}/values/batchUpdate — пакет атомарный, поэтому закрытая ячейка в любом диапазоне отклоняет весь запрос;
  • POST /documents/{document}/values/append — проверяются строки, куда попадут новые значения;
  • POST /documents/{document}/values/clear — проверяются заполненные ячейки диапазона.

Запись отклоняется и в том случае, когда от пользователя токена скрыты значения листа: лист, который нельзя прочитать, нельзя и изменить.

Ответ на отказ из-за защиты содержит код "error": "sheet_protected". По нему программа отличает защиту от нехватки прав токена или ограничений тарифа: менять права токена или тариф здесь бесполезно, нужно попросить владельца таблицы добавить пользователя в список защиты.

{
  "message": "Запись запрещена: ячейки защищены настройками защиты листа или диапазона. Менять их могут владелец таблицы и люди из списка защиты.",
  "error": "sheet_protected"
}

Операции с листами​

Защита действует и на сам лист. Защищённый лист может переименовать или удалить только владелец таблицы, даже если у листа есть открытые ячейки. Для остальных вернётся 403 с кодом sheet_protected:

  • PATCH /documents/{document}/sheets/{sheet};
  • DELETE /documents/{document}/sheets/{sheet}.

Лист, на котором есть защищённые диапазоны, тоже может удалить только владелец таблицы, иначе вернётся 403 с кодом sheet_protected. Переименовывать такой лист могут все, у кого есть право редактировать таблицу.

Создание нового листа защитой других листов не ограничено.

Владелец таблицы​

Владелец таблицы не ограничен защитой листов: его токен читает и пишет любые листы документа.

Скрипты​

Скрипты Coverse подчиняются тем же правилам: скрипт участника на защищённом листе меняет только открытые ячейки, а менять защиту может только скрипт владельца таблицы. Подробнее — в статье Права и безопасность скриптов.