דף זה תורגם על ידי Cloud Translation API.

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

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