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

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

דחיסה באמצעות 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 משפיע על התשובה.

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