דף זה תורגם על ידי Cloud Translation API.

שימוש ב-REST להפעלת ה-API

במסמך הזה מוסבר איך להשתמש ב-Custom Search JSON API.

שליחת בקשה

‏REST, או Representational State Transfer, ב-Custom Search JSON API שונה במקצת מ-APIs רגילים מסוג REST. במקום לספק גישה למשאבים, ממשק ה-API מספק גישה לשירות. כתוצאה מכך, ה-API מספק URI יחיד שמשמש כנקודת הקצה של השירות.

כדי לאחזר תוצאות של חיפוש מסוים, שולחים בקשת HTTP GET למזהה ה-URI שלו. מעבירים את הפרטים של בקשת החיפוש כפרמטרים של שאילתה. הפורמט של ה-URI של Custom Search JSON API הוא:

https://www.googleapis.com/customsearch/v1?[parameters]

צריך להוסיף שלוש שאילתות [parameters] לכל בקשת חיפוש:

מפתח API – משתמשים בפרמטר השאילתה key כדי לזהות את האפליקציה.
- Programmable Search Engine ID – משתמשים ב-cx כדי לציין את Programmable Search Engine שבו רוצים להשתמש כדי לבצע את החיפוש הזה. צריך ליצור את מנוע החיפוש באמצעות לוח הבקרה.הערה: מזהה מנוע החיפוש (cx) יכול להיות בפורמט שונה (למשל, 8ac1ab64606d234f1).
שאילתת חיפוש – משתמשים בפרמטר השאילתה q כדי לציין את ביטוי החיפוש.

כל שאר פרמטרים של שאילתה הם אופציונליים.

דוגמה לבקשה לחיפוש הרצאות במנוע חיפוש Programmable Engine לבדיקה:

GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lectures

פרמטרים של שאילתה

יש שני סוגים של פרמטרים שאפשר להעביר בבקשה:

פרמטרים ספציפיים ל-API – מגדירים מאפיינים של החיפוש, כמו ביטוי החיפוש, מספר התוצאות, השפה וכו'.
פרמטרים רגילים של שאילתות – מגדירים היבטים טכניים של הבקשה, כמו מפתח ה-API.

כל ערכי הפרמטרים צריכים להיות מקודדים בכתובת ה-URL.

פרמטרים של שאילתות ספציפיים ל-API

פרמטרים של בקשות שחלים באופן ספציפי על Custom Search JSON API ומגדירים את בקשת החיפוש מפורטים בחומר העזר.

פרמטרים רגילים של שאילתות

הפרמטרים של שאילתות שחלים על כל הפעולות של Custom Search JSON API מתועדים ברשימת הפרמטרים של המערכת.

נתוני התגובה

אם הבקשה תתבצע בהצלחה, השרת יחזיר את קוד הסטטוס 200 OK של HTTP ואת נתוני התשובה בפורמט JSON. אפשר למצוא את המבנה של נתוני התשובה בחומר העזר.

נתוני התגובה הם אובייקט JSON שכולל שלושה סוגים של מאפיינים:

מטא-נתונים שמתארים את החיפוש המבוקש (ואולי גם בקשות חיפוש קשורות)
מטא-נתונים שמתארים את Programmable Search Engine
תוצאות חיפוש

תיאור מפורט של כל מאפיין זמין בחומר העזר.

מטא-נתונים של בקשת חיפוש

מטא-נתוני החיפוש כוללים:

נכס url, שמכיל מידע על תבנית OpenSearch ששימשה להצגת התוצאות שהתקבלו בבקשה הזו.
המאפיין queries, שהוא מערך של אובייקטים שמתארים את המאפיינים של חיפושים אפשריים. השם של כל אובייקט במערך הוא שם של תפקיד שאילתה ב-OpenSearch או אחד משני התפקידים בהתאמה אישית שהוגדרו על ידי ה-API הזה: previousPage ו-nextPage. אובייקטים אפשריים של תפקידי שאילתה:
- request: מטא-נתונים שמתארים את השאילתה של קבוצת התוצאות הנוכחית.
- התפקיד הזה תמיד מופיע בתגובה.
  - הוא תמיד מערך עם רכיב אחד בלבד.
  - nextPage: מטא-נתונים שמתארים את השאילתה שתשמש בדף התוצאות הבא.
    - התפקיד הזה לא מופיע אם התוצאות הנוכחיות הן הדף האחרון. הערה: ה-API הזה מחזיר עד 100 התוצאות הראשונות בלבד.
    - אם השדה הזה מופיע, הוא תמיד מערך עם רכיב אחד בלבד.
- previousPage: מטא-נתונים שמתארים את השאילתה שתשמש לדף הקודם של התוצאות.
  - לא מופיע אם התוצאות הנוכחיות הן בדף הראשון.
  - אם השדה הזה מופיע, הוא תמיד מערך עם רכיב אחד בלבד.

מטא-נתונים של מנוע חיפוש

בנכס context יש מטא-נתונים שמתארים את מנוע החיפוש שבו בוצעה שאילתת החיפוש. הוא כולל את שם מנוע החיפוש ואת כל אובייקטי המאפיינים שהוא מספק כדי לחדד את החיפוש.

תוצאות חיפוש

מערך items מכיל את תוצאות החיפוש בפועל. תוצאות החיפוש כוללות את כתובת ה-URL, הכותרת וקטעי הטקסט שמתארים את התוצאה. בנוסף, אם רלוונטי, הם יכולים לכלול מידע על נכסי Rich Snippet.

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

REST מ-JavaScript

אפשר להפעיל את Custom Search JSON API באמצעות REST מ-JavaScript, באמצעות פרמטר השאילתה callback ופונקציית קריאה חוזרת (callback). כך תוכלו לכתוב אפליקציות מפותחות שמוצגות בהן נתונים מ-Programmable Search Engine בלי לכתוב קוד בצד השרת.

בדוגמה הבאה נעשה שימוש בגישה הזו כדי להציג את הדף הראשון של תוצאות החיפוש לשאילתה lecture:

<html>
<head>
<title>Custom Search JSON API Example</title>
</head>
<body>
    <div id="content"></div>
    <p id="demo"></p>
    <script>
    function hndlr(response) {
      if (response.items == null) {
        document.getElementById("demo").innerHTML +=`<h3> No Results Found </h3>`;
      } else {
        for (var i = 1; i < response.items.length; i++) {
          var item = response.items[i];
          // Make sure HTML in item.htmlTitle is escaped.
          document.getElementById("content").append(
            document.createElement("br"),
            document.createTextNode(item.htmlTitle)
          );
        }
      }
    }
    </script>
    <script src="https://www.googleapis.com/customsearch/v1?key=YOUR-KEY&cx=017576662512468239146:omuauf_lfve&q=lecture&callback=hndlr">
    </script>
  </body>
</html>