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

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

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

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

אחרי שהשרת מעבד בקשה תקינה שכוללת את הפרמטר fields, הוא מחזיר קוד סטטוס HTTP 200 OK יחד עם הנתונים המבוקשים. אם יש שגיאה בפרמטר של השדות או שהוא לא תקין מסיבה אחרת, השרת יחזיר קוד הסטטוס 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"
    }
  ]
}