ניהול מטא נתונים של קבצים

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

ציון שמות קבצים וסיומות

אפליקציות צריכות לציין סיומת קובץ במאפיין הכותרת כשמוסיפים קבצים באמצעות Google Drive API. לדוגמה, פעולה להוספת קובץ JPEG צריכה לציין משהו כמו "name": "cat.jpg" במטא-נתונים.

תגובות GET עוקבות יכולות לכלול את הנכס fileExtension לקריאה בלבד, שאוכלס בהרחבה שצוינה במקור בנכס name. כשמשתמש ב-Google Drive מבקש להוריד קובץ, או כשהקובץ מורד דרך לקוח הסנכרון, מערכת Drive יוצרת שם קובץ מלא (עם סיומת) על סמך הכותרת. במקרים שבהם הסיומת חסרה, מערכת Drive מנסה לקבוע את הסיומת על סמך סוג ה-MIME של הקובץ.

שמירת טקסט שניתן לאינדוקס

‫Drive יוצר באופן אוטומטי אינדקס של מסמכים לחיפוש כשהוא מזהה את סוג הקובץ, כולל מסמכי טקסט, קובצי PDF, תמונות עם טקסט וסוגים נפוצים אחרים. אם האפליקציה שומרת סוגים אחרים של קבצים (כמו ציורים, סרטונים וקיצורי דרך), אפשר לשפר את יכולת הגילוי שלהם על ידי הוספת טקסט שניתן לאינדוקס בשדה contentHints.indexableText של הקובץ.

טקסט שאפשר להוסיף לאינדקס מתווסף לאינדקס כ-HTML. אם שומרים את מחרוזת הטקסט שאפשר להוסיף לאינדקס <section attribute="value1">Here's some text</section>, המערכת מוסיפה לאינדקס את הטקסט 'Here's some text', אבל לא את הערך 'value1'. לכן, שמירת XML כטקסט שאפשר להוסיף לאינדקס לא שימושית כמו שמירת HTML.

כשמציינים את מאפיין indexableText, חשוב לזכור גם את הנקודות הבאות:

  • המגבלה על הגודל של contentHints.indexableText היא 128KB.
  • כדאי לכלול את המונחים והמושגים העיקריים שאתם מצפים שהמשתמש יחפש.
  • אל תנסו למיין את הטקסט לפי סדר החשיבות, כי הכלי ליצירת אינדקס עושה את זה ביעילות בשבילכם.
  • האפליקציה צריכה לעדכן את הטקסט שאפשר להוסיף לאינדקס בכל שמירה.
  • חשוב לוודא שהטקסט קשור לתוכן או למטא-נתונים של הקובץ.

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

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

‫Drive יוצר באופן אוטומטי תמונות ממוזערות עבור הרבה סוגים נפוצים של קבצים, כמו Google Docs,‏ Sheets ו-Slides. התמונות הממוזערות עוזרות למשתמשים לזהות טוב יותר את הקבצים ב-Drive.

עבור סוגי קבצים שלא ניתן ליצור עבורם תמונה ממוזערת רגילה ב-Drive, אתם יכולים לספק תמונה ממוזערת שנוצרה על ידי האפליקציה שלכם. במהלך יצירה או עדכון של קובץ, מעלים תמונה ממוזערת על ידי הגדרת השדה contentHints.thumbnail במשאב files.

באופן ספציפי:

  • מגדירים את השדה contentHints.thumbnail.image לכתובת ה-URL ולשם הקובץ של התמונה בקידוד Base64 (ראו סעיף 5 בתקן RFC 4648).
  • מגדירים את השדה contentHints.thumbnail.mimeType לסוג ה-MIME המתאים לתמונה הממוזערת.

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

התמונות הממוזערות צריכות לעמוד בכללים הבאים:

  • אפשר להעלות אותם בפורמטים PNG, ‏GIF או JPG.
  • הרוחב המומלץ הוא 1,600 פיקסלים.
  • הרוחב המינימלי הוא 220 פיקסלים.
  • גודל הקובץ המקסימלי הוא 2MB.
  • האפליקציה צריכה לעדכן אותם בכל שמירה.

מידע נוסף זמין במשאב files.

אחזור תמונות ממוזערות

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

החזרת תמונה ממוזערת ספציפית

דוגמת הקוד הבאה מציגה בקשת שיטה files.get עם כמה שדות כפרמטר שאילתה להחזרת המטא-נתונים thumbnailLink של קובץ ספציפי. מידע נוסף זמין במאמר החזרת שדות ספציפיים עבור קובץ.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,mimeType,thumbnailLink

מחליפים את FILE_ID בfileId של הקובץ שרוצים למצוא.

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

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

בדוגמת הקוד הבאה מוצגת בקשת method‏ files.list עם כמה שדות כפרמטר שאילתה להחזרת המטא-נתונים thumbnailLink של רשימת קבצים. מידע נוסף זמין במאמר חיפוש קבצים ותיקיות.

GET https://www.googleapis.com/drive/v3/files/?fields=files(id,name,mimeType,thumbnailLink)

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

GET https://www.googleapis.com/drive/v3/files/q=mimeType='application/vnd.google-apps.spreadsheet'&fields=files(id,name,mimeType,thumbnailLink)