במסמך הזה מפורטות כמה טכניקות שאפשר להשתמש בהן כדי לשפר את הביצועים של האפליקציה. במקרים מסוימים, נשתמש בדוגמאות מממשקי API אחרים או מממשקי API כלליים אחרים כדי להדגים את הרעיונות שמוצגים. עם זאת, אותם המושגים רלוונטיים גם לממשקי ה-API של Google Photos.
דחיסה באמצעות 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 שמשתמשות ב-wrappers של 'נתונים', שבהן התגובה נמצאת בתוך אובייקט
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
הוא רשימה של שדות שמופרדים בפסיקים, וכל שדה מצוין ביחס לשורש התגובה. לכן, אם אתם מבצעים פעולת רשימה, התגובה היא אוסף, ובדרך כלל כוללת מערך של משאבים. אם מבצעים פעולה שמחזירה משאב יחיד, השדות מצוינים ביחס למשאב הזה. אם השדה שבוחרים הוא מערך (או חלק ממנו), השרת מחזיר את החלק שנבחר מכל הרכיבים במערך.
ריכזנו כאן כמה דוגמאות ברמת האוסף:
דוגמאות השפעה items
הפונקציה מחזירה את כל הרכיבים במערך הפריטים, כולל כל השדות בכל רכיב, אבל לא שדות אחרים. etag,items
הפונקציה מחזירה גם את השדה etag
וגם את כל הרכיבים במערך items.items/title
הפונקציה מחזירה רק את השדה title
לכל הרכיבים במערך הפריטים.
בכל פעם שמוחזר שדה בתצוגת עץ, התגובה כוללת את אובייקטי ההורה שמקפים אותו. שדות ההורה לא כוללים שדות צאצא אחרים, אלא אם הם גם נבחרו באופן מפורש.context/facets/label
הפונקציה מחזירה רק את השדה label
לכל המשתתפים במערךfacets
, שהוא עצמו מוטמע באובייקטcontext
.items/pagemap/*/title
לכל רכיב במערך items, הפונקציה מחזירה רק את השדה title
(אם הוא קיים) של כל האובייקטים שהם צאצאים שלpagemap
.
הנה כמה דוגמאות ברמת המשאב:
דוגמאות השפעה title
הפונקציה מחזירה את השדה title
של המשאב המבוקש.author/uri
הפונקציה מחזירה את שדה המשנה uri
של האובייקטauthor
במשאב המבוקש.links/*/href
הפונקציה מחזירה את השדה href
של כל האובייקטים שהם צאצאים שלlinks
. - לבקש רק חלקים של שדות ספציפיים באמצעות בחירות משנה.
- כברירת מחדל, אם הבקשה מציינת שדות מסוימים, השרת מחזיר את האובייקטים או את רכיבי המערך בשלמותם. אפשר לציין תשובה שכוללת רק שדות משנה מסוימים. כדי לעשות זאת, משתמשים בתחביר הבחירה המשנית '
( )
', כמו בדוגמה הבאה.דוגמה השפעה items(title,author/uri)
הפונקציה מחזירה רק את הערכים של title
ושלuri
של המחבר לכל אלמנט במערך הפריטים.
טיפול בתשובות חלקיות
אחרי שהשרת מעבד בקשה תקינה שכוללת את פרמטר השאילתה fields
, הוא שולח בחזרה קוד סטטוס HTTP 200 OK
יחד עם הנתונים המבוקשים. אם יש שגיאה בפרמטר השאילתה 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
), צריך להשתמש בפרמטרים האלה כדי לצמצם את התוצאות של כל שאילתה לגודל שניתן לניהול. אחרת, יכול להיות שלא תראו את השיפורים בביצועים שאפשר להשיג באמצעות תגובה חלקית.