שירות Drive מתקדם

לנהל קבצים ותיקיות, כולל מאפיינים מותאמים אישית וגרסאות.

שירות Drive המתקדם מאפשר לכם להשתמש ב-Google Drive API ב-Google Apps Script. בדומה לשירות Drive המובנה ב-Apps Script, ה-API הזה מאפשר לסקריפטים ליצור, למצוא ולשנות קבצים ותיקיות ב-Google Drive. ברוב המקרים, קל יותר להשתמש בשירות המובנה, אבל השירות המתקדם הזה מספק כמה תכונות נוספות, כולל גישה למאפיינים מותאמים אישית של קבצים וכן לגרסאות של קבצים ותיקיות.

זהו שירות מתקדם שצריך להפעיל לפני השימוש.

חומרי עזר

מידע מפורט על השירות הזה מופיע במסמכי העזרה של Drive API. בדומה לכל השירותים המתקדמים ב-Apps Script, שירות Drive המתקדם משתמש באותם אובייקטים, שיטות ופרמטרים כמו ה-API הציבורי. מידע נוסף זמין במאמר איך נקבעות חתימות של שיטות. בנוסף, שמות של methods שנקראות delete ב-Drive API נקראות remove בשירות המתקדם (למשל Drive.Permissions.remove()), כי delete היא מילה שמורה ב-JavaScript.

כדי לדווח על בעיות ולמצוא תמיכה נוספת, אפשר לעיין במדריך לתמיכה ב-Drive API.

קוד לדוגמה

בדוגמאות הקוד שבקטע הזה נעשה שימוש בגרסה 3 של ה-API.

העלאת קבצים

בדוגמת הקוד הבאה אפשר לראות איך לשמור קובץ ב-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
  });
}