יצירה וניהול של קבצים

במדריך הזה מוסבר איך ליצור ולנהל קבצים ב-Google Drive באמצעות Google Drive API.

יצירת קובץ

כדי ליצור קובץ ב-Drive שלא מכיל מטא-נתונים או תוכן, צריך להשתמש בשיטה create במשאב files ללא פרמטרים.

כשיוצרים את הקובץ, השיטה מחזירה משאב files. לקובץ ניתן kind של drive.file,‏ id,‏ name של Untitled וmimeType של application/octet-stream. המאפיין uploadType מסומן כמאפיין חובה, אבל ערך ברירת המחדל שלו הוא media, כך שבעצם לא צריך לספק אותו.

מידע נוסף על מגבלות קבצים ב-Drive זמין במאמר מגבלות על קבצים ותיקיות.

בדוגמאות הקוד הבאות אפשר לראות איך ליצור קובץ בלי מטא-נתונים או תוכן:

Node.js

/**
 * Create an empty file.
 * @return {string} The created file's ID.
 */
async function createEmptyFile() {
  // Get credentials and build service
  // TODO(developer): Use appropriate auth mechanism for your app

  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  const auth = new GoogleAuth({scopes: 'https://www.googleapis.com/auth/drive'});
  const service = google.drive({version: 'v3', auth});

  try {
    const response = await service.files.create({});
    console.log('File ID: ' + response.data.id);
    return response.data.id;
  } catch (err) {
    // TODO(developer): Handle error
    console.error(err);
  }
}

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files' \
 -H 'Authorization: Bearer ACCESS_TOKEN'

מחליפים את מה שכתוב בשדות הבאים:

  • ‫ACCESS_TOKEN: אסימון OAuth 2.0 של האפליקציה.

שימוש בפרמטר fields

אם רוצים לציין את השדות שיוחזרו בתגובה, אפשר להגדיר את fields פרמטר המערכת בכל שיטה של משאב files. אם משמיטים את הפרמטר fields, השרת מחזיר קבוצת ברירת מחדל של שדות שספציפיים לשיטה. לדוגמה, ה-method‏ list מחזירה רק את השדות kind, id, name, mimeType ו-resourceKey לכל קובץ. כדי להחזיר שדות שונים, אפשר לעיין במאמר בנושא החזרת שדות ספציפיים.

הבעלות על הקובץ

כשיוצרים קובץ באמצעות Drive API, הבעלות תלויה בפרטי האימות שבהם האפליקציה משתמשת, באופן הבא:

  • חשבון משתמש (OAuth 2.0): אם האפליקציה מאומתת בשם משתמש, המשתמש הזה הופך לבעלים של הקובץ. הקובץ יישמר בתיקייה 'האחסון שלי' או בתיקייה שצוינה. הוא תופס חלק ממכסת האחסון שלהם.

  • חשבון שירות: אם האפליקציה מאומתת באמצעות חשבון שירות, חשבון השירות הוא הבעלים של הקובץ. הקובץ יישמר באחסון הייעודי ב-Drive של חשבון השירות. קבצים לא מופיעים בחשבונות אחסון אחרים ב-Drive, אלא אם הם שותפו במפורש. אם חשבון השירות נמחק, כל הקבצים שבבעלותו נמחקים באופן מיידי.

    אם אתם משתמשים בחשבון שירות אבל רוצים שחשבון משתמש ספציפי יהיה הבעלים של קובץ, אתם יכולים להשתמש בהענקת גישה ברמת הדומיין. כך חשבון השירות יכול להתחזות למשתמש וליצור קבצים בשמו. מידע נוסף מופיע במאמר הענקת הרשאה ברמת הדומיין לחשבון השירות.

מידע נוסף על הרשאות לקבצים זמין במאמר שיתוף קבצים, תיקיות וכוננים.

יצירת מזהים לשימוש בקבצים

השיטה generateIds במשאב files מאפשרת ליצור מראש מזהי קבצים ייחודיים שאפשר להשתמש בהם כשיוצרים או מעתיקים קבצים ותיקיות ב-Drive. האפשרות הזו יכולה להיות שימושית כשצריך לשלוט במזהי הקבצים מתוך האפליקציה, במקום לאפשר ל-Drive להקצות אותם באופן אוטומטי.

