Method: hashes.search

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

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

בקשת HTTP

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

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

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

פרמטרים
hashPrefixes[]

string (bytes format)

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

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

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

גוף הבקשה

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

גוף התשובה

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

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

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