Compartilhar arquivos, pastas e drives

Cada arquivo, pasta e drive compartilhado do Google Drive tem recursos Permissions associados. Cada recurso identifica a permissão para uma type específica (usuário, grupo, domínio, qualquer pessoa) e role, como "comentador" ou "leitor". Por exemplo, um arquivo pode ter uma permissão que concede acesso somente leitura a um usuário específico (type=user) (role=reader), enquanto outra permissão concede aos membros de um grupo específico (type=group) a capacidade de adicionar comentários a um arquivo (role=commenter).

Para uma lista completa de papéis e as operações permitidas por cada um deles, consulte Papéis.

Situações para compartilhar recursos do Drive

Existem cinco tipos de cenários de compartilhamento:

  1. Para compartilhar um arquivo no Meu Drive, o usuário precisa ter role=writer ou mais recente.

    • Se o valor booleano writersCanShare for definido como False para o arquivo, o usuário precisará ter role=owner.

    • Se o usuário com role=writer tiver acesso temporário regido por uma data e hora de validade, ele não poderá compartilhar o arquivo.

    Para mais informações, consulte Adicionar uma data de validade.

  2. Para compartilhar uma pasta no Meu Drive, o usuário precisa ter role=writer ou mais.

    • Se o valor booleano writersCanShare for definido como False para o arquivo, o usuário precisará ter a role=owner mais permissiva.

    • O acesso temporário (regido por uma data de validade e um horário) não é permitido nas pastas da seção Meu Drive com role=writer.

  3. Para compartilhar um arquivo em um drive compartilhado, o usuário precisa ter role=writer ou mais versão.

    • A configuração writersCanShare não é válida para os itens nos drives compartilhados. É tratado como se fosse sempre definido como True.

    • O acesso temporário (regido por uma data e hora de validade) não é permitido nos drives compartilhados.

  4. Para compartilhar uma pasta em um drive compartilhado, o usuário precisa ter o role=organizer.

    • Se a restrição sharingFoldersRequiresOrganizerPermission em um drive compartilhado estiver definida como False, os usuários com role=fileOrganizer vão poder compartilhar pastas nesse drive compartilhado.

  5. Para gerenciar a associação ao drive compartilhado, o usuário precisa ter o role=organizer. Somente usuários e grupos podem ser membros de drives compartilhados.

Propagação da permissão

As listas de permissões de uma pasta são propagadas para baixo, e todos os arquivos e pastas filhos herdam as permissões da pasta mãe. Sempre que as permissões ou a hierarquia são alteradas, a propagação ocorre recursivamente em todas as pastas aninhadas. Por exemplo, se um arquivo existir em uma pasta e ela for movida para outra, as permissões na nova pasta vão ser propagadas para o arquivo. Se a nova pasta conceder ao usuário do arquivo um novo papel, como "gravador", ele substituirá o papel antigo.

Por outro lado, se um arquivo herda role=writer de uma pasta e é movido para outra pasta que fornece um papel de "leitor", o arquivo agora herda role=reader.

Não é possível remover permissões herdadas de um arquivo ou pasta em um drive compartilhado. Em vez disso, essas permissões precisam ser ajustadas no pai direto ou indireto do qual foram herdadas. As permissões herdadas podem ser removidas dos itens em "Meu Drive" ou "Compartilhados comigo".

Por outro lado, as permissões herdadas podem ser substituídas em um arquivo ou uma pasta em "Meu Drive". Portanto, se um arquivo herdar role=writer de uma pasta Meu Drive, você poderá definir role=reader no arquivo para diminuir o nível de permissão.

Recursos

O recurso Permissions não determina a capacidade do usuário atual de realizar ações em um arquivo ou uma pasta. Em vez disso, um recurso Files contém um conjunto de campos capabilities booleanos usados para indicar se uma ação pode ser executada em um arquivo ou uma pasta. A API Google Drive define esses campos com base no recurso de permissões do usuário atual associado ao arquivo ou pasta.

Por exemplo, quando Alex faz login no seu app e tenta compartilhar um arquivo, a função de Alex é verificada em termos de permissões no arquivo. Se o papel permitir que eles compartilhem um arquivo, os capabilities relacionados ao arquivo, como canShare, vão ser preenchidos em relação ao papel. Se Alex quiser compartilhar o arquivo, o app verificará a capabilities para garantir que canShare esteja definido como true.

Criar uma permissão

