במסמך הזה מפורטות כמה טכניקות שבהן אפשר להשתמש כדי לשפר את ביצועי האפליקציה. במקרים מסוימים, נשתמש בדוגמאות מממשקי API אחרים או מממשקי API כלליים כדי להדגים את הרעיונות שמוצגים. עם זאת, אותם מושגים רלוונטיים גם ל-Tag Manager 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)
תגובה חלקית: בתגובה לבקשה שלמעלה, השרת שולח חזרה תגובה שמכילה רק את המידע מהסוג, וכן מערך פריטים מקוצר שכולל רק מידע על מאפייני הכותרת והאורך של כל פריט.
200 OK
{ "kind": "demo", "items": [{ "title": "First title", "characteristics": { "length": "short" } }, { "title": "Second title", "characteristics": { "length": "long" } }, ... ] }
שימו לב שהתגובה היא אובייקט JSON שכולל רק את השדות שנבחרו ואת אובייקטי ההורה תוחמים שלהם.
בהמשך מופיעים פרטים על הפורמט של הפרמטר fields
, ולאחר מכן פרטים נוספים על מה בדיוק מוחזר בתגובה.
סיכום התחביר של הפרמטרים של השדות
הפורמט של ערך פרמטר הבקשה fields
מבוסס באופן רופף על תחביר XPath. בהמשך מופיע סיכום של התחביר הנתמך, ודוגמאות נוספות מופיעות בקטע הבא.
- משתמשים ברשימה שמופרדת בפסיקים כדי לבחור שדות מרובים.
- כדי לבחור שדה
b
שנמצא בתוך השדהa
, משתמשים בפונקציהa/b
. כדי לבחור שדה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
הוא רשימת שדות שמופרדים בפסיקים, וכל שדה מצוין ביחס לשורש של התגובה. לכן, אם אתם מבצעים פעולת רשימה, התגובה תהיה אוסף והיא כוללת בדרך כלל מערך משאבים. אם אתם מבצעים פעולה שמחזירה משאב יחיד, השדות יצוינו ביחס לאותו משאב. אם השדה שבוחרים הוא (או חלק ממנו) של מערך, השרת מחזיר את החלק שנבחר מכל הרכיבים במערך.
הנה כמה דוגמאות ברמת האוסף:
דוגמאות השפעה 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
, לדוגמה), כדאי להשתמש בפרמטרים האלה כדי לצמצם את התוצאות של כל שאילתה לגודל שניתן לנהל. אחרת, ייתכן שהשיפור בביצועים עם תגובה חלקית לא יתממש.