مشاركة الملفات والمجلدات ومحركات الأقراص

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

يحتوي كل ملف ومجلد ومساحة تخزين سحابي مشتركة في Google Drive على موارد أذونات مرتبطة. ويحدد كل مورد الإذن الممنوح لـ type (مستخدم أو مجموعة أو نطاق أو أي شخص) وrole، مثل "معلِّق" أو "قارئ". على سبيل المثال، قد يكون للملف إذن لمنح مستخدم محدّد (type=user) إذن وصول للقراءة فقط (role=reader) في حين يمنح إذن آخر أعضاء مجموعة محددة (type=group) إمكانية إضافة تعليقات إلى ملف (role=commenter).

للحصول على قائمة كاملة بالأدوار والعمليات المسموح بها لكل منها، يُرجى الرجوع إلى الأدوار.

سيناريوهات مشاركة موارد Drive

هناك 5 أنواع مختلفة من سيناريوهات المشاركة:

  1. لمشاركة ملف في "ملفاتي"، يجب أن يكون لدى المستخدم دور "كاتب" أو دور أعلى.

    • في حال ضبط القيمة المنطقية writersCanShare على False للملف، يجب أن يكون للمستخدم دور "المالك".

    • إذا كان لدى المستخدم الذي لديه دور "كاتب" إذن وصول مؤقت محكوم بتاريخ ووقت انتهاء صلاحية، لن يتمكّن من مشاركة الملف.

    لمزيد من المعلومات، راجع إضافة تاريخ انتهاء الصلاحية.

  2. لمشاركة مجلد في "ملفاتي"، يجب أن يكون لدى المستخدم دور "كاتب" أو دور أعلى.

    • وفي حال ضبط writersCanShareالقيمة المنطقية على False للملف، يجب أن يكون للمستخدم دور "المالك" الأكثر تساهلاً.

    • لا يُسمح بالوصول المؤقت (المُحدَّد بتاريخ ووقت انتهاء الصلاحية) إلى مجلدات "ملفاتي" التي تؤدي دور "كاتب".

  3. لمشاركة ملف في مساحة Drive مشتركة، يجب أن يكون لدى المستخدم دور "كاتب" أو أعلى.

    • لا ينطبق إعداد writersCanShare على العناصر في مساحات التخزين السحابي المشتركة. ويتم التعامل معه كما لو تم ضبطه دائمًا على True.

    • لا يُسمح بالوصول المؤقت (الذي يحكمه تاريخ ووقت انتهاء الصلاحية) في مساحات التخزين السحابي المشتركة.

  4. لمشاركة مجلد في مساحة تخزين سحابي مشتركة، يجب أن يكون لدى المستخدم دور "المنظِّم".

  5. لإدارة عضوية مساحة التخزين السحابي المشتركة، يجب أن يكون لدى المستخدم دور "المنظِّم". لا يمكن إلا للمستخدمين والمجموعات أن يكونوا أعضاء في مساحات Drive المشتركة.

نشر الأذونات

يتم نشر قوائم الأذونات لمجلد لأسفل، كما تكتسب جميع الملفات والمجلدات الفرعية الأذونات من المجلد الرئيسي. عندما يتم تغيير الأذونات أو العرض الهرمي، يحدث النشر بشكل متكرر عبر جميع المجلدات المتداخلة. على سبيل المثال، إذا كان هناك ملف في مجلد ثم تم نقله بعده داخل مجلد آخر، ستنتشر الأذونات في المجلد الجديد إلى الملف. إذا منح المجلد الجديد مستخدم الملف دورًا جديدًا، مثل "كاتب"، سيحل محله دوره القديم.

وبالعكس، إذا كان الملف يرث دور "الكاتب" من مجلد، وتم نقله إلى مجلد آخر يقدم دور "القارئ"، فسيكتسب الملف الآن دور "القارئ".

لا يمكن إزالة الأذونات المكتسبة من ملف أو مجلد في مساحة Drive مشتركة. وبدلاً من ذلك، يجب تعديل هذه الأذونات على العنصر الرئيسي المباشر أو غير المباشر الذي تم اكتسابها منه. يمكن إزالة الأذونات المكتسبة من العناصر ضمن "ملفاتي" أو "تمت مشاركتها معي".

