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

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

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

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

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

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

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

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

תגובה חלקית

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

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

דוגמה

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

בקשה פשוטה: בקשת 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. כדי לבחור שדה c שנמצא בתוך השדה b, צריך להשתמש בפונקציה a/b/c.
  

  חריג: בתגובות 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 על התשובה.

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

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

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

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

דוגמאות	השפעה
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, הוא שולח חזרה קוד סטטוס HTTP 200 OK עם הנתונים המבוקשים. אם יש שגיאה בפרמטר של השאילתה fields או שהוא לא תקין מסיבה אחרת, השרת מחזיר קוד סטטוס HTTP 400 Bad Request, בצירוף הודעת שגיאה שמסבירה למשתמש מה הייתה הבעיה בבחירת השדות (לדוגמה, "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, למשל), כדאי להשתמש בפרמטרים האלה כדי לצמצם את התוצאות של כל שאילתה לגודל שניתן לנהל. אחרת, ייתכן ששיפורי הביצועים האפשריים עם תגובה חלקית לא יתקיימו.