Делитесь файлами, папками и дисками

Каждый файл, папка и общий диск Google Диска имеют соответствующие ресурсы permissions . Каждый ресурс идентифицирует разрешение для определенного type ( user , group , domain , anyone ) и role ( owner , organizer , fileOrganizer , writer , commenter , reader ). Например, файл может иметь разрешение, предоставляющее конкретному пользователю ( type=user ) доступ только для чтения ( role=reader ), в то время как другое разрешение предоставляет членам определенной группы ( type=group ) возможность добавлять комментарии к файлу ( role=commenter ).

Полный список ролей и операций, разрешенных каждой из них, см. в разделе Роли и разрешения .

Как работают разрешения

Списки разрешений для папки распространяются вниз. Все дочерние файлы и папки наследуют разрешения от родительского. Всякий раз, когда разрешения или иерархия изменяются, распространение происходит рекурсивно по всем вложенным папкам. Например, если файл существует в папке, а затем эта папка перемещается в другую папку, разрешения для новой папки распространяются на файл. Если новая папка предоставляет пользователю файла новую роль, например «писатель», она переопределяет его старую роль.

И наоборот, если файл наследует role=writer из папки и перемещается в другую папку, предоставляющую роль «читателя», теперь файл наследует role=reader .

Унаследованные разрешения нельзя удалить из файла или папки на общем диске. Вместо этого эти разрешения необходимо настроить для прямого или косвенного родительского объекта, от которого они были унаследованы. Унаследованные разрешения можно удалить для элементов в разделах «Мой диск» или «Доступно мне».

И наоборот, унаследованные разрешения могут быть переопределены для файла или папки в «Моем диске». Таким образом, если файл наследует role=writer из папки «Мой диск», вы можете установить для файла role=reader чтобы снизить уровень его разрешений.

Понимание возможностей файлов

Ресурс permissions в конечном итоге не определяет способность текущего пользователя выполнять действия с файлом или папкой. Вместо этого ресурс files содержит набор логических полей capabilities используемых для указания того, можно ли выполнить действие над файлом или папкой. API Google Диска устанавливает эти поля на основе ресурсов разрешений текущего пользователя, связанных с файлом или папкой.

Например, когда Алекс входит в ваше приложение и пытается поделиться файлом, роль Алекса проверяется на наличие разрешений для файла. Если роль позволяет им делиться файлом, capabilities связанные с файлом, например canShare , заполняются относительно роли. Если Алекс хочет поделиться файлом, ваше приложение проверяет capabilities , чтобы убедиться, что для canShare установлено значение true .

Пример получения capabilities файла см. в разделе Получение возможностей файла .

Получить возможности файла

Когда ваше приложение открывает файл, оно должно проверить возможности файла и отобразить пользовательский интерфейс, отражающий разрешения текущего пользователя. Например, если у пользователя нет возможности canComment для файла, возможность комментирования должна быть отключена в пользовательском интерфейсе.

Чтобы проверить возможности, вызовите метод get() ресурса files с параметром пути fileId и параметром fields , установленным в поле capabilities . Дополнительную информацию о возврате полей с помощью параметра fields см. в разделе Возврат определенных полей .

Показать пример

В следующем примере кода показано, как проверить разрешения пользователя. Ответ возвращает список возможностей, которые пользователь имеет в отношении файла. Каждая возможность соответствует детальному действию, которое может предпринять пользователь. Некоторые поля заполняются только для объектов на общих дисках.

Запрос

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=capabilities

Ответ

{
  "capabilities": {
    "canAcceptOwnership": false,
    "canAddChildren": false,
    "canAddMyDriveParent": false,
    "canChangeCopyRequiresWriterPermission": true,
    "canChangeSecurityUpdateEnabled": false,
    "canComment": true,
    "canCopy": true,
    "canDelete": true,
    "canDownload": true,
    "canEdit": true,
    "canListChildren": false,
    "canModifyContent": true,
    "canModifyContentRestriction": true,
    "canModifyLabels": true,
    "canMoveChildrenWithinDrive": false,
    "canMoveItemOutOfDrive": true,
    "canMoveItemWithinDrive": true,
    "canReadLabels": true,
    "canReadRevisions": true,
    "canRemoveChildren": false,
    "canRemoveMyDriveParent": true,
    "canRename": true,
    "canShare": true,
    "canTrash": true,
    "canUntrash": true
  }
}

