ממשק API לחיפוש גלישה בטוחה (v4)

סקירה כללית

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

כתובות ה-URL בבדיקה

כדי לבדוק אם כתובת URL מסוימת נמצאת ברשימת הגלישה הבטוחה, צריך לשלוח בקשת HTTP POST למתודה threatMatches.find:

• בקשת ה-HTTP POST יכולה לכלול עד 500 כתובות URL. כתובות ה-URL צריכות להיות תקינות (ראו RFC 2396), אבל אין צורך שהן יהיו קנוניות או מקודדות.
• תגובת ה-HTTP POST מחזירה את כתובות ה-URL התואמות, יחד עם משך הזמן של המטמון.

דוגמה: EveryMatches.find

בקשת HTTP POST

בדוגמה הבאה, שתי רשימות של גלישה בטוחה ושלוש כתובות URL נשלחות לשרת כדי לקבוע אם יש התאמה.

כותרת הבקשה

כותרת הבקשה כוללת את כתובת ה-URL של הבקשה ואת סוג התוכן. אל תשכחו להחליף את מפתח ה-API של API_KEY בכתובת ה-URL.

  POST https://safebrowsing.googleapis.com/v4/threatMatches:find?key=API_KEY HTTP/1.1
  Content-Type: application/json
  

גוף הבקשה

גוף הבקשה כולל את פרטי הלקוח (מזהה וגרסה) ואת פרטי האיום (שמות הרשימה וכתובות ה-URL). פרטים נוספים זמינים בקטע threatMatches.find request body ובהסברים שמופיעים אחרי דוגמת הקוד.

  {
    "client": {
      "clientId":      "yourcompanyname",
      "clientVersion": "1.5.2"
    },
    "threatInfo": {
      "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
      "platformTypes":    ["WINDOWS"],
      "threatEntryTypes": ["URL"],
      "threatEntries": [
        {"url": "http://www.urltocheck1.org/"},
        {"url": "http://www.urltocheck2.org/"},
        {"url": "http://www.urltocheck3.com/"}
      ]
    }
  }

פרטי הלקוח

השדות clientID ו-clientVersion צריכים לזהות הטמעה של לקוח באופן ייחודי, ולא של משתמש יחיד. (פרטי הלקוח משמשים לרישום ביומן וחשבונאות בצד השרת. תוכלו לבחור כל שם למזהה הלקוח, אבל מומלץ לבחור שם שמייצג את הזהות האמיתית של הלקוח, כמו שם החברה שלכם שמוצג כמילה אחת בלבד, באותיות קטנות).

רשימות גלישה בטוחה

השדות threatType, platformType ו-threatEntryType משולבים כדי לזהות רשימות של גלישה בטוחה (שם). בדוגמה הזו מזוהות שתי רשימות: MALWARE/WINDOWS/URL ו-SOCIAL_יקרERING/WINDOWS/URL. לפני שליחת בקשה, חשוב לוודא ששילובי הסוגים שציינתם תקינים (כדאי לעיין בקטע רשימות גלישה בטוחה).

כתובות URL שכוללות איומים

בדוגמה, המערך threatEntries מכיל שלוש כתובות URL (urltocheck1.org, urltocheck2.org ו-urltocheck3.org) שייבדקו מול שתי הרשימות של הגלישה הבטוחה.

הערה: ב-Lookup API וב-method threatMatches תמיד צריך להשתמש בשדה URL, ולא בשדה hash (פרטים נוספים זמינים במאמר ThreatEntry).

תשובת HTTP POST

בדוגמה הבאה, התגובה מחזירה התאמה. שתיים משלוש כתובות ה-URL שצוינו בבקשה נמצאות באחת משתי הרשימות של הגלישה הבטוחה שצוינו בבקשה.

כותרת תגובה

כותרת התגובה כוללת את קוד הסטטוס של HTTP ואת סוג התוכן.

HTTP/1.1 200 OK
Content-Type: application/json

גוף התגובה

גוף התגובה כולל את פרטי ההתאמה (שמות הרשימות וכתובות ה-URL שברשימות האלה, המטא-נתונים (אם הם זמינים) ומשך הזמן של המטמון). תוכלו לקרוא פרטים נוספים בקטע threatMatches.find body ובהסברים שמופיעים אחרי דוגמת הקוד.

הערה: אם אין התאמות (כלומר, אם אף מכתובות ה-URL שצוינו בבקשה לא נמצאות באחת מהרשימות שצוינו בבקשה), תגובת HTTP POST פשוט תחזיר אובייקט ריק בגוף התגובה.

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat":          {"url": "http://www.urltocheck1.org/"},
    "threatEntryMetadata": {
      "entries": [{
        "key": "malware_threat_type",
        "value": "landing"
     }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat":          {"url": "http://www.urltocheck2.org/"},
    "threatEntryMetadata": {
      "entries": [{
        "key":   "malware_threat_type",
        "value": "landing"
     }]
    },
    "cacheDuration": "300.000s"
  }]
}

התאמות

באובייקט matches מפורטים השמות של רשימות הגלישה הבטוחה וכתובות ה-URL – אם יש התאמה. בדוגמה, שתי כתובות URL (urltocheck1.org ו-urltocheck2.org) נמצאו באחת מרשימות הגלישה הבטוחה (MALWARE/WINDOWS/URL), כך שהמידע התואם מוחזר. כתובת ה-URL השלישית (urltocheck3.org) לא נמצאה באף אחת מהרשימות, ולכן לא מוחזר מידע לגבי כתובת ה-URL הזו.

Metadata

השדה threatEntryMetadata הוא אופציונלי ומספק מידע נוסף על התאמת האיום. נכון לעכשיו, המטא-נתונים זמינים ברשימת הגלישה הבטוחה של MALWARE/Windows/URL (מידע נוסף בקטע מטא-נתונים).

משך הזמן של המטמון

השדה cacheDuration מציין את משך הזמן שבו כתובת ה-URL צריכה להיחשב לא בטוחה (מידע נוסף זמין בקטע שמירה במטמון).