Method: hashes.search

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

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

בקשת HTTP

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

כתובת ה-URL כתובה בתחביר של gRPC Transcoding.

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

פרמטרים
hashPrefixes[]

string (bytes format)

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

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

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

string

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

המסנן מוגדר באמצעות Google Common Expression Language (שפת ביטויים נפוצה של Google), שאפשר למצוא בכתובת 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.

גוף הבקשה

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

גוף התשובה

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

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

מה חדש בגרסה 5: יש הפרדה בין FullHash לבין FullHashDetail. במקרה שבו הגיבוב מייצג אתר עם כמה איומים (למשל, גם MALWARE וגם SOCIAL_ENGINEERING), אין צורך לשלוח את הגיבוב המלא פעמיים כמו בגרסה 4. בנוסף, משך הזמן של המטמון פושט לשדה 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 שהלקוח מחשיב כלא תקינים. לכן, הלקוח אחראי לבדוק את התוקף של כל ערכי ה-enum‏ ThreatType ו-ThreatAttribute. אם ערך כלשהו נחשב לא חוקי, הלקוח חייב להתעלם מההודעה FullHashDetail כולה.

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

enum (ThreatType)

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

enum (ThreatAttribute)

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

ThreatAttribute

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

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