Сценарии совместного использования ресурсов Диска

Существует пять различных типов сценариев совместного использования:

  1. Чтобы поделиться файлом на «Моем диске», у пользователя должны быть role=writer или role=owner .

  2. Чтобы предоставить общий доступ к папке на «Моем диске», у пользователя должны быть role=writer или role=owner .

  3. Чтобы поделиться файлом на общем диске, у пользователя должна быть role=writer , role=fileOrganizer или role=organizer .

    • Параметр writersCanShare не применяется к объектам на общих дисках. Он рассматривается так, как будто для него всегда установлено значение true .
  4. Чтобы предоставить общий доступ к папке на общем диске, у пользователя должен быть role=organizer .

    • Если для sharingFoldersRequiresOrganizerPermission на общем диске установлено значение false , пользователи с role=fileOrganizer могут совместно использовать папки на этом общем диске.
  5. Чтобы управлять членством в общем диске, у пользователя должен быть role=organizer . Участниками общих дисков могут быть только пользователи и группы.

Создать разрешение

Следующие два поля необходимы при создании разрешения:

  • type : type определяет область разрешений ( user , group , domain или anyone ). Разрешение с type=user применяется к конкретному пользователю, тогда как разрешение с type=domain применяется ко всем в определенном домене.

  • role : Поле role определяет операции, которые может выполнять type . Например, разрешение с type=user и role=reader предоставляет конкретному пользователю доступ только для чтения к файлу или папке. Или разрешение с type=domain и role=commenter позволяет всем в домене добавлять комментарии к файлу. Полный список ролей и операций, разрешенных каждой из них, см. в разделе Роли и разрешения .

Когда вы создаете разрешение, где type=user или type=group , вы также должны указать emailAddress , чтобы привязать конкретного пользователя или группу к разрешению.

Когда вы создаете разрешение, где type=domain , вы также должны указать domain , чтобы привязать определенный домен к разрешению.

Чтобы создать разрешение:

  1. Используйте метод create() с параметром пути fileId для связанного файла или папки.
  2. В теле запроса укажите type и role .
  3. Если type=user или type=group , укажите emailAddress . Если type=domain , укажите domain .

Показать пример

В следующем примере кода показано, как создать разрешение. Ответ возвращает экземпляр ресурса Permission , включая назначенный permissionId .

Запрос

POST https://www.googleapis.com/drive/v3/files/FILE_ID/permissions
{
  "requests": [
    {
        "type": "user",
        "role": "commenter",
        "emailAddress": "alex@altostrat.com"
    }
  ]
}

Ответ

{
    "kind": "drive#permission",
    "id": "PERMISSION_ID",
    "type": "user",
    "role": "commenter"
}

Используйте целевые аудитории

Целевая аудитория — это группы людей, например отделы или команды, которым вы можете порекомендовать пользователям поделиться своими элементами. Вы можете поощрять пользователей делиться элементами с более конкретной или ограниченной аудиторией, а не со всей вашей организацией. Целевые аудитории могут помочь вам повысить безопасность и конфиденциальность ваших данных, а также облегчить пользователям надлежащий обмен ими. Дополнительную информацию см. в разделе О целевых аудиториях .

Чтобы использовать целевые аудитории:

  1. В консоли администратора Google выберите > Каталог > Целевые аудитории .

    Перейти к Целевые аудитории

    Для выполнения этой задачи вам необходимо войти в систему, используя учетную запись с правами суперадминистратора .

  2. В списке «Целевые аудитории» щелкните название целевой аудитории. Чтобы создать целевую аудиторию, см. Создание целевой аудитории.

  3. Скопируйте уникальный идентификатор из URL-адреса целевой аудитории: https://admin.google.com/ac/targetaudiences/ ID .

  4. Создайте разрешение с type=domain и задайте для поля domain ID .audience.googledomains.com .