Os dois campos a seguir são necessários ao criar uma permissão:

  • type: o type identifica o escopo da permissão (user, group, domain ou anyone). Uma permissão com type=user se aplica a um usuário específico, enquanto uma permissão com type=domain se aplica a todos em um domínio específico.

  • role: o campo role identifica as operações que o type pode executar. Por exemplo, uma permissão com type=user e role=reader concede a um usuário específico acesso somente leitura ao arquivo ou à pasta. Ou uma permissão com type=domain e role=commenter permite que todos no domínio adicionem comentários a um arquivo. Para ver uma lista completa de papéis e as operações permitidas por cada um deles, consulte Papéis.

Ao criar uma permissão em que type=user ou type=group, você também precisa fornecer um emailAddress para vincular o usuário ou grupo específico à permissão.

Ao criar uma permissão em que type=domain, também é necessário fornecer um domain para vincular um domínio específico à permissão.

Para criar uma permissão, faça o seguinte:

  1. Use o método permissions.create com o fileId para a pasta ou o arquivo associado.
  2. No corpo da solicitação, identifique o type e o role.
  3. Se type=user ou type=group, forneça um emailAddress. Se type=domain, forneça um domain.

Usar públicos-alvo

Os públicos-alvo são grupos de pessoas, como departamentos ou equipes, que você pode recomendar aos usuários para compartilhar itens. É possível incentivar os usuários a compartilhar itens com um público mais específico ou limitado, e não com toda a organização. Os públicos-alvo ajudam a melhorar a segurança e a privacidade dos dados, além de facilitar o compartilhamento adequado. Para mais informações, consulte Sobre públicos-alvo.

Para usar públicos-alvo, faça o seguinte:

  1. Faça login no Google Admin Console.

    Para realizar essa tarefa, você precisa fazer login usando uma conta com privilégios de superadministrador.

  2. Acesse Menu > Diretório > Públicos-alvo.

  3. Na lista de públicos-alvo, clique no nome do público-alvo. Para criar um público-alvo, consulte Criar um público-alvo.

  4. Copie o ID exclusivo do URL do público-alvo: https://admin.google.com/ac/targetaudiences/ID.

  5. Crie uma permissão com type=domain e defina o campo domain como ID.audience.googledomains.com.

Para ver como os usuários interagem com os públicos-alvo, consulte Experiência do usuário para compartilhamento de links.

Recuperar todas as permissões de um arquivo, uma pasta ou um drive compartilhado

Use o método permissions.list para recuperar todas as permissões de um arquivo, pasta ou drive compartilhado.

Verificar as permissões do usuário

Quando o app abre um arquivo, ele precisa verificar os recursos do arquivo e renderizar a IU para refletir as permissões do usuário atual. Por exemplo, se o usuário não tiver um recurso canComment no arquivo, a capacidade de comentar vai ser desativada na IU.

Para verificar os recursos, chame files.get com o fileId e o parâmetro fields definido no campo capabilities.

Para mais informações sobre como retornar campos usando o parâmetro fields, consulte Retornar campos específicos para um arquivo.

Determinar a origem da função de pastas e arquivos de drives compartilhados

Para alterar o papel em um arquivo ou uma pasta, você precisa saber a origem dele. Para drives compartilhados, a origem de um papel pode ser baseada na associação ao drive compartilhado, no papel em uma pasta ou no papel em um arquivo.

Para determinar a origem do papel de um drive compartilhado ou de itens dentro dele, chame permissions.get com o parâmetro fileId, permissionId e fields definido como o campo permissionDetails. Para encontrar o permissionId, use permissions.list com o fileId.

Esse campo enumera todas as permissões herdadas e diretas de arquivo para o usuário, grupo ou domínio.

Mudar permissões

Para alterar as permissões de um arquivo ou uma pasta, mude a função atribuída:

  1. Chame permissions.update com o permissionId da permissão para mudar e o fileId para o arquivo, a pasta ou o drive compartilhado associado. Para encontrar o permissionId, use permissions.list com o fileId.

  2. Na solicitação, identifique o novo role.

Você pode conceder permissões em arquivos ou pastas individuais em um drive compartilhado, mesmo que o usuário ou grupo já seja membro. Por exemplo, Alex tem role=commenter como parte da associação a um drive compartilhado. No entanto, o app pode conceder a Alex role=writer um arquivo em um drive compartilhado. Nesse caso, como o novo papel é mais permissivo do que o concedido por meio da associação, a nova permissão se torna o papel efetivo do arquivo ou pasta.

