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

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

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

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

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

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

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

תשובה חלקית

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

כדי לבקש תגובה חלקית, משתמשים בפרמטר הבקשה 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

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

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

  יוצא מן הכלל: בתגובות ל-API שמשתמשות במעטפות '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 הוא רשימה של שדות שמופרדים בפסיקים, וכל שדה מצוין ביחס לשורש של התגובה. לכן, אם מבצעים פעולת 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, הוא מחזיר קוד סטטוס 200 OK של HTTP, יחד עם הנתונים המבוקשים. אם יש שגיאה בפרמטר השאילתה 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), כדאי להשתמש בפרמטרים האלה כדי לצמצם את התוצאות של כל שאילתה לגודל שקל לנהל. אחרת, יכול להיות שלא תהיה עלייה בביצועים כמו במקרה של תגובה חלקית.