אפשר להגדיר את מספר המזהים שייווצרו באמצעות פרמטר השאילתה count. אם לא מגדירים את count, ברירת המחדל היא 10. המספר המקסימלי של מזהים שאפשר לבקש הוא 1,000.

אפשר גם לציין את space שבו אפשר להשתמש במזהים ואת type של הפריטים שאפשר להשתמש בהם במזהים.

אחרי שנוצר מזהה, אפשר להעביר אותו לשיטה create או copy דרך השדה id. כך מוודאים שהקובץ שנוצר או שהועתק ישתמש במזהה שנקבע מראש.

אם הקובץ נוצר או מועתק בהצלחה, ניסיונות חוזרים יחזירו תגובת קוד סטטוס של HTTP 409 Conflict ולא ייצרו קבצים כפולים.

שימו לב שאי אפשר להשתמש במזהים שנוצרו מראש כדי ליצור קבצים ב-Google Workspace, למעט application/vnd.google-apps.drive-sdkוapplication/vnd.google-apps.folder סוגי MIME. באופן דומה, אין תמיכה בהעלאות שמתייחסות להמרה לפורמט קובץ של Google Workspace.

בדוגמאות הקוד הבאות אפשר לראות איך ליצור מראש מזהי קבצים ייחודיים:

Node.js

/**
 * Pre-generate unique file IDs.
 */
async function generateFileIds() {
  // Get credentials and build service
  // TODO(developer): Use appropriate auth mechanism for your app

  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  const auth = new GoogleAuth({scopes: 'https://www.googleapis.com/auth/drive'});
  const service = google.drive({version: 'v3', auth});

  try {
    const response = await service.files.generateIds({
      count: 10,
      space: 'drive'
    });
    const ids = response.data.ids;
    console.log('Generated IDs:');
    for (const id of ids) {
      console.log(id);
    }
  } catch (err) {
    // TODO(developer): Handle error
    console.error(err);
  }
}

curl

curl 'https://www.googleapis.com/drive/v3/files/generateIds?count=10&space=drive' \
 -H 'Authorization: Bearer ACCESS_TOKEN'

מחליפים את מה שכתוב בשדות הבאים:

  • ‫ACCESS_TOKEN: אסימון OAuth 2.0 של האפליקציה.

יצירת קבצים עם מטא-נתונים בלבד

קבצים שמכילים מטא-נתונים בלבד לא כוללים תוכן. מטא-נתונים הם נתונים (כמו name,‏ mimeType ו-createdTime) שמתארים את הקובץ. שדות כמו name לא תלויים במשתמש ומופיעים באופן זהה לכל משתמש, בעוד ששדות כמו viewedByMeTime מכילים ערכים ספציפיים למשתמש.

דוגמה לקובץ של מטא-נתונים בלבד היא תיקייה עם סוג ה-MIME application/vnd.google-apps.folder. מידע נוסף זמין במאמר בנושא יצירה של תיקיות והוספת קבצים לתיקיות. דוגמה נוספת היא קיצור דרך שמפנה לקובץ אחר ב-Drive עם סוג ה-MIME‏ application/vnd.google-apps.shortcut. מידע נוסף זמין במאמר בנושא יצירת קיצור דרך לקובץ ב-Drive.

ניהול תמונות ממוזערות

תמונות ממוזערות עוזרות למשתמשים לזהות קבצים ב-Drive. ‫Drive יכול ליצור באופן אוטומטי תמונות ממוזערות לסוגי קבצים נפוצים, או שאתם יכולים לספק תמונה ממוזערת שנוצרה על ידי האפליקציה שלכם. מידע נוסף זמין במאמר בנושא העלאת תמונות ממוזערות.

העתקת קובץ קיים

כדי להעתיק קובץ ולהחיל עדכונים שנדרשים, משתמשים בשיטה copy במשאב files. כדי למצוא את fileId להעתקה, משתמשים בשיטה list.