Revogar acesso a um arquivo ou uma pasta

Para revogar o acesso a um arquivo ou uma pasta, chame delete com fileId e permissionId para excluir a permissão.

Para os itens em "Meu Drive", é possível excluir uma permissão herdada. A exclusão de uma permissão herdada revoga o acesso ao item e aos itens filhos, se algum.

Para itens em um drive compartilhado, as permissões herdadas não podem ser revogadas. Atualize ou revogue a permissão no arquivo ou na pasta mãe.

A operação delete também é usada para excluir permissões aplicadas diretamente a um arquivo ou pasta de drive compartilhado.

Transferir a propriedade de arquivos para outra conta do Google Workspace na mesma organização

A propriedade dos arquivos em "Meu Drive" pode ser transferida de uma conta do Google Workspace para outra na mesma organização. Os arquivos dentro dela pertencem a uma organização proprietária de um drive compartilhado. Portanto, as transferências de propriedade não são compatíveis com arquivos e pastas em drives compartilhados. Os organizadores de um drive compartilhado podem mover os itens e para o "Meu Drive" deles, o que transfere a propriedade para eles.

Para transferir a propriedade de um arquivo em "Meu Drive", siga um destes procedimentos:

  • Crie uma permissão de arquivo que concede acesso de proprietário (role=owner) a um usuário específico (type=user).

  • Atualiza a permissão de um arquivo existente com role=owner e transfere a propriedade para o usuário especificado (transferOwnership=true).

Transferir a propriedade de arquivos de uma conta pessoal para outra

A propriedade dos arquivos pode ser transferida entre contas pessoais. No entanto, o Drive não transfere a propriedade de um arquivo entre duas contas pessoais até que o novo proprietário em potencial concorde explicitamente com a transferência. Para transferir a propriedade de arquivo de uma conta pessoal para outra, siga estas etapas:

  1. O proprietário atual inicia uma transferência de propriedade criando ou atualizando a permissão do arquivo do novo proprietário em potencial. A permissão precisa incluir essas configurações: role=writer, type=user e pendingOwner=true. Se o novo proprietário estiver criando uma permissão, ele receberá uma notificação por e-mail.

  2. O novo proprietário aceita a solicitação de transferência de propriedade ao criar ou atualizar a permissão do arquivo. A permissão precisa incluir estas configurações: role=owner e transferOwnership=true. Se o novo proprietário estiver criando uma nova permissão, uma notificação por e-mail será enviada ao proprietário anterior, indicando que a propriedade foi transferida.

Quando um arquivo é transferido, o papel do proprietário anterior recebe o downgrade para writer.

Alterar várias permissões com solicitações em lote

Recomendamos o uso de solicitações em lote para modificar várias permissões.

Veja a seguir um exemplo de modificação de permissão em lote com uma biblioteca de cliente.

Java

drive/snippets/drive_v3/src/main/java/ShareFile.java
import com.google.api.client.googleapis.batch.BatchRequest;
import com.google.api.client.googleapis.batch.json.JsonBatchCallback;
import com.google.api.client.googleapis.json.GoogleJsonError;
import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.client.http.HttpHeaders;
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.drive.Drive;
import com.google.api.services.drive.DriveScopes;
import com.google.api.services.drive.model.Permission;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

/* Class to demonstrate use-case of modify permissions. */
public class ShareFile {

