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

תשובה חלקית

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

כדי לבקש תשובה חלקית, צריך להשתמש בפרמטר הבקשה 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)

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