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

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

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

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

הפרמטר 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"
    }
  ]
}