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

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

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

שליחת בקשה

REST, או העברת מצב ייצוגי, ב-API ל-JSON של חיפוש מותאם אישית שונה מעט מ-REST המסורתי. במקום לספק גישה למשאבים, ה-API מספק גישה לשירות. כתוצאה מכך, ה-API מספק URI יחיד שמשמש כנקודת הקצה של השירות.

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

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

עם כל בקשת חיפוש נדרשות שלוש שאילתות [parameters]:

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

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

לפניכם דוגמה לבקשה שמחפשת הרצאות ב-Programmable Search 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 מתועדים בשדה System Parameters (פרמטרים של המערכת).

נתוני תגובה

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

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

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

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

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

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

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

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

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

תוצאות חיפוש

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

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

REST מ-JavaScript

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

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

<html>
  <head>
    <title>Custom Search JSON API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function hndlr(response) {
      for (var i = 0; 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=cars&callback=hndlr">
    </script>
  </body>
</html>