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

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

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

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