טיפים בנושא ביצועים

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

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

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

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

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

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

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

תשובה חלקית

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

כדי לבקש תשובה חלקית, משתמשים בפרמטר 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 שמשתמשות ב-"data" [נתונים] רכיבי wrapper, שבהם התגובה מוצבת בתוך אובייקט 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 חייב להיות מקודד בכתובת ה-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), אפשר להשתמש בפרמטרים האלה כדי לצמצם את התוצאות של כל שאילתה לגודל שאפשר לנהל. אחרת, ייתכן שהביצועים יהיו טובים יותר אם נקבל תגובה חלקית.