אפשר להחיל עדכונים באמצעות סמנטיקה של תיקון, כלומר אפשר לבצע שינויים חלקיים במשאב. צריך להגדיר במפורש בבקשה את השדות שרוצים לשנות. כל השדות שלא נכללים בבקשה שומרים על הערכים הקיימים שלהם. מידע נוסף מופיע במאמר עבודה עם משאבים חלקיים.

אפשר להגדיר מראש את מזהה הקובץ של הקובץ שהועתק באמצעות ה-method‏ generateIds. מידע נוסף זמין במאמר בנושא יצירת מזהים לשימוש בקבצים.

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

בדוגמאות הקוד הבאות אפשר לראות איך מעתיקים קובץ ומעדכנים את השם שלו:

Node.js

/**
 * Copy an existing file.
 * @return {string} The copied file's ID.
 */
async function copyFile() {
  // Get credentials and build service
  // TODO(developer): Use appropriate auth mechanism for your app

  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  const auth = new GoogleAuth({scopes: 'https://www.googleapis.com/auth/drive'});
  const service = google.drive({version: 'v3', auth});

  try {
    const response = await service.files.copy({
      fileId: 'FILE_ID',
      requestBody: {
        name: 'FILE_COPY_NAME'
      }
    });
    console.log('Copied file ID: ' + response.data.id);
    return response.data.id;
  } catch (err) {
    // TODO(developer): Handle error
    console.error(err);
  }
}

מחליפים את מה שכתוב בשדות הבאים:

  • ‫FILE_ID: המזהה של הקובץ שרוצים להעתיק.
  • ‫FILE_COPY_NAME: השם של הקובץ החדש.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/copy' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "name": "FILE_COPY_NAME"
 }'

מחליפים את מה שכתוב בשדות הבאים:

  • ‫FILE_ID: המזהה של הקובץ שרוצים להעתיק.
  • ‫ACCESS_TOKEN: אסימון OAuth 2.0 של האפליקציה.
  • ‫FILE_COPY_NAME: השם של הקובץ החדש.

מגבלות ושיקולים

כשמתכוננים להעתקת קבצים, חשוב לשים לב למגבלות ולשיקולים הבאים:

  • הרשאות:

    • האובייקט DownloadRestrictionsMetadata של המשאב files קובע מי יכול להעתיק את הקובץ. מידע נוסף זמין במאמר בנושא איך מונעים ממשתמשים להוריד, להדפיס או להעתיק את הקובץ.
    • המשאב של השדה capabilities.canCopy קובע אם המשתמש יכול להעתיק קובץ. מידע נוסף זמין במאמר הסבר על היכולות של קבצים.
    • המשתמש שיצר את העותק הוא הבעלים של הקובץ שהועתק. הגדרות שיתוף אחרות מקובץ המקור לא משוכפלות. אם העותק נוצר בתיקייה משותפת, הוא מקבל את ההרשאות של התיקייה הזו.
    • יכול להיות שהבעלות על קובץ שהועתק תשתנה, וההעתק לא יקבל בירושה את הרשאות השיתוף של הקובץ המקורי. יכול להיות שתצטרכו לאפס את ההגדרות האלה.

  • ניהול קבצים:

    • אי אפשר להעתיק קבצים מסוימים, כמו קיצורי דרך של צד שלישי.
    • אפשר להעתיק קובץ רק לתיקיית אב אחת. אי אפשר לציין כמה הורים. אם השדה parents לא מצוין, הקובץ מקבל בירושה את כל תיקיות ההורה שאפשר לגלות מקובץ המקור.
    • למרות שתיקייה היא סוג של קובץ, אי אפשר להעתיק תיקייה. במקום זאת, יוצרים תיקיית יעד ומגדירים את השדה parents של הקבצים הקיימים לתיקיית היעד. אחרי זה אפשר למחוק את תיקיית המקור המקורית.
    • אלא אם מציינים שם קובץ חדש, השיטה copy יוצרת קובץ עם אותו שם כמו הקובץ המקורי.
    • שימוש מופרז ב-copy עלול לגרום לחריגה ממגבלות המכסה של Drive API. מידע נוסף זמין במאמר בנושא מגבלות שימוש.

הנה כמה פעולות שאפשר לנסות: