Method: hashes.search

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

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

בקשת HTTP

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

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

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

פרמטרים
hashPrefixes[]

string (bytes format)

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

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

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

גוף הבקשה

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

גוף התשובה

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

אם לא נמצא דבר, השרת יחזיר סטטוס 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)

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

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 מציין שאין להשתמש ב-threatType לאכיפת מדיניות.
FRAME_ONLY המשמעות היא שצריך להשתמש ב-threatType רק לאכיפת מסגרות.