Method: hashes.search

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

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

בקשת HTTP

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

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

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

פרמטרים
hashPrefixes[]

string (bytes format)

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

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

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

גוף הבקשה

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

גוף התשובה

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

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

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

ThreatType

סוגי איומים.

טיפוסים בני מנייה (enum)
THREAT_TYPE_UNSPECIFIED סוג האיום לא ידוע. אם השרת מחזיר את הערך הזה, הלקוח יתעלם לגמרי מה-FullHashDetail שמצורף.
MALWARE

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

מידע נוסף זמין כאן
SOCIAL_ENGINEERING

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

מידע נוסף זמין כאן
UNWANTED_SOFTWARE סוג איום של תוכנה לא רצויה. תוכנה לא רצויה היא כל תוכנה שלא פועלת בהתאם לעקרונות התוכנה של Google אבל לא תוכנה זדונית.
POTENTIALLY_HARMFUL_APPLICATION סוג איום של אפליקציה שעלולה להזיק בשימוש של Google Play Protect בחנות Play.

ThreatAttribute

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

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