Чтобы просмотреть, как пользователи взаимодействуют с целевыми аудиториями, см. раздел «Взаимодействие с пользователями при обмене ссылками» .

Список всех разрешений

Используйте метод list() ресурса permissions , чтобы получить все разрешения для файла, папки или общего диска.

Показать пример

В следующем примере кода показано, как получить все разрешения. Ответ возвращает список разрешений.

Запрос

GET https://www.googleapis.com/drive/v3/files/FILE_ID/permissions

Ответ

{
  "kind": "drive#permissionList",
  "permissions": [
    {
      "id": "PERMISSION_ID",
      "type": "user",
      "kind": "drive#permission",
      "role": "commenter"
    }
  ]
}

Обновить разрешения

Чтобы обновить разрешения для файла или папки, вы можете изменить назначенную роль. Дополнительные сведения о поиске источника роли см. в разделе Определение источника роли .

  1. Вызовите метод update() для ресурса permissions , указав в качестве параметра пути permissionId разрешение на изменение, а в качестве параметра пути fileId задано связанное с ним файл, папку или общий диск. Чтобы найти permissionId , используйте метод list() для ресурса permissions с параметром пути fileId .

  2. В запросе укажите новую role .

Вы можете предоставить разрешения для отдельных файлов или папок на общем диске, даже если пользователь или группа уже являются его участниками. Например, у Алекса есть role=commenter как часть его членства на общем диске. Однако ваше приложение может предоставить Alex role=writer для файла на общем диске. В этом случае, поскольку новая роль является более разрешающей, чем роль, предоставленная посредством их членства, новое разрешение становится эффективной ролью для файла или папки.

Показать пример

В следующем примере кода показано, как изменить права доступа к файлу или папке с комментатора на автора. Ответ возвращает экземпляр ресурса permissions .

Запрос

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID
{
  "requests": [
    {
        "role": "writer"
    }
  ]
}

Ответ

{
  "kind": "drive#permission",
  "id": "PERMISSION_ID",
  "type": "user",
  "role": "writer"
}

Определите источник роли

Чтобы изменить роль файла или папки, вы должны знать источник роли. Для общих дисков источником роли может быть членство в общем диске, роль в папке или роль в файле.

Чтобы определить источник роли для общего диска или элементов на этом диске, вызовите метод get() для ресурса permissions с параметрами пути fileId и permissionId , а для параметра fields установлено значение поля permissionDetails .

Чтобы найти permissionId , используйте метод list() ресурса permissions с параметром пути fileId . Чтобы получить поле permissionDetails в запросе list , установите для параметра fields значение permissions/permissionDetails .

В этом поле перечислены все унаследованные и прямые права доступа к файлам для пользователя, группы или домена.

Показать пример

В следующем примере кода показано, как определить источник роли. Ответ возвращает сведения permissionDetails ресурса permissions . Поле inheritedFrom предоставляет идентификатор элемента, от которого наследуется разрешение.

Запрос

GET https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID?fields=permissionDetails&supportsAllDrives=true

Ответ

{
  "permissionDetails": [
    {
      "permissionType": "member",
      "role": "commenter",
      "inheritedFrom": "INHERITED_FROM_ID",
      "inherited": true
    },
    {
      "permissionType": "file",
      "role": "writer",
      "inherited": false
    }
  ]
}

Обновление нескольких разрешений с помощью пакетных запросов

Мы настоятельно рекомендуем использовать пакетные запросы для изменения нескольких разрешений.

Ниже приведен пример пакетного изменения разрешений с помощью клиентской библиотеки.

Ява

диск/фрагменты/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;
    }
  }
}

Питон

диск/фрагменты/drive-v3/file_snippet/share_file.py
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_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_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;
    }

}

