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

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

כשמציינים indexableText, חשוב גם לזכור:

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

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

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

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

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

פרטים נוספים:

  • מגדירים את השדה contentHints.thumbnail.image לכתובת ה-URL ולתמונה הבטוחה בקידוד Base64 (ראו RFC 4648 סעיף 5).
  • מגדירים את השדה 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)