Custom Search JSON API: מבוא

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

לפני שמתחילים

יצירת Programmable Search Engine

כדי לשלוח בקשות למופע קיים של Programmable Search Engine, המשתמש צריך להפעיל את ה-API. לכן, לפני שמשתמשים ב-API, צריך ליצור מפתח בלוח הבקרה. במדריך מוסבר על אפשרויות ההגדרה השונות. אחרי שיוצרים אותו, אפשר למצוא את מזהה מנוע החיפוש בקטע Basic (בסיסי) בדף Overview (סקירה כללית). זהו הפרמטר cx שמשמש את ה-API.

זיהוי האפליקציה ב-Google באמצעות מפתח API

כדי להשתמש ב-Custom Search API בפורמט JSON, צריך מפתח API. מפתח API הוא דרך לזהות את הלקוח שלכם ב-Google.

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

סקירה כללית על ממשקי API

פעולות API

יש רק method אחת להפעלה ב-Custom Search API בפורמט JSON:

פעולה תיאור מיפוי REST HTTP
list הפונקציה מחזירה את תוצאות החיפוש המבוקשות מ-Programmable Search Engine. GET

מודל הנתונים של ה-API

התוצאה של שאילתת חיפוש ב-Custom Search API בפורמט JSON היא אובייקט JSON שכולל שלושה סוגי נתונים:

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

פרטים נוספים זמינים בקטע "נתוני התגובה" במאמר שימוש ב-REST.

מודל הנתונים מבוסס על מפרט OpenSearch 1.1. בנוסף למאפיינים הרגילים של OpenSearch, ב-Custom Search API בפורמט JSON מוגדרים שני מאפיינים מותאמים אישית ושני תפקידי שאילתה מותאמים אישית:

  • מאפיינים מותאמים אישית
    • cx: המזהה של Programmable Search Engine.
    • ‫safe: תיאור של רמת החיפוש הבטוח לסינון התוצאות שמוחזרות.
  • תפקידים של שאילתות בהתאמה אישית
    • ‫nextPage: תפקיד שמציין שאפשר להשתמש בשאילתה כדי לגשת לדף התוצאות הלוגי הבא, אם יש כזה.
    • ‫previousPage: תפקיד שמציין שאפשר להשתמש בשאילתה כדי לגשת לדף הלוגי הקודם של התוצאות, אם יש כזה.

אני רוצה לנסות

כדי להתנסות ולראות מה ה-API יכול לעשות בלי לכתוב קוד, אפשר להשתמש בכלי "רוצה לנסות את ה-API הזה?".

תיאור מלא של הפרמטרים מופיע בחומר העזר בנושא cse.list.

כדי ללמוד איך להשתמש ב-API באמצעות בקשות HTTP, המשיכו לקרוא את המאמר שימוש ב-REST.