במסמך הזה מפורטים שיקולים חשובים לגבי מתן שמות לקבצים ועבודה עם מטא-נתונים כמו טקסט שניתן לאינדוקס ותמונות ממוזערות. כדי להוסיף ולאחזר קבצים, אפשר לעיין במשאב files.
סקירה כללית של מטא-נתונים
ב-Google Drive API, המשאב files מייצג את המטא-נתונים. בניגוד לממשקי API שבהם המטא-נתונים הם אובייקט משנה, ב-Drive API המשאב files כולו נחשב למטא-נתונים. אפשר לגשת למטא-נתונים ישירות באמצעות השיטות get או list במשאב files.
כברירת מחדל, השיטות get ו-list מחזירות רק קבוצה חלקית של שדות. כדי לאחזר נתונים ספציפיים, צריך להגדיר את fields פרמטר המערכת בבקשה. אם לא מציינים את הפרמטר הזה, השרת מחזיר קבוצת משנה של שדות שרלוונטיים לשיטה. לדוגמה, ה-method list מחזירה רק את השדות kind, id, name, mimeType ו-resourceKey לכל קובץ. כדי להחזיר שדות שונים, אפשר לעיין במאמר החזרת שדות ספציפיים.
בנוסף, מי יכול לראות את המטא-נתונים תלוי בתפקיד של המשתמש בקובץ. המשאב
permissions לא קובע אילו פעולות מותרות למשתמש בקובץ או בתיקייה. במקום זאת, המשאב files מכיל אוסף של שדות בוליאניים capabilities. Google Drive API מחלץ את הערכים האלה capabilities מהמשאב permissions שמשויך לקובץ או לתיקייה. מידע נוסף זמין במאמר בנושא הסבר על היכולות של קבצים.
Drive API מציע שני היקפי מטא-נתונים מוגבלים: drive.metadata
ו-drive.metadata.readonly. ההרשאה drive.metadata מאפשרת לכם לראות ולנהל את המטא-נתונים של הקובץ, ואילו ההרשאה drive.metadata.readonly היא לקריאה בלבד. שניהם
אוסרים באופן מוחלט גישה לתוכן הקובץ. מידע נוסף זמין במאמר בחירת היקפי הרשאות של Google Drive API.
לסיום, חשוב תמיד לאמת את הלוגיקה שלכם לגבי הרשאות והיקפים. לדוגמה, יכול להיות שמשתמש הוא הבעלים של קובץ עם הרשאות מלאות, אבל Drive API יחסום ניסיונות לשנות או להוריד את הקובץ אם לאפליקציה שלכם יש רק היקף drive.metadata.readonly.
ציון שמות וסיומות של קבצים
כשמכניסים קבצים באמצעות Google Drive API, צריך לציין סיומת קובץ במאפיין name) באפליקציות. לדוגמה, בפעולה להוספת קובץ 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.
החזרת תמונה ממוזערת ספציפית
בדוגמת הקוד הבאה מוצגת בקשת שיטה get עם כמה שדות כפרמטר שאילתה, כדי להחזיר את המטא-נתונים של קובץ ספציפי thumbnailLink. מידע נוסף זמין במאמר בנושא החזרת שדות ספציפיים של קובץ.
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,mimeType,thumbnailLink
מחליפים את FILE_ID בfileId של הקובץ שרוצים למצוא.
אם התמונה הממוזערת זמינה, הבקשה מחזירה כתובת URL לזמן קצר לתמונה הממוזערת של הקובץ.
בדרך כלל הקישור תקף למשך כמה שעות. השדה מאוכלס רק אם לאפליקציה ששולחת את הבקשה יש גישה לתוכן של הקובץ. אם הקובץ לא שותף באופן ציבורי, צריך לאחזר את כתובת ה-URL שמוחזרת ב-thumbnailLink באמצעות בקשה עם פרטי כניסה.
החזרת רשימה של תמונות ממוזערות
בדוגמת הקוד הבאה מוצגת בקשת שיטה 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)