O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Gerenciar aprovações

Este documento explica como gerenciar aprovações na API Google Drive.

Os usuários podem enviar documentos no Google Drive por um processo de aprovação formal. Você pode usar esse processo para receber aprovação em uma revisão de contrato ou em um documento oficial antes da publicação. Uma aprovação acompanha o status da revisão (como "Em andamento", "Aprovado" ou "Recusado") e os revisores envolvidos. As aprovações são uma excelente maneira de validar o conteúdo e manter um registro dos revisores.

É possível criar e gerenciar aprovações de conteúdo no Drive. A API Google Drive fornece o approvals recurso para trabalhar com aprovações de arquivos. Os métodos do recurso approvals funcionam em itens do Drive, do Google Docs e de outros editores do Google Workspace. Os revisores podem aprovar, rejeitar ou dar feedback sobre os documentos diretamente.

Antes de começar

O arquivo precisa conter a canStartApproval capacidade . Para verificar as capacidades do arquivo, chame o get método no files recurso com o fileId parâmetro de caminho e use o canStartApproval campo de capacidade em o fields parâmetro. Para mais informações, consulte Entender as capacidades de arquivos.

A capacidade booleana canStartApproval é false quando:
- As configurações do administrador restringem o acesso ao recurso.
- Sua edição do Google Workspace não é qualificada.
- O arquivo pertence a um usuário fora do seu domínio.
- O usuário não tem a permissão role=writer no arquivo.
Compartilhe manualmente o arquivo de destino com os revisores. O Drive não faz isso automaticamente. Se um revisor não tiver acesso ao arquivo, o pedido de aprovação será bem-sucedido, mas ele não receberá notificações nem poderá visualizar o arquivo.

Conceitos

Os principais conceitos a seguir formam a base das aprovações.

Status de aprovação

Quando você solicita a aprovação de um documento, o processo de aprovação garante que todos os revisores possam dar feedback sobre o documento.

O recurso approvals inclui um Status objeto que detalha o status da aprovação quando o recurso é solicitado. Ele também inclui o ReviewerResponse objeto que detalha as respostas a uma aprovação feita por revisores específicos. A resposta de cada revisor é representada pelo Response objeto.

O comportamento da aprovação quando o conteúdo do arquivo é alterado enquanto a aprovação Status é IN_PROGRESS é determinado pelo campo fileContentChangeBehavior do recurso approvals. Os seguintes comportamentos podem ser aplicados:

RESET_APPROVAL: o processo de aprovação garante que todos os revisores aprovem a mesma versão do conteúdo. Se o arquivo for editado depois que um revisor aprovar a solicitação e antes que ela seja concluída, as aprovações do revisor serão redefinidas (a resposta será definida como NO_RESPONSE) e os revisores precisarão aprovar a nova versão. Quando a aprovação tem o status APPROVED, o arquivo é bloqueado para impedir outras modificações. Outras edições de conteúdo após a aprovação final farão com que um banner apareça no documento indicando que a versão atual é diferente da aprovada. Esse é o comportamento padrão.
NO_APPROVAL_ACTION: as edições no conteúdo do arquivo não redefinem as decisões do revisor enquanto a aprovação está pendente. Além disso, o arquivo não é bloqueado na aprovação final. Os revisores também podem redefinir a própria decisão APPROVED para o status pendente (a resposta é definida como NO_RESPONSE) a qualquer momento antes que a aprovação seja concluída.

Depois que a aprovação é concluída, esse comportamento não se aplica mais.

Cada ação no processo de aprovação gera notificações por e-mail que são enviadas ao iniciador (o usuário que solicita a aprovação) e a todos os revisores. Ela também é adicionada ao registro de atividades de aprovação.

Todos os revisores precisam aprovar uma aprovação. Qualquer revisor que recusar uma aprovação define o estado concluído como DECLINED.

Depois que uma aprovação é concluída (o status é APPROVED, CANCELLED ou DECLINED), ela permanece no estado concluído e não pode ser interagida pelo iniciador ou pelos revisores. É possível adicionar comentários a uma aprovação concluída, desde que não haja uma aprovação em um arquivo com o status IN_PROGRESS.

Ciclo de vida de uma aprovação

Uma aprovação passa por vários estados durante o ciclo de vida. A Figura 1 mostra as etapas de alto nível de um ciclo de vida de aprovação:

Iniciar a aprovação. Chame start para iniciar o pedido de aprovação. O status é definido como IN_PROGRESS.
Aprovação pendente. Enquanto a aprovação está pendente (status definido como IN_PROGRESS), o iniciador e os revisores podem interagir com ela. Eles podem adicionar um comment, o iniciador pode reassign revisores, e um ou mais revisores podem approve a solicitação.
Aprovação no estado concluído. Uma aprovação entra no estado concluído (status definido como APPROVED, CANCELLED ou DECLINED) quando todos os revisores aprovam a solicitação, o iniciador opta por cancel a solicitação ou se algum revisor escolhe por decline a solicitação.

