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

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

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

מידע על פרמטרים אחרים של המערכת שרלוונטיים ל-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 מתועדים ברשימת הפרמטרים של המערכת.