Эта страница переведена с помощью Cloud Translation API.

Управление согласованиями

В этом документе объясняется, как управлять подтверждениями в API Google Drive.

Пользователи могут отправлять документы в Google Drive через формальный процесс утверждения. Этот процесс можно использовать для получения одобрения на проверку контракта или официального документа перед публикацией. Утверждение отслеживает статус как самой проверки (например, «В процессе», «Одобрено» или «Отклонено»), так и участвующих в ней рецензентов. Утверждения — это отличный способ проверить контент и вести учет рецензентов.

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

Прежде чем начать

Ваш файл должен содержать возможность canStartApproval . Чтобы проверить возможности файла, вызовите метод get ресурса files с параметром fileId path и используйте поле возможности canStartApproval в параметре fields . Для получения дополнительной информации см. раздел «Понимание возможностей файлов» .
Логическая переменная canStartApproval имеет значение false когда:
- Доступ к этой функции ограничен настройками администратора.
- Ваша версия Google Workspace не подходит.
- Файл принадлежит пользователю, не входящему в ваш домен.
- У пользователя отсутствует role=writer для этого файла.
Убедитесь, что вы вручную предоставили доступ к целевому файлу рецензентам. Google Drive не делает это автоматически. Если у рецензента нет доступа к файлу, запрос на утверждение будет одобрен, но он не будет получать уведомления и не сможет просмотреть файл.

Концепции

Следующие ключевые понятия составляют основу процесса утверждения.

Статус одобрения

При запросе на утверждение документа процесс утверждения гарантирует, что каждый рецензент сможет внести свои замечания по документу.

Ресурс approvals включает объект Status , в котором подробно описывается статус утверждения на момент запроса ресурса. Он также включает объект ReviewerResponse , в котором подробно описываются ответы конкретных рецензентов на утверждение. Ответ каждого рецензента представлен объектом Response .

Поведение процесса утверждения при изменении содержимого файла Status IN_PROGRESS определяется полем fileContentChangeBehavior ресурса approvals . Могут применяться следующие варианты поведения:

RESET_APPROVAL : Процесс утверждения гарантирует, что каждый рецензент утвердит одну и ту же версию содержимого. Если файл редактируется после того, как рецензент утвердит запрос, но до завершения запроса, количество утверждений рецензентов сбрасывается (ответ возвращается к NO_RESPONSE ), и рецензенты должны утвердить новую версию. Когда статус утверждения становится APPROVED , файл блокируется, чтобы предотвратить дальнейшие изменения. Дополнительные изменения содержимого после окончательного утверждения приведут к появлению на документе баннера, указывающего на то, что текущая версия отличается от утвержденной. Это поведение по умолчанию.
NO_APPROVAL_ACTION : Изменения содержимого файла не сбрасывают решения рецензентов, пока идет процесс утверждения. Кроме того, файл не блокируется после окончательного утверждения. Рецензенты также могут в любое время до завершения утверждения изменить свой собственный статус APPROVED на «Ожидание» (ответ возвращается к NO_RESPONSE ).

После завершения процедуры утверждения данное правило больше не применяется.

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

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

После завершения процедуры утверждения (статус APPROVED , CANCELLED или DECLINED ») она остается в состоянии «завершено» и не может быть изменена ни инициатором, ни рецензентами. Вы можете добавлять комментарии к завершенному утверждению, если нет существующего утверждения файла со статусом IN_PROGRESS .

Жизненный цикл утверждения

Процесс утверждения проходит несколько этапов в течение своего жизненного цикла. На рисунке 1 показаны основные этапы жизненного цикла утверждения:

