שיפור הביצועים

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

דחיסה באמצעות gzip

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

כדי לקבל תשובה בקידוד gzip, צריך לבצע שתי פעולות: להגדיר כותרת Accept-Encoding ולשנות את סוכן המשתמש כך שיכיל את המחרוזת gzip. דוגמה לכותרות HTTP בפורמט תקין להפעלת דחיסת gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)

עבודה עם משאבים חלקיים

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

מילוי חלקי

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

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

דוגמה

בדוגמה הבאה מוצג השימוש בפרמטר fields עם API גנרי (פיקטיבי) מסוג "הדגמה".

בקשה פשוטה: בקשת ה-HTTP GET הזו משמיטה את הפרמטר fields ומחזירה את המשאב המלא.

https://www.googleapis.com/demo/v1

תגובת המשאב המלאה: נתוני המשאב המלאים כוללים את השדות הבאים, יחד עם שדות רבים אחרים שהושמטו כדי לקצר.

{
  "kind": "demo",
  ...
  "items": [
  {
    "title": "First title",
    "comment": "First comment.",
    "characteristics": {
      "length": "short",
      "accuracy": "high",
      "followers": ["Jo", "Will"],
    },
    "status": "active",
    ...
  },
  {
    "title": "Second title",
    "comment": "Second comment.",
    "characteristics": {
      "length": "long",
      "accuracy": "medium"
      "followers": [ ],
    },
    "status": "pending",
    ...
  },
  ...
  ]
}

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

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

תגובה חלקית: בתגובה לבקשה שלמעלה, השרת שולח בחזרה תגובה שמכילה רק את פרטי הסוג, יחד עם מערך פריטים מצומצם שכולל רק את פרטי הכותרת והאורך של ה-HTML בכל פריט.

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

שימו לב שהתגובה היא אובייקט JSON שכולל רק את השדות שנבחרו ואת אובייקטי ההורה שמכילים אותם.

בהמשך מוסבר איך להגדיר את הפורמט של הפרמטר fields, ומה בדיוק מוחזר בתגובה.

סיכום התחביר של פרמטר השדות

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

• כדי לבחור כמה שדות, משתמשים ברשימה מופרדת בפסיקים.
• משתמשים ב-a/b כדי לבחור שדה b שמוטמע בתוך שדה a; משתמשים ב-a/b/c כדי לבחור שדה c שמוטמע בתוך b.
  

  חריג: בתגובות מה-API שמשתמשות ב-wrapper של "data", כשהתגובה מוטמעת בתוך אובייקט data שנראה כמו data: { ... }, אל תכללו את "data" במפרט של fields. הכללת אובייקט הנתונים עם מפרט שדות כמו data/a/b גורמת לשגיאה. במקום זאת, פשוט משתמשים במפרט fields כמו a/b.

• כדי לבקש קבוצה של שדות משנה ספציפיים של מערכים או אובייקטים, משתמשים בבורר משנה על ידי הצבת ביטויים בסוגריים "( )".

  לדוגמה: fields=items(id,author/email) מחזיר רק את מזהה הפריט ואת כתובת האימייל של המחבר לכל רכיב במערך הפריטים. אפשר גם לציין שדה משנה יחיד, כאשר fields=items(id) שווה ערך ל-fields=items/id.

• אם צריך, אפשר להשתמש בתווים כלליים לחיפוש בבחירות של השדות.

  לדוגמה: fields=items/pagemap/* בוחר את כל האובייקטים במפת דפים.

דוגמאות נוספות לשימוש בפרמטר fields

הדוגמאות הבאות כוללות תיאורים של האופן שבו ערך הפרמטר fields משפיע על התגובה.

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

מזהים את השדות שרוצים להחזיר או מבצעים בחירות של שדות.

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

הנה כמה דוגמאות ברמת האוסף:

דוגמאות	השפעה
items	היא מחזירה את כל הרכיבים במערך הפריטים, כולל כל השדות בכל רכיב, אבל לא שדות אחרים.
etag,items	הפונקציה מחזירה גם את השדה etag וגם את כל הרכיבים במערך הפריטים.
items/title	הפונקציה מחזירה רק את השדה title לכל הרכיבים במערך הפריטים. בכל פעם שמוחזר שדה בתצוגת עץ, התגובה כוללת את אובייקטי ההורה שמכילים אותו. שדות ההורה לא כוללים שדות צאצא אחרים, אלא אם גם הם נבחרו באופן מפורש.
context/facets/label	הפונקציה מחזירה רק את השדה label לכל האיברים במערך facets, שבעצמו מוטמע באובייקט context.
items/pagemap/*/title	לכל רכיב במערך הפריטים, הפונקציה מחזירה רק את השדה title (אם הוא קיים) של כל האובייקטים שהם צאצאים של pagemap.

הנה כמה דוגמאות ברמת המשאב:

דוגמאות	השפעה
title	הפונקציה מחזירה את השדה title של המשאב המבוקש.
author/uri	הפונקציה מחזירה את שדה המשנה uri של האובייקט author במשאב המבוקש.
links/*/href	הפונקציה מחזירה את השדה href של כל האובייקטים שהם צאצאים של links.

לבקש רק חלקים משדות ספציפיים באמצעות בחירות משנה.

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

דוגמה	השפעה
items(title,author/uri)	הפונקציה מחזירה רק את הערכים של title ושל uri של המחבר לכל רכיב במערך הפריטים.

טיפול בתשובות חלקיות

אחרי שהשרת מעבד בקשה תקינה שכוללת את הפרמטר fields של השאילתה, הוא שולח בחזרה קוד סטטוס 200 OK של HTTP, יחד עם הנתונים המבוקשים. אם הפרמטר של השאילתה fields מכיל שגיאה או לא תקין, השרת מחזיר קוד סטטוס 400 Bad Request של HTTP, יחד עם הודעת שגיאה שמסבירה למשתמש מה לא תקין בבחירת השדות שלו (לדוגמה, "Invalid field selection a/b").

זוהי הדוגמה לתשובה חלקית שמוצגת בקטע המבוא שלמעלה. הבקשה משתמשת בפרמטר fields כדי לציין אילו שדות להחזיר.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

התגובה החלקית נראית כך:

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

הערה: בממשקי API שתומכים בפרמטרים של שאילתות לעימוד נתונים (לדוגמה, maxResults ו-nextPageToken), צריך להשתמש בפרמטרים האלה כדי לצמצם את התוצאות של כל שאילתה לגודל שניתן לניהול. אחרת, יכול להיות שלא תיהנו מהשיפורים בביצועים שאפשר להשיג באמצעות תגובה חלקית.