وبالعكس، يمكن إلغاء الأذونات المكتسبة من ملف أو مجلد في "ملفاتي". لذلك، إذا اكتسب الملف دور "الكاتب" من مجلد "ملفاتي"، يمكنك ضبط دور "القارئ" في الملف لخفض مستوى الإذن الخاص به.

الإمكانات

لا يحدد مورد الأذونات في النهاية إمكانية المستخدم الحالي في تنفيذ إجراءات على ملف أو مجلد. بدلاً من ذلك، يحتوي مورد الملفات على مجموعة من الحقول المنطقية capabilities المستخدمة للإشارة إلى ما إذا كان يمكن تنفيذ أحد الإجراءات على ملف أو مجلد. تعمل واجهة برمجة تطبيقات Google Drive على تعيين هذه الحقول بناءً على مورد أذونات المستخدم الحالي المقترن بالملف أو المجلد.

على سبيل المثال، عندما يسجل سمير الدخول إلى تطبيقك ويحاول مشاركة ملف، يتم التحقق من دور أليكس من حيث الأذونات في الملف. وإذا كان الدور يسمح لهم بمشاركة ملف، يتم ملء capabilities ذي الصلة بالملف، مثل canShare، نسبيًا بالنسبة إلى الدور. إذا أراد أليكس مشاركة الملف، سيتحقق تطبيقك من capabilities لضمان ضبط canShare على true.

إنشاء إذن

الحقلان التاليان ضروريان عند إنشاء إذن:

  • 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. استخدِم الطريقة permissions.create مع fileId للملف أو المجلد المرتبط.
  2. في نص الطلب، حدِّد type وrole.
  3. إذا كانت قيمة السمة type=user أو type=group، يجب تقديم emailAddress. إذا كان type=domain، قدّم domain.

استرداد جميع الأذونات لأحد الملفات أو المجلدات أو مساحات التخزين السحابي المشتركة

يمكنك استخدام طريقة permissions.list لاسترداد جميع الأذونات لأحد الملفات أو المجلدات أو مساحات التخزين السحابي المشتركة.

التحقق من أذونات المستخدمين

عندما يفتح تطبيقك ملفًا، يجب أن يتحقق من إمكانيات الملف وأن يعرض واجهة المستخدم لتعكس أذونات المستخدم الحالي. على سبيل المثال، إذا لم يكن لدى المستخدم الإمكانية canComment في الملف، يجب إيقاف إمكانية التعليق في واجهة المستخدم.

للتحقق من الإمكانيات، يمكنك استدعاء files.get مع ضبط معلَمتَي fileId وfields على الحقل capabilities.

للحصول على مزيد من المعلومات عن الحقول المكررة باستخدام معلمة fields، يمكنك الرجوع إلى إرجاع حقول معينة لملف.

تحديد مصدر دور ملفات ومجلدات مساحة التخزين السحابي المشتركة

لتغيير الدور في ملف أو مجلد، عليك معرفة مصدر الدور. بالنسبة إلى مساحات التخزين السحابي المشتركة، يمكن أن يستند مصدر الدور إلى العضوية في مساحة التخزين السحابي المشتركة أو الدور في مجلد أو الدور في ملف.

لتحديد مصدر الدور لمساحة تخزين سحابي مشتركة، أو العناصر ضمن مساحة التخزين السحابي هذه، يمكنك استدعاء permissions.get مع ضبط معلَمة fileId وpermissionId وfields على الحقل permissionDetails. للعثور على permissionId، استخدِم permissions.list مع fileId.

يحصي هذا الحقل جميع أذونات الملفات الموروثة والمباشرة للمستخدم أو المجموعة أو النطاق.

تغيير الأذونات

لتغيير الأذونات في ملف أو مجلد، يمكنك تغيير الدور المعيَّن:

  1. اتّصل بـ permissions.update مع منح permissionId الإذن اللازم للتغيير وfileId للملف أو المجلد أو مساحة التخزين السحابي المشتركة المرتبطة. للعثور على permissionId، استخدِم permissions.list مع fileId.

  2. في الطلب، حدِّد السمة الجديدة role.

