Gerenciar propostas de acesso pendentes

Uma proposta de acesso é uma proposta de um solicitante para um aprovador conceder a um destinatário acesso a um item do Google Drive.

Um aprovador pode analisar e realizar ações em todas as propostas de acesso não resolvidas nos arquivos do Drive. Isso significa que você pode acelerar o processo de aprovação consultando e resolvendo propostas de acesso de forma programática. Ela também permite que um aprovador veja as propostas de forma agregada.

A API Google Drive fornece o recurso accessproposals para que você possa ver e resolver propostas de acesso pendentes. Os métodos do recurso accessproposals funcionam em arquivos, pastas e arquivos em um drive compartilhado, mas não no drive compartilhado.

Os termos a seguir são específicos das propostas de acesso:

  • Solicitante: o usuário que inicia a proposta de acesso a um item do Drive.
  • Destinatário: o usuário que recebe as permissões adicionais em um arquivo se a proposta de acesso for concedida. Muitas vezes, o destinatário é o mesmo que o solicitante, mas nem sempre.
  • Aprovador: o usuário responsável por aprovar (ou negar) a proposta de acesso. Isso geralmente acontece porque eles são proprietários do documento ou têm permissão para compartilhá-lo.

Listar propostas de acesso pendentes

Para listar todas as propostas de acesso pendentes em um item do Drive, chame o método list() no recurso accessproposals e inclua o parâmetro de caminho fileId.

Somente os aprovadores de um arquivo podem listar as propostas pendentes nele. Um aprovador é um usuário com a capacidade can_approve_access_proposals no arquivo. Se o solicitante não for um aprovador, uma lista vazia será retornada. Para mais informações sobre capabilities, consulte Entender os recursos de arquivos.

O corpo da resposta consiste em um objeto AccessProposal que representa uma lista de propostas de acesso não resolvidas no arquivo.

O objeto AccessProposal inclui informações sobre cada proposta, como o solicitante, o destinatário e a mensagem adicionada pelo solicitante. Ele também inclui um objeto AccessProposalRoleAndView que agrupa o role proposto pelo solicitante com um view. Como role é um campo repetido, pode haver vários valores para cada proposta. Por exemplo, uma proposta pode ter um objeto AccessProposalRoleAndView de role=reader e view=published, além de um objeto AccessProposalRoleAndView adicional com apenas o valor role=writer. Para mais informações, consulte Visualizações.

Transmita os seguintes parâmetros de consulta para personalizar a paginação ou filtrar propostas de acesso:

  • pageToken: um token de página recebido de uma chamada de lista anterior. Informe esse token para recuperar a página subsequente.

  • pageSize: o número máximo de propostas de acesso a serem retornadas por página.

Resolver propostas de acesso pendentes

Para resolver todas as propostas de acesso pendentes em um item do Drive, chame o método resolve() no recurso accessproposals e inclua os parâmetros de caminho fileId e proposalId.

O método resolve() inclui um parâmetro de consulta action que indica a ação a ser tomada na proposta. O objeto Action rastreia a mudança de estado da proposta para sabermos se ela está sendo aceita ou negada.

O método resolve() também inclui os parâmetros de consulta opcionais role e view. Os únicos papéis aceitos são writer, commenter e reader. Se a função não for especificada, o padrão será reader. Um parâmetro de consulta opcional adicional de send_notification permite enviar uma notificação por e-mail ao solicitante quando a proposta é aceita ou recusada.

Assim como no método list(), os usuários que resolvem a proposta precisam ter a capacidade can_approve_access_proposals no arquivo. Para mais informações sobre capabilities, consulte Entender os recursos de arquivos.

As propostas são resolvidas usando os mesmos padrões listados em Cenários para compartilhamento de recursos do Drive. Se houver várias propostas para o mesmo usuário, mas com funções diferentes, o seguinte se aplica:

  • Se uma proposta for aceita e outra negada, a função aceita será aplicada ao item do Drive.
  • Se as duas propostas forem aceitas ao mesmo tempo, a proposta com a permissão mais alta (por exemplo, role=writer em vez de role=reader) será aplicada. A outra proposta de acesso é removida do item.

Depois de enviar uma proposta ao método resolve(), a ação de compartilhamento é concluída. O AccessProposal não é mais retornado pelo método list(). Depois que a proposta for aceita, o usuário precisará usar a coleção permissions para atualizar as permissões em um arquivo ou pasta. Para mais informações, consulte Atualizar permissões.