Gerenciar propostas de acesso pendentes

Uma proposta de acesso é uma solicitação de um requerente a um aprovador para conceder a um destinatário acesso a um item do Google Drive.

Um aprovador pode analisar e resolver todas as propostas de acesso pendentes 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 vai receber 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.

Usar o parâmetro "fields"

Se você quiser especificar os campos a serem retornados na resposta, defina o parâmetro do sistema fields com qualquer método do recurso accessproposals. Se você omitir o parâmetro fields, o servidor vai retornar um conjunto padrão de campos específicos do método. Para retornar campos diferentes, consulte Retornar campos específicos.

Receber uma proposta de acesso pendente

Para receber uma proposta de acesso, use o método get no recurso accessproposals com os parâmetros de caminho fileId e proposalId. Se você não souber o ID da proposta, liste as propostas de acesso pendentes usando o método list.

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 accessproposals que representa uma lista de propostas de acesso não resolvidas no arquivo.

O objeto accessproposals inclui informações sobre cada proposta, como o solicitante, o destinatário e a mensagem adicionada pelo solicitante. Ele também inclui um objeto RoleAndView 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 RoleAndView de role=reader e view=published, além de um objeto RoleAndView 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. Forneça 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. Para mais informações, consulte Papéis e permissões. Um parâmetro de consulta opcional adicional de sendNotification 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. A proposta de acesso resolvida não é mais retornada pelo método list. Depois que a proposta for aceita, o usuário precisará usar o recurso permissions para atualizar as permissões em um arquivo ou pasta. Para mais informações, consulte Atualizar permissões.