  /**
   * Batch permission modification.
   * realFileId file Id.
   * realUser User Id.
   * realDomain Domain of the user ID.
   *
   * @return list of modified permissions if successful, {@code null} otherwise.
   * @throws IOException if service account credentials file not found.
   */
  public static List<String> shareFile(String realFileId, String realUser, String realDomain)
      throws IOException {
        /* Load pre-authorized user credentials from the environment.
         TODO(developer) - See https://developers.google.com/identity for
         guides on implementing OAuth2 for your application.application*/
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(Arrays.asList(DriveScopes.DRIVE_FILE));
    HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(
        credentials);

    // Build a new authorized API client service.
    Drive service = new Drive.Builder(new NetHttpTransport(),
        GsonFactory.getDefaultInstance(),
        requestInitializer)
        .setApplicationName("Drive samples")
        .build();

    final List<String> ids = new ArrayList<String>();


    JsonBatchCallback<Permission> callback = new JsonBatchCallback<Permission>() {
      @Override
      public void onFailure(GoogleJsonError e,
                            HttpHeaders responseHeaders)
          throws IOException {
        // Handle error
        System.err.println(e.getMessage());
      }

      @Override
      public void onSuccess(Permission permission,
                            HttpHeaders responseHeaders)
          throws IOException {
        System.out.println("Permission ID: " + permission.getId());

        ids.add(permission.getId());

      }
    };
    BatchRequest batch = service.batch();
    Permission userPermission = new Permission()
        .setType("user")
        .setRole("writer");

    userPermission.setEmailAddress(realUser);
    try {
      service.permissions().create(realFileId, userPermission)
          .setFields("id")
          .queue(batch, callback);

      Permission domainPermission = new Permission()
          .setType("domain")
          .setRole("reader");

      domainPermission.setDomain(realDomain);

      service.permissions().create(realFileId, domainPermission)
          .setFields("id")
          .queue(batch, callback);

      batch.execute();

      return ids;
    } catch (GoogleJsonResponseException e) {
      // TODO(developer) - handle error appropriately
      System.err.println("Unable to modify permission: " + e.getDetails());
      throw e;
    }
  }
}

Python

drive/snippets/drive-v3/file_snippet/share_file.py
from __future__ import print_function

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def share_file(real_file_id, real_user, real_domain):
    """Batch permission modification.
    Args:
        real_file_id: file Id
        real_user: User ID
        real_domain: Domain of the user ID
    Prints modified permissions

    Load pre-authorized user credentials from the environment.
    TODO(developer) - See https://developers.google.com/identity
    for guides on implementing OAuth2 for the application.
    """
    creds, _ = google.auth.default()

    try:
        # create drive api client
        service = build('drive', 'v3', credentials=creds)
        ids = []
        file_id = real_file_id

        def callback(request_id, response, exception):
            if exception:
                # Handle error
                print(exception)
            else:
                print(f'Request_Id: {request_id}')
                print(F'Permission Id: {response.get("id")}')
                ids.append(response.get('id'))

        # pylint: disable=maybe-no-member
        batch = service.new_batch_http_request(callback=callback)
        user_permission = {
            'type': 'user',
            'role': 'writer',
            'emailAddress': 'user@example.com'
        }
        batch.add(service.permissions().create(fileId=file_id,
                                               body=user_permission,
                                               fields='id',))
        domain_permission = {
            'type': 'domain',
            'role': 'reader',
            'domain': 'example.com'
        }
        domain_permission['domain'] = real_domain
        batch.add(service.permissions().create(fileId=file_id,
                                               body=domain_permission,
                                               fields='id',))
        batch.execute()

    except HttpError as error:
        print(F'An error occurred: {error}')
        ids = None

    return ids


if __name__ == '__main__':
    share_file(real_file_id='1dUiRSoAQKkM3a4nTPeNQWgiuau1KdQ_l',
               real_user='gduser1@workspacesamples.dev',
               real_domain='workspacesamples.dev')

Node.js

drive/snippets/drive_v3/file_snippets/share_file.js
/**
 * Batch permission modification
 * @param{string} fileId file ID
 * @param{string} targetUserEmail username
 * @param{string} targetDomainName domain
 * @return{list} permission id
 * */
async function shareFile(fileId, targetUserEmail, targetDomainName) {
  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  // Get credentials and build service
  // TODO (developer) - Use appropriate auth mechanism for your app
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/drive',
  });
  const service = google.drive({version: 'v3', auth});
  const permissionIds = [];

  const permissions = [
    {
      type: 'user',
      role: 'writer',
      emailAddress: targetUserEmail, // 'user@partner.com',
    },
    {
      type: 'domain',
      role: 'writer',
      domain: targetDomainName, // 'example.com',
    },
  ];
  // Note: Client library does not currently support HTTP batch
  // requests. When possible, use batched requests when inserting
  // multiple permissions on the same item. For this sample,
  // permissions are inserted serially.
  for (const permission of permissions) {
    try {
      const result = await service.permissions.create({
        resource: permission,
        fileId: fileId,
        fields: 'id',
      });
      permissionIds.push(result.data.id);
      console.log(`Inserted permission id: ${result.data.id}`);
    } catch (err) {
      // TODO(developer): Handle failed permissions
      console.error(err);
    }
  }
  return permissionIds;
}

PHP