.СЕТЬ

диск/фрагменты/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;
        }
    }
}

Удаление разрешения

Чтобы отозвать доступ к файлу или папке, вызовите метод delete() на ресурсе permissions с параметрами fileId и пути permissionId установленными для удаления разрешения.

Для элементов в «Моем диске» можно удалить унаследованное разрешение. Удаление унаследованного разрешения отменяет доступ к элементу и дочерним элементам, если таковые имеются.

Для объектов на общем диске унаследованные разрешения нельзя отозвать. Вместо этого обновите или удалите разрешение для родительского файла или папки.

Метод delete() также используется для удаления разрешений, непосредственно примененных к файлу или папке на общем диске.

Показать пример

В следующем примере кода показано, как отозвать доступ, удалив permissionId . В случае успеха тело ответа пустое. Чтобы подтвердить удаление разрешения, используйте метод list() ресурса permissions с параметром пути fileId .

Запрос

DELETE https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID

Установите дату истечения срока действия, чтобы ограничить доступ к файлам

Когда вы работаете с людьми над конфиденциальным проектом, вы можете через некоторое время ограничить им доступ к определенным файлам на Диске. Для файлов в «Моем диске» вы можете установить дату истечения срока действия, чтобы ограничить или удалить доступ к этому файлу.

Чтобы установить дату истечения срока действия:

  • Используйте метод create() для ресурса permissions и установите поле expirationTime (вместе с другими обязательными полями). Дополнительные сведения см. в разделе Создание разрешения .

  • Используйте метод update() для ресурса permissions и установите поле expirationTime (вместе с другими обязательными полями). Дополнительные сведения см. в разделе Разрешения на обновление .

Поле expirationTime указывает, когда истекает срок действия разрешения, используя дату-время RFC 3339 . Срок действия имеет следующие ограничения:

  • Их можно установить только для разрешений пользователя и группы.
  • Время должно быть в будущем.
  • Это время не может быть больше, чем через год.

Дополнительную информацию о сроке действия см. в следующих статьях:

,

Каждый файл, папка и общий диск Google Диска имеют соответствующие ресурсы permissions . Каждый ресурс идентифицирует разрешение для определенного type ( user , group , domain , anyone ) и role ( owner , organizer , fileOrganizer , writer , commenter , reader ). Например, файл может иметь разрешение, предоставляющее конкретному пользователю ( type=user ) доступ только для чтения ( role=reader ), в то время как другое разрешение предоставляет членам определенной группы ( type=group ) возможность добавлять комментарии к файлу ( role=commenter ).

Полный список ролей и операций, разрешенных каждой из них, см. в разделе Роли и разрешения .

Как работают разрешения

Списки разрешений для папки распространяются вниз. Все дочерние файлы и папки наследуют разрешения от родительского. Всякий раз, когда разрешения или иерархия изменяются, распространение происходит рекурсивно по всем вложенным папкам. Например, если файл существует в папке, а затем эта папка перемещается в другую папку, разрешения для новой папки распространяются на файл. Если новая папка предоставляет пользователю файла новую роль, например «писатель», она переопределяет его старую роль.

И наоборот, если файл наследует role=writer из папки и перемещается в другую папку, предоставляющую роль «читателя», теперь файл наследует role=reader .

Унаследованные разрешения нельзя удалить из файла или папки на общем диске. Вместо этого эти разрешения необходимо настроить для прямого или косвенного родительского объекта, от которого они были унаследованы. Унаследованные разрешения можно удалить для элементов в разделах «Мой диск» или «Доступно мне».

И наоборот, унаследованные разрешения могут быть переопределены для файла или папки в «Моем диске». Таким образом, если файл наследует role=writer из папки «Мой диск», вы можете установить для файла role=reader чтобы снизить уровень его разрешений.

Понимание возможностей файлов