يمكنك منح أذونات للملفات أو المجلدات الفردية في مساحة Drive مشتركة حتى إذا كان المستخدم أو المجموعة عضوًا فيها من قبل. مثلاً، يمتلك "أليكس" دور commenter كجزء من عضويته في "مساحة تخزين سحابي مشتركة". ومع ذلك، يمكن لتطبيقك منح أليكس الدور writer لملف في مساحة Drive مشتركة. في هذه الحالة، ونظرًا لأن الدور الجديد أكثر تساهلاً من الدور الممنوح من خلال عضويته، يصبح الإذن الجديد الدور الفعّال للملف أو المجلد.

إبطال الوصول إلى ملف أو مجلد

لإبطال الوصول إلى ملف أو مجلد، يمكنك الاتصال delete باستخدام fileId و permissionId لحذف الإذن.

بالنسبة إلى العناصر في "ملفاتي"، من الممكن حذف إذن مكتسب. يؤدي حذف إذن مكتسب إلى إبطال الوصول إلى العنصر والعناصر الفرعية، إن وجدت.

بالنسبة إلى العناصر في مساحة التخزين السحابي المشتركة، لا يمكن إبطال الأذونات المكتسبة. يمكنك تحديث الإذن أو إبطاله في الملف أو المجلد الرئيسي بدلاً من ذلك.

يتم أيضًا استخدام العملية delete لحذف الأذونات المطبَّقة مباشرةً على ملف أو مجلد Drive مشترك.

نقل ملكية الملف إلى حساب Google Workspace آخر في المؤسسة نفسها

يمكن نقل ملكية الملفات الحالية في "ملفاتي" من حساب Google Workspace إلى حساب آخر في المؤسسة نفسها. تمتلك المؤسسة التي تمتلك مساحة Drive مشتركة الملفات داخلها. وبالتالي، لا تتوفّر عمليات نقل الملكية للمجلدات والمجلدات في مساحات التخزين السحابي المشتركة. يمكن لمنظّمي مساحة Drive المشتركة نقل العناصر من مساحة Drive المشتركة هذه إلى "ملفاتي" الخاصة بهم والتي تنقل الملكية إليهم.

لنقل ملكية ملف في "ملفاتي"، نفّذ أحد الإجراءات التالية:

  • إنشاء إذن ملف يمنح مستخدمًا محدّدًا (type=user) إمكانية وصول المالك (role=owner)

  • يمكنك تعديل إذن ملف حالي باستخدام الدور owner ونقل الملكية إلى المستخدم المُحدّد (transferOwnership=true).

نقل ملكية ملف من حساب مستهلك واحد إلى حساب مستهلك آخر

يمكن نقل ملكية الملفات بين حساب مستهلك واحد إلى حساب مستهلك آخر. ومع ذلك، لا ينقل Drive ملكية ملف بين حسابَين للمستهلك حتى يوافق المالك الجديد المحتمل صراحةً على عملية النقل. لنقل ملكية الملف من حساب مستهلك إلى حساب مستهلك آخر:

  1. يبدأ المالك الحالي عملية نقل الملكية من خلال إنشاء أو تحديث إذن ملف مالك جديد محتمل. ويجب أن يتضمن الإذن الإعدادات التالية: role=writer وtype=user وpendingOwner=true. إذا كان المالك الجديد ينشئ إذنًا للمالك المحتمل، يتم إرسال إشعار بالبريد الإلكتروني إلى المالك الجديد المحتمل يشير إلى أنه تتم مطالبته بتولي ملكية الملف.

  2. يقبل المالك الجديد طلب نقل الملكية عن طريق إنشاء إذن ملف له أو تحديثه. ويجب أن يتضمّن الإذن الإعدادات التالية: role=owner وtransferOwnership=true. إذا كان المالك الجديد ينشئ إذنًا جديدًا، فسيتم إرسال إشعار بالبريد الإلكتروني إلى المالك السابق يشير إلى أنه تم نقل الملكية.

عند نقل ملف، يتم خفض مستوى دور المالك السابق إلى writer.

تغيير أذونات متعددة باستخدام الطلبات المجمّعة

ننصحك بشدة باستخدام طلبات مجمّعة لتعديل أذونات متعدّدة.

في ما يلي مثال على إجراء تعديل مجمّع للأذونات باستخدام مكتبة عميلة.

لغة 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;
        }
    }
}