drive/snippets/drive_v3/src/DriveShareFile.php
use Google\Client;
use Google\Service\Drive;
function shareFile()
{
    try {
        $client = new Client();
        $client->useApplicationDefaultCredentials();
        $client->addScope(Drive::DRIVE);
        $driveService = new Drive($client);
        $realFileId = readline("Enter File Id: ");
        $realUser = readline("Enter user email address: ");
        $realDomain = readline("Enter domain name: ");
        $ids = array();
            $fileId = '1sTWaJ_j7PkjzaBWtNc3IzovK5hQf21FbOw9yLeeLPNQ';
            $fileId = $realFileId;
            $driveService->getClient()->setUseBatch(true);
            try {
                $batch = $driveService->createBatch();

                $userPermission = new Drive\Permission(array(
                    'type' => 'user',
                    'role' => 'writer',
                    'emailAddress' => 'user@example.com'
                ));
                $userPermission['emailAddress'] = $realUser;
                $request = $driveService->permissions->create(
                    $fileId, $userPermission, array('fields' => 'id'));
                $batch->add($request, 'user');
                $domainPermission = new Drive\Permission(array(
                    'type' => 'domain',
                    'role' => 'reader',
                    'domain' => 'example.com'
                ));
                $userPermission['domain'] = $realDomain;
                $request = $driveService->permissions->create(
                    $fileId, $domainPermission, array('fields' => 'id'));
                $batch->add($request, 'domain');
                $results = $batch->execute();

                foreach ($results as $result) {
                    if ($result instanceof Google_Service_Exception) {
                        // Handle error
                        printf($result);
                    } else {
                        printf("Permission ID: %s\n", $result->id);
                        array_push($ids, $result->id);
                    }
                }
            } finally {
                $driveService->getClient()->setUseBatch(false);
            }
            return $ids;
    } catch(Exception $e) {
        echo "Error Message: ".$e;
    }

}

.NET

drive/snippets/drive_v3/DriveV3Snippets/ShareFile.cs
using Google.Apis.Auth.OAuth2;
using Google.Apis.Drive.v3;
using Google.Apis.Drive.v3.Data;
using Google.Apis.Requests;
using Google.Apis.Services;

namespace DriveV3Snippets
{
    // Class to demonstrate use-case of Drive modify permissions.
    public class ShareFile
    {
        /// <summary>
        /// Batch permission modification.
        /// </summary>
        /// <param name="realFileId">File id.</param>
        /// <param name="realUser">User id.</param>
        /// <param name="realDomain">Domain id.</param>
        /// <returns>list of modified permissions, null otherwise.</returns>
        public static IList<String> DriveShareFile(string realFileId, string realUser, string realDomain)
        {
            try
            {
                /* Load pre-authorized user credentials from the environment.
                 TODO(developer) - See https://developers.google.com/identity for
                 guides on implementing OAuth2 for your application. */
                GoogleCredential credential = GoogleCredential.GetApplicationDefault()
                    .CreateScoped(DriveService.Scope.Drive);

                // Create Drive API service.
                var service = new DriveService(new BaseClientService.Initializer
                {
                    HttpClientInitializer = credential,
                    ApplicationName = "Drive API Snippets"
                });

                var ids = new List<String>();
                var batch = new BatchRequest(service);
                BatchRequest.OnResponse<Permission> callback = delegate(
                    Permission permission,
                    RequestError error,
                    int index,
                    HttpResponseMessage message)
                {
                    if (error != null)
                    {
                        // Handle error
                        Console.WriteLine(error.Message);
                    }
                    else
                    {
                        Console.WriteLine("Permission ID: " + permission.Id);
                    }
                };
                Permission userPermission = new Permission()
                {
                    Type = "user",
                    Role = "writer",
                    EmailAddress = realUser
                };

                var request = service.Permissions.Create(userPermission, realFileId);
                request.Fields = "id";
                batch.Queue(request, callback);

                Permission domainPermission = new Permission()
                {
                    Type = "domain",
                    Role = "reader",
                    Domain = realDomain
                };
                request = service.Permissions.Create(domainPermission, realFileId);
                request.Fields = "id";
                batch.Queue(request, callback);
                var task = batch.ExecuteAsync();
                task.Wait();
                return ids;
            }
            catch (Exception e)
            {
                // TODO(developer) - handle error appropriately
                if (e is AggregateException)
                {
                    Console.WriteLine("Credential Not found");
                }
                else
                {
                    throw;
                }
            }
            return null;
        }
    }
}