Ресурс permissions в конечном итоге не определяет способность текущего пользователя выполнять действия с файлом или папкой. Вместо этого ресурс files содержит набор логических полей capabilities используемых для указания того, можно ли выполнить действие над файлом или папкой. API Google Диска устанавливает эти поля на основе ресурсов разрешений текущего пользователя, связанных с файлом или папкой.

Например, когда Алекс входит в ваше приложение и пытается поделиться файлом, роль Алекса проверяется на наличие разрешений для файла. Если роль позволяет им делиться файлом, capabilities связанные с файлом, такие как canShare , заполняются относительно роли. Если Алекс хочет поделиться файлом, ваше приложение проверяет capabilities , чтобы убедиться, что для canShare установлено значение true .

Пример получения capabilities файла см. в разделе Получение возможностей файла .

Получить возможности файла

Когда ваше приложение открывает файл, оно должно проверить возможности файла и отобразить пользовательский интерфейс, отражающий разрешения текущего пользователя. Например, если у пользователя нет возможности canComment для файла, возможность комментирования должна быть отключена в пользовательском интерфейсе.

Чтобы проверить возможности, вызовите метод get() ресурса files с параметром пути fileId и параметром fields , установленным в поле capabilities . Дополнительную информацию о возврате полей с помощью параметра fields см. в разделе Возврат определенных полей .

Показать пример

В следующем примере кода показано, как проверить разрешения пользователя. Ответ возвращает список возможностей, которые пользователь имеет в отношении файла. Каждая возможность соответствует детальному действию, которое может предпринять пользователь. Некоторые поля заполняются только для объектов на общих дисках.

Запрос

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=capabilities

Ответ

{
  "capabilities": {
    "canAcceptOwnership": false,
    "canAddChildren": false,
    "canAddMyDriveParent": false,
    "canChangeCopyRequiresWriterPermission": true,
    "canChangeSecurityUpdateEnabled": false,
    "canComment": true,
    "canCopy": true,
    "canDelete": true,
    "canDownload": true,
    "canEdit": true,
    "canListChildren": false,
    "canModifyContent": true,
    "canModifyContentRestriction": true,
    "canModifyLabels": true,
    "canMoveChildrenWithinDrive": false,
    "canMoveItemOutOfDrive": true,
    "canMoveItemWithinDrive": true,
    "canReadLabels": true,
    "canReadRevisions": true,
    "canRemoveChildren": false,
    "canRemoveMyDriveParent": true,
    "canRename": true,
    "canShare": true,
    "canTrash": true,
    "canUntrash": true
  }
}

Сценарии совместного использования ресурсов Диска

Существует пять различных типов сценариев совместного использования:

  1. Чтобы поделиться файлом на «Моем диске», у пользователя должны быть role=writer или role=owner .

  2. Чтобы предоставить общий доступ к папке на «Моем диске», у пользователя должны быть role=writer или role=owner .

  3. Чтобы поделиться файлом на общем диске, у пользователя должна быть role=writer , role=fileOrganizer или role=organizer .

    • Параметр writersCanShare не применяется к объектам на общих дисках. Он рассматривается так, как будто для него всегда установлено значение true .
  4. Чтобы предоставить общий доступ к папке на общем диске, у пользователя должен быть role=organizer .

    • Если для sharingFoldersRequiresOrganizerPermission на общем диске установлено значение false , пользователи с role=fileOrganizer могут совместно использовать папки на этом общем диске.
  5. Чтобы управлять членством в общем диске, у пользователя должен быть role=organizer . Участниками общих дисков могут быть только пользователи и группы.

Создать разрешение

Следующие два поля необходимы при создании разрешения:

  • type : type определяет область разрешений ( user , group , domain или anyone ). Разрешение с type=user применяется к конкретному пользователю, тогда как разрешение с type=domain применяется ко всем в определенном домене.

  • role : Поле role определяет операции, которые может выполнять type . Например, разрешение с type=user и role=reader предоставляет конкретному пользователю доступ только для чтения к файлу или папке. Или разрешение с type=domain и role=commenter позволяет всем в домене добавлять комментарии к файлу. Полный список ролей и операций, разрешенных каждой из них, см. в разделе Роли и разрешения .

