خدمة Drive المتقدّمة

لإدارة الملفات والمجلدات، بما في ذلك الخصائص المخصّصة والمراجعات

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

هذه خدمة متقدّمة يجب تفعيلها قبل استخدامها.

مراجع

للحصول على معلومات تفصيلية عن هذه الخدمة، يُرجى الاطّلاع على المستندات المرجعية الخاصة بواجهة Drive API. مثل جميع الخدمات المتقدّمة في Apps Script، تستخدم خدمة Drive المتقدّمة العناصر والطرق والمعلَمات نفسها التي تستخدمها واجهة برمجة التطبيقات العامة. لمزيد من المعلومات، اطّلِع على كيفية تحديد التواقيع. بالإضافة إلى ذلك، فإنّ الطرق التي تحمل الاسم delete في Drive API تحمل الاسم remove في الخدمة المتقدّمة (مثل Drive.Permissions.remove())، لأنّ delete هي كلمة محجوزة في JavaScript.

للإبلاغ عن المشاكل والعثور على دعم آخر، يُرجى الاطّلاع على دليل دعم Drive API.

نموذج التعليمات البرمجية

تستخدم عيّنات الرموز البرمجية في هذا القسم الإصدار 3 من واجهة برمجة التطبيقات.

تحميل ملفات

يوضّح نموذج الرمز البرمجي التالي كيفية حفظ ملف في حساب المستخدم على Drive.

advanced/drive.gs
/**
 * Uploads a new file to the user's Drive.
 */
function uploadFile() {
  try {
    // Makes a request to fetch a URL.
    const image = UrlFetchApp.fetch("http://goo.gl/nd7zjB").getBlob();
    let file = {
      name: "google_logo.png",
      mimeType: "image/png",
    };
    // Create a file in the user's Drive.
    file = Drive.Files.create(file, image, { fields: "id,size" });
    console.log("ID: %s, File size (bytes): %s", file.id, file.size);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed to upload file with error %s", err.message);
  }
}

إنشاء مجلد

يوضّح نموذج الرمز البرمجي التالي كيفية إنشاء مجلد في Drive.

/**
 * Creates a new folder.
 */
function createFolder() {
  var folderMetadata = {
    'name': 'New Folder',
    'mimeType': 'application/vnd.google-apps.folder'
  };
  var folder = Drive.Files.create(folderMetadata);
  Logger.log('Folder ID: ' + folder.id);
}

البحث عن ملفات

يوضّح نموذج الرمز التالي كيفية البحث عن الملفات باستخدام سلسلة طلب بحث.

/**
 * Searches for files with a specific name.
 */
function searchFiles() {
  var query = 'name contains "Project Plan" and trashed = false';
  var files = Drive.Files.list({
    'q': query,
    'fields': 'files(id, name, mimeType)'
  });
  if (files.files && files.files.length > 0) {
    for (var i = 0; i < files.files.length; i++) {
      var file = files.files[i];
      Logger.log('%s (ID: %s)', file.name, file.id);
    }
  } else {
    Logger.log('No files found.');
  }
}

سرد المجلدات

يوضّح نموذج الرمز البرمجي التالي كيفية إدراج المجلدات ذات المستوى الأعلى في Drive الخاص بالمستخدم. يُرجى العِلم أنّه يتم استخدام رموز مميزة للصفحات للوصول إلى القائمة الكاملة بالنتائج.

advanced/drive.gs
/**
 * Lists the top-level folders in the user's Drive.
 */
function listRootFolders() {
  const query =
    '"root" in parents and trashed = false and ' +
    'mimeType = "application/vnd.google-apps.folder"';
  let folders;
  let pageToken = null;
  do {
    try {
      folders = Drive.Files.list({
        q: query,
        pageSize: 100,
        pageToken: pageToken,
      });
      if (!folders.files || folders.files.length === 0) {
        console.log("All folders found.");
        return;
      }
      for (let i = 0; i < folders.files.length; i++) {
        const folder = folders.files[i];
        console.log("%s (ID: %s)", folder.name, folder.id);
      }
      pageToken = folders.nextPageToken;
    } catch (err) {
      // TODO (developer) - Handle exception
      console.log("Failed with error %s", err.message);
    }
  } while (pageToken);
}

مراجعات القائمة

يوضّح نموذج الرمز البرمجي التالي كيفية إدراج المراجعات لملف معيّن. يُرجى العِلم أنّ بعض الملفات يمكن أن تتضمّن عدة مراجعات، وعليك استخدام رموز الصفحات للوصول إلى القائمة الكاملة للنتائج.

advanced/drive.gs
/**
 * Lists the revisions of a given file.
 * @param {string} fileId The ID of the file to list revisions for.
 */
function listRevisions(fileId) {
  let revisions;
  let pageToken = null;
  do {
    try {
      revisions = Drive.Revisions.list(fileId, {
        fields: "revisions(modifiedTime,size),nextPageToken",
      });
      if (!revisions.revisions || revisions.revisions.length === 0) {
        console.log("All revisions found.");
        return;
      }
      for (let i = 0; i < revisions.revisions.length; i++) {
        const revision = revisions.revisions[i];
        const date = new Date(revision.modifiedTime);
        console.log(
          "Date: %s, File size (bytes): %s",
          date.toLocaleString(),
          revision.size,
        );
      }
      pageToken = revisions.nextPageToken;
    } catch (err) {
      // TODO (developer) - Handle exception
      console.log("Failed with error %s", err.message);
    }
  } while (pageToken);
}

إضافة خصائص الملف

يستخدم نموذج الرمز البرمجي التالي الحقل appProperties لإضافة سمة مخصّصة إلى ملف. لا تظهر السمة المخصّصة إلا للنص البرمجي. لإضافة خاصية مخصّصة إلى الملف يمكن للتطبيقات الأخرى الاطّلاع عليها أيضًا، استخدِم الحقل properties بدلاً من ذلك. لمزيد من المعلومات، يُرجى الاطّلاع على إضافة خصائص ملفات مخصّصة.

advanced/drive.gs
/**
 * Adds a custom app property to a file. Unlike Apps Script's DocumentProperties,
 * Drive's custom file properties can be accessed outside of Apps Script and
 * by other applications; however, appProperties are only visible to the script.
 * @param {string} fileId The ID of the file to add the app property to.
 */
function addAppProperty(fileId) {
  try {
    let file = {
      appProperties: {
        department: "Sales",
      },
    };
    // Updates a file to add an app property.
    file = Drive.Files.update(file, fileId, null, {
      fields: "id,appProperties",
    });
    console.log(
      "ID: %s, appProperties: %s",
      file.id,
      JSON.stringify(file.appProperties, null, 2),
    );
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed with error %s", err.message);
  }
}

إضافة مستخدم إلى ملف

يوضّح نموذج الرمز البرمجي التالي كيفية إضافة مستخدم كمحرّر لملف وإيقاف الإشعار عبر البريد الإلكتروني.

/**
 * Adds a user to a file as an editor without sending an email notification.
 */
function addEditor() {
  var fileId = '1234567890abcdefghijklmnopqrstuvwxyz';
  var userEmail = 'bob@example.com';
  var request = {
    'role': 'writer',
    'type': 'user',
    'emailAddress': userEmail
  };
  Drive.Permissions.create(request, fileId, {
    'sendNotificationEmail': false
  });
}