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

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

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

כברירת מחדל, השרת מחזיר קבוצה של שדות ספציפיים למשאב שאליו מתבצעת השאילתה. לדוגמה, השיטה get() במשאב files עשויה להחזיר רק את הערכים id,‏ name ו-mimeType. השיטה 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"
    }
  ]
}