החזרת שדות ספציפיים

במאמר הזה מוסבר איך להשתמש בפרמטר fields ב-Google Drive.

כדי לקבל את השדות המדויקים שאתם צריכים ולשפר את הביצועים, צריך להשתמש בפרמטר המערכת fields בהפעלת ה-method.

מידע על פרמטרים אחרים של המערכת שרלוונטיים ל-Drive API זמין במאמר פרמטרים חלופיים של המערכת.

איך פועל פרמטר השדות

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

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

בכל השיטות של המשאבים about, ‏ comments (לא כולל delete) ו-replies (לא כולל delete), חובה להגדיר את הפרמטר fields. השיטות האלה לא מחזירות קבוצת שדות שמוגדרת כברירת מחדל.

אחרי ששרת מעבד בקשה תקינה שכוללת את הפרמטר fields, הוא מחזיר קוד סטטוס HTTP 200 OK, יחד עם הנתונים המבוקשים. אם יש שגיאה בפרמטר fields או שהוא לא תקין מסיבה אחרת, השרת מחזיר קוד סטטוס HTTP 400 Bad Request, יחד עם הודעת שגיאה שמציינת מה לא בסדר בבחירת השדות. לדוגמה, ‫files.list(fields='files(id,capabilities,canAddChildren)') מחזירה את השגיאה Invalid field selection canAddChildren. הפרמטר הנכון של השדות בדוגמה הזו הוא files.list(fields='files(id,capabilities/canAddChildren)').

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

כללי פורמט של פרמטרים של שדות

הפורמט של ערך הפרמטר request מבוסס באופן חופשי על תחביר XPath. אלה כללי הפורמט של הפרמטר fields. בדוגמאות של כל הכללים האלה אנחנו משתמשים בשיטה files.get.

• כדי לבחור כמה שדות, כמו 'name, mimeType', צריך להשתמש ברשימה של שדות שמופרדים באמצעות פסיקים.

• משתמשים ב-a/b כדי לבחור בשדה b שמוטמע בשדה a, כמו 'capabilities/canDownload'. מידע נוסף זמין במאמר אחזור השדות של משאב מקונן.

• כדי לבקש קבוצה של שדות משנה ספציפיים של מערכים או אובייקטים, משתמשים בבורר משנה ומציבים ביטויים בסוגריים '()'. לדוגמה, 'permissions(id)' מחזיר רק את מזהה ההרשאה של כל רכיב במערך ההרשאות.

• כדי להחזיר את כל השדות באובייקט, משתמשים בכוכבית (*) כתו כללי לחיפוש בבחירת השדות. לדוגמה, 'permissions/permissionDetails/*' בוחר את כל שדות הפרטים הזמינים של ההרשאות לכל הרשאה. שימו לב: שימוש בתו כללי עלול להשפיע לרעה על הביצועים של הבקשה.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared

{
  "name": "File1",
  "starred": false,
  "shared": true
  }
}

אחזור השדות של משאב מוטמע

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

לדוגמה, כדי לאחזר את השדה role (משאב מקונן) של המשאב permissions, אפשר להשתמש באחת מהאפשרויות הבאות:

• permissions.get עם fields=role.
• permissions.get עם fields=* כדי להציג את כל השדות permissions.
• ‫files.get עם fields=permissions(role) או fields=permissions/role.
• files.get עם fields=permissions כדי להציג את כל השדות permissions.
• changes.list עם fields=changes(file(permissions(role))).

כדי לאחזר כמה שדות, משתמשים ברשימה מופרדת בפסיקים. לדוגמה, files.list עם fields=files(id,name,createdTime,modifiedTime,size).

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared,permissions(kind,type,role)

{
  "name": "File1",
  "starred": false,
  "shared": true,
  "permissions": [
    {
      "kind": "drive#permission",
      "type": "user",
      "role": "owner"
    }
  ]
}

פרמטרים חלופיים של המערכת

הפרמטרים של שאילתות שחלים על כל הפעולות של Google Drive API מתועדים ברשימת הפרמטרים של המערכת.

נושאים קשורים

• פתרון שגיאות
• פתרון בעיות באימות ובהרשאות
• שיפור הביצועים