טיפים לשימוש ב-API

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