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

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

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

שליחת בקשה

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

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

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

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

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

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

הנה דוגמה לבקשה שמחפשת Test 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 ומגדירים מתבצע סיכום של בקשות החיפוש הפניה.

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

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

נתוני תגובה

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

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

<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>