Когда вы создаете разрешение, где type=user или type=group , вы также должны указать emailAddress , чтобы привязать конкретного пользователя или группу к разрешению.

Когда вы создаете разрешение, где type=domain , вы также должны указать domain , чтобы привязать определенный домен к разрешению.

Чтобы создать разрешение:

  1. Используйте метод create() с параметром пути fileId для связанного файла или папки.
  2. В теле запроса укажите type и role .
  3. Если type=user или type=group , укажите emailAddress . Если type=domain , укажите domain .

Показать пример

В следующем примере кода показано, как создать разрешение. Ответ возвращает экземпляр ресурса Permission , включая назначенный permissionId .

Запрос

POST https://www.googleapis.com/drive/v3/files/FILE_ID/permissions
{
  "requests": [
    {
        "type": "user",
        "role": "commenter",
        "emailAddress": "alex@altostrat.com"
    }
  ]
}

Ответ

{
    "kind": "drive#permission",
    "id": "PERMISSION_ID",
    "type": "user",
    "role": "commenter"
}

Используйте целевые аудитории

Целевые аудитории — это группы людей, например отделы или команды, которым вы можете порекомендовать пользователям поделиться своими элементами. Вы можете поощрять пользователей делиться элементами с более конкретной или ограниченной аудиторией, а не со всей вашей организацией. Целевые аудитории могут помочь вам повысить безопасность и конфиденциальность ваших данных, а также облегчить пользователям надлежащий обмен ими. Дополнительную информацию см. в разделе О целевых аудиториях .

Чтобы использовать целевые аудитории:

  1. В консоли администратора Google выберите > Каталог > Целевые аудитории .

    Перейти к Целевые аудитории

    Для выполнения этой задачи вам необходимо войти в систему, используя учетную запись с правами суперадминистратора .

  2. В списке «Целевые аудитории» щелкните название целевой аудитории. Чтобы создать целевую аудиторию, см. Создание целевой аудитории.

  3. Скопируйте уникальный идентификатор из URL-адреса целевой аудитории: https://admin.google.com/ac/targetaudiences/ ID .

  4. Создайте разрешение с type=domain и задайте для поля domain ID .audience.googledomains.com .

Чтобы просмотреть, как пользователи взаимодействуют с целевыми аудиториями, см. раздел «Взаимодействие с пользователями при обмене ссылками» .

Список всех разрешений

Используйте метод list() ресурса permissions , чтобы получить все разрешения для файла, папки или общего диска.

Показать пример

В следующем примере кода показано, как получить все разрешения. Ответ возвращает список разрешений.

Запрос

GET https://www.googleapis.com/drive/v3/files/FILE_ID/permissions

Ответ

{
  "kind": "drive#permissionList",
  "permissions": [
    {
      "id": "PERMISSION_ID",
      "type": "user",
      "kind": "drive#permission",
      "role": "commenter"
    }
  ]
}

Обновить разрешения

Чтобы обновить разрешения для файла или папки, вы можете изменить назначенную роль. Дополнительные сведения о поиске источника роли см. в разделе Определение источника роли .

  1. Вызовите метод update() для ресурса permissions с параметром пути permissionId установленным для разрешения на изменение, и параметром пути fileId установленным для связанного файла, папки или общего диска. Чтобы найти permissionId , используйте метод list() ресурса permissions с параметром пути fileId .

  2. В запросе укажите новую role .

Вы можете предоставить разрешения для отдельных файлов или папок на общем диске, даже если пользователь или группа уже являются его участниками. Например, у Алекса есть role=commenter как часть его членства на общем диске. Однако ваше приложение может предоставить Alex role=writer для файла на общем диске. В этом случае, поскольку новая роль является более разрешающей, чем роль, предоставленная посредством их членства, новое разрешение становится эффективной ролью для файла или папки.

Показать пример

В следующем примере кода показано, как изменить права доступа к файлу или папке с комментатора на автора. Ответ возвращает экземпляр ресурса permissions .

