Method: hashes.search

חיפוש גיבובים מלאים שתואמים לקידומות שצוינו.

זוהי שיטה מותאמת אישית כפי שמוגדר על ידי https://google.aip.dev/136 (השיטה המותאמת אישית מתייחסת לכך שיש לשיטה הזו שם מותאם אישית במסגרת מינוח הפיתוח הכללי של Google API; היא לא מתייחסת לשימוש בשיטת HTTP מותאמת אישית).

בקשת HTTP

GET https://safebrowsing.googleapis.com/v5alpha1/hashes:search

בכתובת ה-URL נעשה שימוש בתחביר המרת קידוד של gRPC.

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

פרמטרים
hashPrefixes[]

string (bytes format)

חובה. יש לחפש את קידומות הגיבוב. אסור ללקוחות לשלוח יותר מ-1,000 קידומות גיבוב. עם זאת, בהתאם לתהליך עיבוד כתובות האתרים, לקוחות לא אמורים לשלוח יותר מ-30 קידומות hash.

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

מחרוזת בקידוד base64.
filter

string

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

המסנן מצוין באמצעות Google Common Expression Language, שמופיעה בכתובת https://github.com/google/cel-spec יחד עם דוגמאות כלליות. הנה כמה דוגמאות ספציפיות שאפשר להשתמש בהן כאן:

המסנן "threatType == ThreatType.SOCIAL_ENGINEERING" מחייב שבתוך FullHashDetail סוג האיום יהיה SOCIAL_ENGINEERING. המזהה "threatType" מתייחס לסוג האיום הנוכחי. המזהה "ThreatType" מתייחס לאיסוף של כל סוגי האיומים האפשריים.

המסנן "threatType in [ ThreatType.UNWANTED_SOFTWARE, ThreatType.MALWARE ]" מחייב שסוג האיום יהיה UNWANTED_SOFTWARE או MALWARE.

גוף הבקשה

גוף הבקשה חייב להיות ריק.

גוף התשובה

התשובה הוחזרה אחרי חיפוש 'גיבובים' של איומים.

אם לא נמצא דבר, השרת יחזיר סטטוס תקין (קוד מצב HTTP 200) כשהשדה fullHashes ריק, במקום להחזיר סטטוס NOT_FOUND (קוד מצב HTTP 404).

מה חדש ב-V5: יש הפרדה בין FullHash ל-FullHashDetail. במקרה שבו גיבוב מייצג אתר עם מספר איומים (למשל, MALWARE וגם SOCIAL_engineERING), אין צורך לשלוח את הגיבוב המלא פעמיים כמו ב-V4. בנוסף, משך הזמן של המטמון הופשט לשדה cacheDuration אחד.

אם הפעולה בוצעה ללא שגיאות, גוף התשובה מכיל נתונים במבנה הבא:

ייצוג JSON 
{
  "fullHashes": [
    {
      object (FullHash)
    }
  ],
  "cacheDuration": string
}
שדות
fullHashes[]

object (FullHash)

רשימה לא ממוינת. נמצאה רשימה לא ממוינת של גיבובים מלאים.
cacheDuration

string (Duration format)

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

אם ורק אם השדה fullHashes ריק, הלקוח עשוי להגדיל את הערך cacheDuration כדי לקבוע תאריך תפוגה חדש מאוחר יותר מזה שצוין על ידי השרת. בכל מקרה, משך הזמן המוגדל של המטמון לא יכול להיות ארוך מ-24 שעות.

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

משך זמן בשניות עם עד תשע ספרות עשרוניות, המסתיים ב-'s'. דוגמה: "3.5s".

FullHash

הגיבוב המלא שזוהה עם התאמה אחת או יותר.

ייצוג JSON 
{
  "fullHash": string,
  "fullHashDetails": [
    {
      object (FullHashDetail)
    }
  ]
}
שדות
fullHash

string (bytes format)

הגיבוב המלא התואם. זהו גיבוב SHA256. האורך יהיה 32 בייטים בדיוק.

מחרוזת בקידוד base64.
fullHashDetails[]

object (FullHashDetail)

רשימה לא ממוינת. שדה חוזר שמזהה את הפרטים הרלוונטיים לגיבוב המלא הזה.

FullHashDetail

פרטים על גיבוב מלא תואם.

הערה חשובה לגבי תאימות העברה: השרת יכול להוסיף סוגי איומים חדשים ומאפייני איומים בכל שלב. התוספות האלה נחשבות לשינויים קטנים בגרסה. המדיניות של Google היא לא לחשוף מספרי גרסאות משניות בממשקי API (בכתובת https://cloud.google.com/apis/design/versioning מופיעה המדיניות בנושא ניהול גרסאות), ולכן הלקוחות חייבים להיות מוכנים לקבל הודעות FullHashDetail שמכילות ערכי enum מסוג ThreatType או ערכי enum מסוג ThreatAttribute שנחשבים לא חוקיים על ידי הלקוח. לכן, באחריות הלקוח לבדוק את החוקיות של כל הערכים מסוג 'ThreatType' ו-'ThreatAttribute'. אם ערך כלשהו נחשב לא חוקי, הלקוח חייב להתעלם מההודעה FullHashDetail במלואה.

ייצוג JSON 
{
  "threatType": enum (ThreatType),
  "attributes": [
    enum (ThreatAttribute)
  ]
}
שדות
threatType

enum (ThreatType)

סוג האיום. השדה הזה אף פעם לא יהיה ריק.
attributes[]

enum (ThreatAttribute)

רשימה לא ממוינת. מאפיינים נוספים לגבי הגיבובים המלאים. יכול להיות שהשדה הזה ריק.

ThreatAttribute

מאפיינים של איומים. ייתכן שהמאפיינים האלה יתנו משמעות נוספת לאיום מסוים, אבל לא ישפיעו על סוג האיום. לדוגמה, מאפיין מסוים עשוי לציין רמת סמך נמוכה יותר, ומאפיין אחר עשוי לציין רמת סמך גבוהה יותר. יכול להיות שמאפיינים נוספים יתווספו בעתיד.

טיפוסים בני מנייה (enums)
THREAT_ATTRIBUTE_UNSPECIFIED מאפיין לא ידוע. אם השרת מחזיר זאת, הלקוח יתעלם לגמרי מה-FullHashDetail המצורף.
CANARY האפשרות מציינת שאין להשתמש בסוג האיום לצורך אכיפה.
FRAME_ONLY ההערה מציינת שיש להשתמש ב-איומים על פריימים רק לצורך אכיפה.