חיפוש גיבובים מלאים שתואמים לקידומות שצוינו.
זוהי שיטה מותאמת אישית כפי שמוגדר על ידי https://google.aip.dev/136 (השיטה המותאמת אישית מתייחסת לכך שיש לשיטה הזו שם מותאם אישית במסגרת מינוח הפיתוח הכללי של Google API; היא לא מתייחסת לשימוש בשיטת HTTP מותאמת אישית).
בקשת HTTP
GET https://safebrowsing.googleapis.com/v5alpha1/hashes:search
בכתובת ה-URL נעשה שימוש בתחביר המרת קידוד של gRPC.
פרמטרים של שאילתה
פרמטרים | |
---|---|
hashPrefixes[] |
חובה. יש לחפש את קידומות הגיבוב. אסור ללקוחות לשלוח יותר מ-1,000 קידומות גיבוב. עם זאת, בהתאם לתהליך עיבוד כתובות האתרים, לקוחות לא אמורים לשלוח יותר מ-30 קידומות hash. בשלב זה, כל קידומת גיבוב נדרשת להיות באורך של 4 בייטים בדיוק. זה עשוי להיות רגוע בעתיד. מחרוזת בקידוד base64. |
filter |
זה שינוי אופציונלי. אם הלקוח מעוניין לבצע סינון, למשל אחזור סוגים ספציפיים של איומים, אפשר לציין את זה. אם הוא יושמט, יוחזרו כל האיומים התואמים. מומלץ מאוד להשמיט אותה כדי לקבל את ההגנה המלאה ביותר שהגלישה הבטוחה יכולה להציע. המסנן מצוין באמצעות Google Common Expression Language, שמופיעה בכתובת https://github.com/google/cel-spec יחד עם דוגמאות כלליות. הנה כמה דוגמאות ספציפיות שאפשר להשתמש בהן כאן: המסנן המסנן |
גוף הבקשה
גוף הבקשה חייב להיות ריק.
גוף התשובה
התשובה הוחזרה אחרי חיפוש 'גיבובים' של איומים.
אם לא נמצא דבר, השרת יחזיר סטטוס תקין (קוד מצב HTTP 200) כשהשדה fullHashes
ריק, במקום להחזיר סטטוס NOT_FOUND (קוד מצב HTTP 404).
מה חדש ב-V5: יש הפרדה בין FullHash
ל-FullHashDetail
. במקרה שבו גיבוב מייצג אתר עם מספר איומים (למשל, MALWARE וגם SOCIAL_engineERING), אין צורך לשלוח את הגיבוב המלא פעמיים כמו ב-V4. בנוסף, משך הזמן של המטמון הופשט לשדה cacheDuration
אחד.
אם הפעולה בוצעה ללא שגיאות, גוף התשובה מכיל נתונים במבנה הבא:
ייצוג JSON |
---|
{
"fullHashes": [
{
object ( |
שדות | |
---|---|
fullHashes[] |
רשימה לא ממוינת. נמצאה רשימה לא ממוינת של גיבובים מלאים. |
cacheDuration |
משך הזמן של המטמון בצד הלקוח. הלקוח חייב להוסיף את משך הזמן הזה לזמן הנוכחי כדי לקבוע את זמן התפוגה. זמן התפוגה חל לאחר מכן על כל קידומת גיבוב שמציגה את הלקוח בבקשה, ללא קשר למספר הגיבובים המלאים שמוחזרים בתגובה. גם אם השרת לא מחזיר גיבובים מלאים עבור קידומת גיבוב מסוימת, גם עובדה זו חייבת להישמר במטמון על ידי הלקוח. אם ורק אם השדה חשוב: הלקוח לא יכול להניח שהשרת יחזיר את אותו משך מטמון לכל התגובות. השרת עשוי לבחור משך זמן שונה של מטמון לתגובות שונות, בהתאם למצב. משך זמן בשניות עם עד תשע ספרות עשרוניות, המסתיים ב-' |
FullHash
הגיבוב המלא שזוהה עם התאמה אחת או יותר.
ייצוג JSON |
---|
{
"fullHash": string,
"fullHashDetails": [
{
object ( |
שדות | |
---|---|
fullHash |
הגיבוב המלא התואם. זהו גיבוב SHA256. האורך יהיה 32 בייטים בדיוק. מחרוזת בקידוד base64. |
fullHashDetails[] |
רשימה לא ממוינת. שדה חוזר שמזהה את הפרטים הרלוונטיים לגיבוב המלא הזה. |
FullHashDetail
פרטים על גיבוב מלא תואם.
הערה חשובה לגבי תאימות העברה: השרת יכול להוסיף סוגי איומים חדשים ומאפייני איומים בכל שלב. התוספות האלה נחשבות לשינויים קטנים בגרסה. המדיניות של Google היא לא לחשוף מספרי גרסאות משניות בממשקי API (בכתובת https://cloud.google.com/apis/design/versioning מופיעה המדיניות בנושא ניהול גרסאות), ולכן הלקוחות חייבים להיות מוכנים לקבל הודעות FullHashDetail
שמכילות ערכי enum מסוג ThreatType
או ערכי enum מסוג ThreatAttribute
שנחשבים לא חוקיים על ידי הלקוח. לכן, באחריות הלקוח לבדוק את החוקיות של כל הערכים מסוג 'ThreatType
' ו-'ThreatAttribute
'. אם ערך כלשהו נחשב לא חוקי, הלקוח חייב להתעלם מההודעה FullHashDetail
במלואה.
ייצוג JSON |
---|
{ "threatType": enum ( |
שדות | |
---|---|
threatType |
סוג האיום. השדה הזה אף פעם לא יהיה ריק. |
attributes[] |
רשימה לא ממוינת. מאפיינים נוספים לגבי הגיבובים המלאים. יכול להיות שהשדה הזה ריק. |
ThreatAttribute
מאפיינים של איומים. ייתכן שהמאפיינים האלה יתנו משמעות נוספת לאיום מסוים, אבל לא ישפיעו על סוג האיום. לדוגמה, מאפיין מסוים עשוי לציין רמת סמך נמוכה יותר, ומאפיין אחר עשוי לציין רמת סמך גבוהה יותר. יכול להיות שמאפיינים נוספים יתווספו בעתיד.
טיפוסים בני מנייה (enums) | |
---|---|
THREAT_ATTRIBUTE_UNSPECIFIED |
מאפיין לא ידוע. אם השרת מחזיר זאת, הלקוח יתעלם לגמרי מה-FullHashDetail המצורף. |
CANARY |
האפשרות מציינת שאין להשתמש בסוג האיום לצורך אכיפה. |
FRAME_ONLY |
ההערה מציינת שיש להשתמש ב-איומים על פריימים רק לצורך אכיפה. |