כדי להחזיר בדיוק את השדות הדרושים ולשפר את הביצועים, כדאי להשתמש בפרמטר השאילתה 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" } ] }