Method: hashes.search

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

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

בקשת HTTP

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

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

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

פרמטרים
hashPrefixes[]

string (bytes format)

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

בשלב הזה, כל קידומת גיבוב (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).

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

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

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

object (FullHash)

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

string (Duration format)

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

אם השדה 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

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

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