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

סקירה כללית

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

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

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

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

דוגמה: InvalidMatches.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 ואת ההסברים שמופיעים אחרי דוגמת הקוד.

  {
    "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_ENGINEERING/WINDOWS/URL. לפני שליחת בקשה, יש לבדוק את הסוג השילובים שציינתם חוקיים (ראו רשימות של גלישה בטוחה).

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

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

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

תגובת HTTP POST

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

כותרת תשובה

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

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

גוף התשובה

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

הערה: אם אין התאמות (כלומר, אם לא צוינו כתובות 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 הזו.

מטא-נתונים

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

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

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