Начните процесс утверждения . Вызовите метод ` start , чтобы начать запрос на утверждение. После этого status будет установлен на IN_PROGRESS .
Ожидается утверждение . Пока утверждение находится в процессе ( status установлен как IN_PROGRESS ), инициатор, и рецензенты могут взаимодействовать с ним. Они могут добавить comment , инициатор может reassign рецензентов, и один или несколько рецензентов могут approve запрос.
Процесс утверждения находится в состоянии "завершено" . Утверждение переходит в состояние "завершено" ( status устанавливается на APPROVED , CANCELLED или DECLINED "), когда все рецензенты одобряют запрос, инициатор решает cancel запрос или если какой-либо рецензент решает decline запрос.

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

Если вы хотите указать поля, которые должны быть возвращены в ответе, вы можете задать системный параметр fields для любого метода ресурса approvals . Если вы опустите параметр fields , сервер вернет набор полей по умолчанию, специфичных для данного метода. Чтобы вернуть другие поля, см. раздел «Возврат определенных полей» .

Запуск и администрирование процедур утверждения.

Ресурс approvals можно использовать для запуска и управления утверждениями с помощью API Google Drive. Эти методы работают с любыми существующими областями действия API Google Drive OAuth 2.0, которые позволяют записывать метаданные файлов. Для получения дополнительной информации см. раздел «Выбор областей действия API Google Drive» .

Начало утверждения

Чтобы начать новый процесс утверждения файла, используйте метод start ресурса approvals и укажите в качестве параметра путь fileId ).

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

dueTime : Крайний срок утверждения в формате RFC 3339.
lockFile : Логическое значение, указывающее, следует ли блокировать файл при начале процесса утверждения. Это блокирует возможность изменения файла пользователями во время процесса утверждения. Любой пользователь с правами role=writer может снять эту блокировку.
message : Пользовательское сообщение, отправляемое рецензентам.
fileContentChangeBehavior : Поведение подтверждения при изменении содержимого файла. Поддерживаемые значения:
- RESET_APPROVAL : (По умолчанию) Сбрасывает любой ответ рецензента APPROVED на NO_RESPONSE при изменении содержимого во время процесса утверждения. Файл блокируется после завершения утверждения со статусом APPROVED .
- NO_APPROVAL_ACTION : Не сбрасывает ответы рецензентов при изменении содержимого и не блокирует файл после завершения утверждения.

В теле ответа содержится экземпляр ресурса approvals , включая поле initiator , которым является пользователь, запросивший согласование. Status согласования устанавливается в IN_PROGRESS .

Если существует согласование со Status IN_PROGRESS , метод start завершится с ошибкой. Вы можете запустить согласование только в том случае, если для файла нет существующего согласования или если существующее согласование находится в завершенном состоянии (статус APPROVED , CANCELLED или DECLINED ).

локон

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals:start' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "reviewerEmails": [
     "reviewer1@example.com",
     "reviewer2@example.com"
    ],
    "dueTime": "2026-04-01T15:01:23Z",
    "lockFile": true,
    "message": "Please review this file for approval.",
    "fileContentChangeBehavior": "RESET_APPROVAL"
 }'

Замените следующее:

FILE_ID : Идентификатор файла, по которому осуществляется утверждение.
ACCESS_TOKEN : Токен OAuth 2.0 вашего приложения.

Комментарий по поводу одобрения

Чтобы оставить комментарий к утверждению, используйте метод comment ресурса approvals и укажите параметры fileId и approvalId path.

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

В теле ответа содержится экземпляр ресурса approvals . Сообщение отправляется инициатору утверждения и рецензентам в качестве уведомления, а также включается в журнал активности утверждений.

локон

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:comment' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The required comment on the approval."
 }'

Замените следующее:

FILE_ID : Идентификатор файла, по которому осуществляется утверждение.
APPROVAL_ID : Идентификатор подтверждения.
ACCESS_TOKEN : Токен OAuth 2.0 вашего приложения.

Переназначьте рецензентов после утверждения.

Для переназначения рецензентов при утверждении используйте метод reassign ресурса approvals и укажите в качестве параметров путь fileId и approvalId .

Метод reassign позволяет инициатору утверждения (или пользователю с правами role=writer ) добавлять или заменять рецензентов в объекте ReviewerResponse ресурса approvals . Пользователь с правами role=reader может переназначить только то утверждение, которое назначено ему самому. Это позволяет пользователю переназначить запрос другому, более компетентному рецензенту.

Переназначение рецензентов возможно только при Status IN_PROGRESS и значении NO_RESPONSE в поле response для переназначаемого рецензента.

Обратите внимание, что удалить рецензента из процесса утверждения невозможно. Если вам необходимо удалить рецензента, вы должны отменить утверждение и начать новое.

Тело запроса состоит из необязательных полей addReviewers и replaceReviewers . Каждое поле содержит повторяющийся объект для AddReviewer и ReplaceReviewer , каждый из которых содержит одного рецензента для добавления или пару рецензентов для замены. Вы также можете добавить необязательное поле message , содержащее комментарий, который вы хотите отправить новым рецензентам.

В теле ответа содержится экземпляр ресурса approvals . Сообщение отправляется новым рецензентам в качестве уведомления, а также включается в журнал активности утверждений.

локон

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:reassign' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "addReviewers": [
    {
        "addedReviewerEmail": "new_reviewer@example.com"
    }
    ],
    "replaceReviewers": [
    {
        "addedReviewerEmail": "replacement_reviewer@example.com",
        "removedReviewerEmail": "old_reviewer@example.com"
    }
    ],
    "message": "Reassigning reviewers for this approval request."
 }'

Замените следующее:

FILE_ID : Идентификатор файла, по которому осуществляется утверждение.
APPROVAL_ID : Идентификатор подтверждения.
ACCESS_TOKEN : Токен OAuth 2.0 вашего приложения.

Отменить подтверждение

Для отмены утверждения используйте метод cancel ресурса approvals и укажите в качестве параметров fileId и approvalId path.

Метод cancel может быть вызван только инициатором утверждения (или пользователем с правами role=writer ), если Status утверждения равен IN_PROGRESS .

Тело запроса состоит из необязательного поля message , представляющего собой строку, содержащую текст, сопровождающий отмену подтверждения.

В теле ответа содержится экземпляр ресурса « approvals . Сообщение отправляется в виде уведомления и также включается в журнал активности утверждений. Status утверждения устанавливается в значение CANCELLED , и оно находится в состоянии «Завершено».

локон

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:cancel' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The optional reason for cancelling this approval request."
 }'

Замените следующее:

FILE_ID : Идентификатор файла, по которому осуществляется утверждение.
APPROVAL_ID : Идентификатор подтверждения.
ACCESS_TOKEN : Токен OAuth 2.0 вашего приложения.

Отклонить одобрение

Чтобы отклонить запрос на утверждение, используйте метод decline для ресурса approvals и укажите в качестве параметров путь fileId и approvalId .

Метод decline можно вызвать только в том случае, если Status утверждения — IN_PROGRESS .

Тело запроса состоит из необязательного поля message , представляющего собой строку, содержащую текст, сопровождающий отказ в одобрении.

В теле ответа содержится экземпляр ресурса approvals . Сообщение отправляется в виде уведомления и также включается в журнал активности утверждений. Поле response объекта ReviewerResponse запрашивающего пользователя устанавливается в DECLINED . Кроме того, Status утверждения устанавливается в DECLINED , и утверждение находится в состоянии "завершено".

локон

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:decline' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The optional reason for declining this approval request."
 }'

Замените следующее:

FILE_ID : Идентификатор файла, по которому осуществляется утверждение.
APPROVAL_ID : Идентификатор подтверждения.
ACCESS_TOKEN : Токен OAuth 2.0 вашего приложения.

Одобрить утверждение

Для утверждения используйте метод approve ресурса approvals и укажите в качестве параметров fileId и approvalId path.

Метод approve можно вызвать только тогда, когда Status утверждения равен IN_PROGRESS .

Тело запроса состоит из необязательного поля message , представляющего собой строку, содержащую текст, сопровождающий подтверждение.

В теле ответа содержится экземпляр ресурса approvals . Сообщение отправляется в виде уведомления и также включается в журнал активности утверждений. Поле response объекта ReviewerResponse запрашивающего пользователя устанавливается в APPROVED . Кроме того, если это последний необходимый ответ рецензента, Status утверждения устанавливается в APPROVED , и утверждение находится в состоянии "завершено".

локон

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:approve' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The optional reason for approving this approval request."
 }'

Замените следующее:

FILE_ID : Идентификатор файла, по которому осуществляется утверждение.
APPROVAL_ID : Идентификатор подтверждения.
ACCESS_TOKEN : Токен OAuth 2.0 вашего приложения.

Найдите существующие разрешения.

Ресурс approvals также можно использовать для получения и отображения статуса ваших утверждений с помощью API Google Drive.

Для просмотра подтверждений по файлу необходимо иметь разрешение на чтение метаданных файла. Дополнительную информацию см. в разделе «Роли и разрешения» .

Получите одобрение

Чтобы получить подтверждение для файла, используйте метод get ресурса approvals с параметрами fileId и approvalId путь). Если идентификатор подтверждения неизвестен, вы можете вывести список подтверждений с помощью метода list .

В теле ответа содержится экземпляр ресурса approvals .

локон

curl -X GET 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Accept: application/json'

Замените следующее:

FILE_ID : Идентификатор файла, по которому осуществляется утверждение.
APPROVAL_ID : Идентификатор подтверждения.
ACCESS_TOKEN : Токен OAuth 2.0 вашего приложения.

Утверждение списков

Чтобы вывести список утверждений для файла, вызовите метод list ресурса approvals и укажите в качестве параметра путь fileId .

В ответе содержится список согласований по файлу. Поле items включает информацию о каждом согласовании в виде ресурса approvals .

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

pageSize : Максимальное количество подтверждений, возвращаемых на странице. Если pageSize не задан, сервер вернет до 100 подтверждений.
pageToken : Токен страницы, полученный из предыдущего вызова списка. Этот токен используется для получения следующей страницы. Он должен быть установлен в значение nextPageToken из предыдущего ответа.

локон

curl -X GET 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals?pageSize=10' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Accept: application/json'

Замените следующее:

FILE_ID : Идентификатор файла, по которому осуществляется утверждение.
ACCESS_TOKEN : Токен OAuth 2.0 вашего приложения.

Управление согласованиями Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Прежде чем начать

Концепции

Статус одобрения

Жизненный цикл утверждения

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

Запуск и администрирование процедур утверждения.

Начало утверждения

локон

Комментарий по поводу одобрения

локон

Переназначьте рецензентов после утверждения.

локон

Отменить подтверждение

локон

Отклонить одобрение

локон

Одобрить утверждение

локон

Найдите существующие разрешения.

Получите одобрение

локон

Утверждение списков

локон

Связанные темы

Управление согласованиями