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

במסמך הזה מוסבר על שיקולים חשובים לגבי מתן שמות לקובצים ולעבודה עם מטא-נתונים, כמו טקסט שאפשר להוסיף לאינדקס ותמונות ממוזערות. למידע נוסף על הוספה ואחזור של קבצים, אפשר לעיין במשאב 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 באמצעות בקשה עם פרטי כניסה.

הצגת רשימה של תמונות ממוזערות

בקטע הקוד הבא מוצגת בקשה של שיטת 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)