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

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

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

כברירת מחדל, השרת מחזיר קבוצה של שדות ספציפיים למשאב שאליו מתבצעת השאילתה. לדוגמה, השיטה get() במשאב files עשויה להחזיר רק את הערכים id,‏ name ו-mimeType. ה-method get() במשאב permissions מחזירה קבוצה שונה של שדות ברירת מחדל.

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

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

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

הפורמט של ערך הפרמטר של בקשת השדות מבוסס באופן רופף על תחביר 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"
    }
  ]
}