שיפור הביצועים

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

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

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

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

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

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

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

תגובה חלקית

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

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

דוגמה

הדוגמה הבאה מציגה את השימוש בפרמטר fields עם ממשק API גנרי (בדיוני) "Demo" 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" 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 חייב להיות מקודד בכתובת ה-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 ושל המחבר's 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), אפשר להשתמש בפרמטרים האלה כדי לצמצם את התוצאות של כל שאילתה לגודל מנוהל. אחרת, ייתכן שהביצועים שיתקבלו לא יהיו אפשריים, אם לא תתקבל תגובה חלקית.