Запрос

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID
{
  "requests": [
    {
        "role": "writer"
    }
  ]
}

Ответ

{
  "kind": "drive#permission",
  "id": "PERMISSION_ID",
  "type": "user",
  "role": "writer"
}

Определите источник роли

Чтобы изменить роль файла или папки, вы должны знать источник роли. Для общих дисков источником роли может быть членство в общем диске, роль в папке или роль в файле.

Чтобы определить источник роли для общего диска или элементов на этом диске, вызовите метод get() для ресурса permissions с параметрами пути fileId и permissionId , а для параметра fields установлено значение поля permissionDetails .

Чтобы найти permissionId , используйте метод list() ресурса permissions с параметром пути fileId . Чтобы получить поле permissionDetails в запросе list , установите для параметра fields значение permissions/permissionDetails .

В этом поле перечислены все унаследованные и прямые права доступа к файлам для пользователя, группы или домена.

Показать пример

В следующем примере кода показано, как определить источник роли. Ответ возвращает сведения permissionDetails ресурса permissions . Поле inheritedFrom предоставляет идентификатор элемента, от которого наследуется разрешение.

Запрос

GET https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID?fields=permissionDetails&supportsAllDrives=true

Ответ

{
  "permissionDetails": [
    {
      "permissionType": "member",
      "role": "commenter",
      "inheritedFrom": "INHERITED_FROM_ID",
      "inherited": true
    },
    {
      "permissionType": "file",
      "role": "writer",
      "inherited": false
    }
  ]
}

Обновление нескольких разрешений с помощью пакетных запросов

Мы настоятельно рекомендуем использовать пакетные запросы для изменения нескольких разрешений.

Ниже приведен пример пакетного изменения разрешений с помощью клиентской библиотеки.

Ява

диск/фрагменты/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;
    }
  }
}

Питон

диск/фрагменты/drive-v3/file_snippet/share_file.py
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_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_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;
    }

}

.СЕТЬ

диск/фрагменты/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;
        }
    }
}

Удаление разрешения

Чтобы отозвать доступ к файлу или папке, вызовите метод delete() на ресурсе permissions с параметрами fileId и пути permissionId установленными для удаления разрешения.

Для элементов в «Моем диске» можно удалить унаследованное разрешение. Удаление унаследованного разрешения отменяет доступ к элементу и дочерним элементам, если таковые имеются.

Для объектов на общем диске унаследованные разрешения нельзя отозвать. Вместо этого обновите или удалите разрешение для родительского файла или папки.

Метод delete() также используется для удаления разрешений, непосредственно примененных к файлу или папке на общем диске.

Показать пример

В следующем примере кода показано, как отозвать доступ, удалив permissionId . В случае успеха тело ответа пустое. Чтобы подтвердить удаление разрешения, используйте метод list() ресурса permissions с параметром пути fileId .

Запрос

DELETE https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID

Установите дату истечения срока действия, чтобы ограничить доступ к файлам

Когда вы работаете с людьми над конфиденциальным проектом, вы можете через некоторое время ограничить им доступ к определенным файлам на Диске. Для файлов в «Моем диске» вы можете установить дату истечения срока действия, чтобы ограничить или удалить доступ к этому файлу.

Чтобы установить срок действия:

  • Используйте метод create() для ресурса permissions и установите поле expirationTime (вместе с другими обязательными полями). Дополнительные сведения см. в разделе Создание разрешения .

  • Используйте метод update() для ресурса permissions и установите поле expirationTime (вместе с другими обязательными полями). Дополнительные сведения см. в разделе Разрешения на обновление .

Поле expirationTime указывает, когда истекает срок действия разрешения, используя дату-время RFC 3339 . Срок действия имеет следующие ограничения:

  • Их можно установить только для разрешений пользователя и группы.
  • Время должно быть в будущем.
  • Это время не может быть больше, чем через год в будущем.

Дополнительную информацию о сроке действия см. в следующих статьях: