Gerenciar propostas de acesso pendentes

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

Um aprovador pode analisar e agir em todas as propostas de acesso não resolvidas em arquivos do Drive. Isso significa que você pode acelerar o processo de aprovação consultando programaticamente as propostas de acesso e resolvendo-as. Também permite que as propostas sejam visualizadas de forma agregada por um aprovador.

A API Google Drive fornece o accessproposals recurso para que você possa visualizar 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 requerente, mas nem sempre.
  • Aprovador: o usuário responsável por aprovar (ou negar) a proposta de acesso. Isso geralmente acontece porque ele é proprietário do documento ou tem a capacidade de compartilhá-lo.

Usar o parâmetro "fields"

Se você quiser especificar os campos a serem retornados na resposta, defina o fields parâmetro do sistema com qualquer método do recurso accessproposals. Se você omitir o parâmetro fields, o servidor 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 get método no recurso accessproposals com os parâmetros de caminho fileId e proposalId. Se você não souber o ID da proposta, poderá listar 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 list método no accessproposals recurso e inclua o fileId parâmetro de caminho.

Somente os aprovadores de 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 Entender as capacidades 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 RoleAndView objeto que agrupa o role proposto do solicitante com um view. Como role é um campo repetido, vários podem existir 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 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 indica a ação a ser realizada na proposta. O objeto Action acompanha a mudança de estado da proposta para que saibamos se ela está sendo aceita ou negada.

O método resolve também inclui os parâmetros de consulta opcionais de role e view. As únicas funções compatíveis são writer, commenter e reader. Se a função não for especificada, ela será definida como reader por padrão. Para mais informações, consulte Funções e permissões. Um parâmetro de consulta opcional adicional de sendNotification permite enviar uma notificação por e-mail ao requerente quando a proposta é aceita ou negada.

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 as capacidades de arquivos.

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 será aplicado:

  • Se uma proposta for aceita e outra for 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 será removida do item.

Depois de enviar uma proposta para o método resolve, a ação de compartilhamento será concluída. A proposta de acesso resolvida não será mais retornada pelo método list. Depois que a proposta for aceita, o usuário precisará usar o permissions recurso para atualizar as permissões em um arquivo ou pasta. Para mais informações, consulte Atualizar permissões.