החזרת שדות ספציפיים לקובץ

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

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