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

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

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

ריכזנו כאן כמה דוגמאות ברמת האוסף:

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