Usar o parâmetro fields

Para recuperar detalhes de aprovação, é necessário especificar explicitamente os campos que você quer usando o fields parâmetro do sistema com qualquer método do recurso approvals. Ao contrário de outros recursos, os métodos do recurso approvals não retornam um conjunto padrão de campos quando o parâmetro fields é omitido. Para mais informações, consulte Retornar campos específicos.

Iniciar e administrar aprovações

O recurso approvals pode ser usado para iniciar e gerenciar aprovações usando a API Drive. Esses métodos funcionam com qualquer um dos escopos da API OAuth 2.0 Drive que permitem gravar metadados de arquivos. Para mais informações, consulte Escolher escopos da API Google Drive.

Iniciar aprovação

Para iniciar uma nova aprovação em um arquivo, use o start método no approvals recurso e inclua o fileId parâmetro de caminho.

O corpo da solicitação consiste em um campo reviewerEmails obrigatório, que é uma matriz de strings que contém os endereços de e-mail dos revisores atribuídos para revisar o arquivo. Cada endereço de e-mail do revisor precisa estar associado a uma Conta do Google ou a solicitação falhará. Além disso, quatro campos opcionais são oferecidos:

dueTime: o prazo para a aprovação no formato RFC 3339.
lockFile: um booleano que indica se o arquivo será bloqueado ao iniciar a aprovação. Isso impede que os usuários modifiquem o arquivo durante o processo de aprovação. Qualquer usuário com a permissão role=writer pode remover esse bloqueio.
message: uma mensagem personalizada enviada aos revisores.
fileContentChangeBehavior: o comportamento da aprovação quando o conteúdo do arquivo muda. Os valores aceitos são:
- RESET_APPROVAL: (padrão) redefine qualquer resposta do revisor de APPROVED para NO_RESPONSE quando o conteúdo muda enquanto a aprovação está em andamento. O arquivo é bloqueado quando a aprovação é concluída com o status APPROVED.
- NO_APPROVAL_ACTION: não redefine as respostas do revisor quando o conteúdo muda e não bloqueia o arquivo quando a aprovação é concluída.

O corpo da resposta contém uma instância do approvals recurso e ele inclui o initiator campo que é o usuário que solicitou a aprovação. O Status da aprovação é definido como IN_PROGRESS.

Se uma aprovação já estiver presente com um Status de IN_PROGRESS, o método start falhará. Só é possível iniciar uma aprovação se não houver uma aprovação no arquivo ou se a aprovação atual estiver no estado concluído (o status é APPROVED, CANCELLED ou DECLINED).

curl

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"
 }'

Substitua:

FILE_ID: o ID do arquivo em que a aprovação está.
ACCESS_TOKEN: o token OAuth 2.0 do seu app.

Comentar na aprovação

Para comentar em uma aprovação, use o comment método no recurso approvals e inclua os parâmetros de caminho fileId e approvalId.

O corpo da solicitação consiste em um campo obrigatório message, que é uma string que contém o comentário que você quer adicionar à aprovação.

O corpo da resposta contém uma instância do recurso approvals. A mensagem é enviada ao iniciador e aos revisores da aprovação como uma notificação e também é incluída no registro de atividades de aprovação.

curl

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."
 }'

Substitua:

FILE_ID: o ID do arquivo em que a aprovação está.
APPROVAL_ID: o ID da aprovação.
ACCESS_TOKEN: o token OAuth 2.0 do seu app.

Reatribuir revisores na aprovação

Para reatribuir revisores em uma aprovação, use o reassign método no approvals recurso e inclua os fileId e approvalId parâmetros de caminho.

O método reassign permite que o iniciador da aprovação (ou um usuário com a role=writer permissão) adicione ou substitua revisores no ReviewerResponse objeto do recurso approvals. Um usuário com a permissão role=reader só pode reatribuir uma aprovação que foi atribuída a ele. Isso permite que o usuário reatribua uma solicitação a outra pessoa que seja um revisor mais capaz.

Os revisores só podem ser reatribuídos enquanto o Status for IN_PROGRESS e o response campo do revisor que está sendo reatribuído estiver definido como NO_RESPONSE.

Observação: não é possível remover um revisor em uma aprovação. Se você precisar remover um revisor, cancele a aprovação e inicie uma nova.

O corpo da solicitação consiste nos campos opcionais addReviewers e replaceReviewers. Cada campo tem um objeto repetido para AddReviewer e ReplaceReviewer que contêm um único revisor a ser adicionado ou um par de revisores a serem substituídos. Também é possível adicionar o campo message opcional que contém o comentário que você quer enviar aos novos revisores.

O corpo da resposta contém uma instância do recurso approvals. A mensagem é enviada aos novos revisores como uma notificação e também é incluída no registro de atividades de aprovação.

curl

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."
 }'

Substitua:

FILE_ID: o ID do arquivo em que a aprovação está.
APPROVAL_ID: o ID da aprovação.
ACCESS_TOKEN: o token OAuth 2.0 do seu app.

