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