Gerenciar propostas de acesso pendentes

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

Um aprovador pode analisar e agir em todas as propostas de acesso não resolvidas nos arquivos do Drive. Isso significa que você pode acelerar o processo de aprovação fazendo consultas programáticas para propostas de acesso e resolvendo-as. Ele também permite que as propostas sejam visualizadas em conjunto por um aprovador.

A API Google Drive fornece o recurso accessproposals para que você possa conferir 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 para 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 a pessoa é proprietária do documento ou tem permissão para compartilhar o documento.

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 em um arquivo podem listar as propostas pendentes em um arquivo. 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 Noções básicas sobre os recursos de arquivo.

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 que o solicitante adicionou. 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 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 este token para recuperar a página seguinte.

  • 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 denota a ação a ser realizada na proposta. O objeto Action rastreia a mudança de estado da proposta para sabermos se ela foi aceita ou negada.

O método resolve() também inclui os parâmetros de consulta opcionais de role e view. Os únicos papéis aceitos são writer, commenter e reader. Se o papel não for especificado, 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 for aceita ou recusada.

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

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

  • Se uma proposta for aceita e outra for negada, o papel aceito será aplicado 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 para o 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.