Cancelar aprovação

Para cancelar uma aprovação, use o cancel método no recurso approvals e inclua os parâmetros de caminho fileId e approvalId.

O método cancel só pode ser chamado pelo iniciador da aprovação (ou um usuário com a permissão role=writer) enquanto o Status for IN_PROGRESS.

O corpo da solicitação consiste em um campo opcional message que é uma string que contém a mensagem para acompanhar o cancelamento da aprovação.

O corpo da resposta contém uma instância do recurso approvals. A mensagem é enviada como uma notificação e também é incluída no registro de atividades de aprovação. O Status da aprovação é definido como CANCELLED e está em um estado concluído.

curl

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."
 }'

Substitua:

FILE_ID: o ID do arquivo em que a aprovação está.
APPROVAL_ID: o ID da aprovação.
ACCESS_TOKEN: o token OAuth 2.0 do seu app.

Recusar aprovação

Para recusar uma aprovação, use o decline método no approvals recurso e inclua os fileId e approvalId parâmetros de caminho.

O método decline só pode ser chamado enquanto o Status da aprovação for IN_PROGRESS.

O corpo da solicitação consiste em um campo opcional message, que é uma string que contém a mensagem para acompanhar a recusa da aprovação.

O corpo da resposta contém uma instância do recurso approvals. A mensagem é enviada como uma notificação e também é incluída no registro de atividades de aprovação. O response campo do ReviewerResponse objeto do usuário solicitante é definido como DECLINED. Além disso, o Status da aprovação é definido como DECLINED e está em um estado concluído.

curl

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."
 }'

Substitua:

FILE_ID: o ID do arquivo em que a aprovação está.
APPROVAL_ID: o ID da aprovação.
ACCESS_TOKEN: o token OAuth 2.0 do seu app.

Aprovar aprovação

Para aprovar uma aprovação, use o approve método no recurso approvals e inclua os parâmetros de caminho fileId e approvalId.

O método approve só pode ser chamado enquanto o Status da aprovação for IN_PROGRESS.

O corpo da solicitação consiste em um campo opcional message, que é uma string que contém a mensagem para acompanhar a aprovação.

O corpo da resposta contém uma instância do recurso approvals. A mensagem é enviada como uma notificação e também é incluída no registro de atividades de aprovação. O response campo do ReviewerResponse objeto do usuário solicitante é definido como APPROVED. Além disso, se essa for a última resposta do revisor necessária, o Status da aprovação será definido como APPROVED e estará em um estado concluído.

curl

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."
 }'

Substitua:

FILE_ID: o ID do arquivo em que a aprovação está.
APPROVAL_ID: o ID da aprovação.
ACCESS_TOKEN: o token OAuth 2.0 do seu app.

Localizar aprovações atuais

O recurso approvals também pode ser usado para receber e listar o status das suas aprovações usando a API Drive.

Para visualizar aprovações em um arquivo, é necessário ter permissão para ler os metadados do arquivo. Para mais informações, consulte Papéis e permissões.

Receber aprovação

Para receber uma aprovação em um arquivo, use o get método no recurso approvals com os parâmetros de caminho fileId e approvalId. Se você não souber o ID da aprovação, poderá listar aprovações usando o método list.

O corpo da resposta contém uma instância do recurso approvals.

curl

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

Substitua:

FILE_ID: o ID do arquivo em que a aprovação está.
APPROVAL_ID: o ID da aprovação.
ACCESS_TOKEN: o token OAuth 2.0 do seu app.

Listar aprovações

Para listar aprovações em um arquivo, chame o list método no approvals recurso e inclua o fileId parâmetro de caminho.

O corpo da resposta consiste em uma lista de aprovações no arquivo. O campo items inclui informações sobre cada aprovação na forma de um recurso approvals.

Também é possível transmitir os seguintes parâmetros de consulta para personalizar a paginação ou filtrar as aprovações:

pageSize: o número máximo de aprovações a serem retornadas por página. Se você não definir pageSize, o servidor retornará até 100 aprovações.
pageToken: um token de página, recebido de uma chamada de lista anterior. Esse token é usado para recuperar a página subsequente. Ele precisa ser definido como o valor de nextPageToken de uma resposta anterior.

curl

curl -X GET \
  'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals?pageSize=10&fields=nextPageToken,items(approvalId,status)' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Accept: application/json'

Substitua:

FILE_ID: o ID do arquivo em que a aprovação está.
ACCESS_TOKEN: o token OAuth 2.0 do seu app.

Gerenciar aprovações Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Conceitos

Status de aprovação

Ciclo de vida de uma aprovação

Usar o parâmetro fields

Iniciar e administrar aprovações

Iniciar aprovação

curl

Comentar na aprovação

curl

Reatribuir revisores na aprovação

curl

Cancelar aprovação

curl

Recusar aprovação

curl

Aprovar aprovação

curl

Localizar aprovações atuais

Receber aprovação

curl

Listar aprovações

curl

Temas relacionados

Gerenciar aprovações