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

במאמר הזה מוסבר איך להשתמש בפרמטר fields ב-Google Drive.

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

מידע על פרמטרים אחרים של המערכת שרלוונטיים ל-Drive API זמין במאמר פרמטרים חלופיים של המערכת.

איך פועל פרמטר השדות

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

אם לא מציינים את הפרמטר fields, השרת מחזיר קבוצת ברירת מחדל של שדות שספציפיים לשיטה. לדוגמה, ה-method‏ list במקור המידע files מחזירה רק את השדות kind,‏ id,‏ name ו-mimeType. השיטה get במשאב permissions מחזירה קבוצה שונה של שדות ברירת מחדל.

בכל השיטות של המשאבים about, ‏ approvals, ‏ comments (לא כולל delete) ו-replies (לא כולל delete), חובה להגדיר את הפרמטר fields. השיטות האלה לא מחזירות קבוצה של שדות שמוגדרת כברירת מחדל.

אחרי ששרת מעבד בקשה תקינה שכוללת את הפרמטר fields, הוא מחזיר קוד סטטוס HTTP 200 OK, יחד עם הנתונים המבוקשים. אם הפרמטר fields מכיל שגיאה או שהוא לא תקין, השרת מחזיר קוד סטטוס HTTP 400 Bad Request, יחד עם הודעת שגיאה שמציינת מה לא בסדר בבחירת השדות. לדוגמה, ‫files.list(fields='files(id,capabilities,canAddChildren)') מחזירה שגיאה של Invalid field selection canAddChildren. פרמטר השדות הנכון בדוגמה הזו הוא files.list(fields='files(id,capabilities/canAddChildren)').

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

כללי פורמט של פרמטרים של שדות

הפורמט של ערך הפרמטר request מבוסס באופן חופשי על תחביר XPath. אלה כללי הפורמט של הפרמטר fields. בדוגמאות לכללים האלה אנחנו משתמשים בשיטה files.get.

  • כדי לבחור כמה שדות, כמו 'name, mimeType', צריך להשתמש ברשימה של שדות שמופרדים באמצעות פסיקים.

  • משתמשים ב-a/b כדי לבחור בשדה b שמוטמע בשדה a, כמו 'capabilities/canDownload'. מידע נוסף זמין במאמר אחזור השדות של משאב מקונן.

  • כדי לבקש קבוצה של שדות משנה ספציפיים במערכים או באובייקטים, אפשר להשתמש בבורר משנה ולהוסיף ביטויים בסוגריים '()'. לדוגמה, 'permissions(id)' מחזיר רק את מזהה ההרשאה של כל רכיב במערך ההרשאות.

  • כדי להחזיר את כל השדות באובייקט, משתמשים בכוכבית (*) כתו כללי בבחירות השדות. לדוגמה, 'permissions/permissionDetails/*' בוחר את כל השדות של פרטי ההרשאות שזמינים לכל הרשאה. שימו לב: שימוש בתו כללי עלול להשפיע לרעה על ביצועי הבקשה.

  • אי אפשר לבחור רכיבים בודדים של מפה כשהמפתחות שלהם מכילים תווים מיוחדים (כמו לוכסנים / או נקודות .). לדוגמה, ניסיון לבחור מפתח ספציפי של פורמט ייצוא ב-exportLinks באמצעות fields=exportLinks/application/pdf יניב שגיאה HTTP 400 Bad Request כי מנתח הנתיבים מפרש את / כתו מפריד של מאפיין מקונן. כדי לאחזר צמדי מפתח/ערך עם תווים מיוחדים במפתחות שלהם, שולחים בקשה למפה כולה (למשל fields=exportLinks) ומסננים את התוצאות בצד הלקוח.

בקשה

בדוגמה הזו, אנחנו מספקים את פרמטר הנתיב של מזהה הקובץ וכמה שדות כפרמטר שאילתה בבקשה. התגובה מחזירה את ערכי השדות של מזהה הקובץ.

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).

כדי לציין שדות מקוננים בתוך מערכים או אובייקטים מקוננים, משתמשים בסוגריים מקוננים. לדוגמה, כדי להציג רשימה של קבצים עם המזהה, השם והפרטים המקוננים של הבעלים (שם לתצוגה וכתובת אימייל), וגם לאחזר את טוקן הדף הבא לצורך עימוד: files.list עם fields=nextPageToken,files(id,name,owners(displayName,emailAddress)).

בקשה

בדוגמה הזו, אנחנו מספקים את פרמטר הנתיב של מזהה הקובץ וכמה שדות, כולל שדות מסוימים של משאב ההרשאות המקונן, כפרמטר שאילתה בבקשה. התגובה מחזירה את ערכי השדות של מזהה הקובץ.

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"
    }
  ]
}

פרמטרים חלופיים של המערכת

הפרמטרים של שאילתות שחלים על כל הפעולות של Google Drive API מתועדים ברשימת הפרמטרים של המערכת.