Method: hashes.search

यह फ़ंक्शन, तय किए गए प्रीफ़िक्स से मेल खाने वाले पूरे हैश खोजता है.

यह एक कस्टम तरीका है, जैसा कि https://google.aip.dev/136 में बताया गया है. कस्टम तरीके का मतलब है कि Google के सामान्य एपीआई डेवलपमेंट नोमेनक्लेचर में इस तरीके का कस्टम नाम है. इसका मतलब कस्टम एचटीटीपी तरीके का इस्तेमाल करना नहीं है.

एचटीटीपी अनुरोध

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

यह यूआरएल, gRPC ट्रांसकोडिंग सिंटैक्स का इस्तेमाल करता है.

क्वेरी पैरामीटर

पैरामीटर
hashPrefixes[]

string (bytes format)

ज़रूरी है. वे हैश प्रीफ़िक्स जिन्हें खोजना है. क्लाइंट को 1,000 से ज़्यादा हैश प्रीफ़िक्स नहीं भेजने चाहिए. हालांकि, यूआरएल प्रोसेसिंग की प्रक्रिया के बाद, क्लाइंट को 30 से ज़्यादा हैश प्रीफ़िक्स भेजने की ज़रूरत नहीं होनी चाहिए.

फ़िलहाल, हर हैश प्रीफ़िक्स की लंबाई ठीक चार बाइट होनी चाहिए. ऐसा हो सकता है कि आने वाले समय में, इसमें कुछ बदलाव किए जाएं.

base64 कोड में बदली गई स्ट्रिंग.
filter

string

ज़रूरी नहीं. अगर क्लाइंट को फ़िल्टर करने में दिलचस्पी है, जैसे कि सिर्फ़ कुछ खास तरह के खतरों को वापस पाना है, तो इसे बताया जा सकता है. अगर इसे शामिल नहीं किया जाता है, तो मेल खाने वाली सभी थ्रेट वापस आ जाती हैं. हमारा सुझाव है कि आप इस विकल्प को न चुनें, ताकि आपको सुरक्षित ब्राउज़िंग की सुविधा से ज़्यादा से ज़्यादा सुरक्षा मिल सके.

फ़िल्टर को 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 हो.

अनुरोध का मुख्य भाग

अनुरोध का मुख्य हिस्सा खाली होना चाहिए.

जवाब का मुख्य भाग

खतरे के हैश खोजने के बाद मिला जवाब.

अगर कुछ भी नहीं मिलता है, तो सर्वर, NOT_FOUND स्टेटस (एचटीटीपी स्टेटस कोड 404) दिखाने के बजाय, OK स्टेटस (एचटीटीपी स्टेटस कोड 200) दिखाएगा. साथ ही, fullHashes फ़ील्ड खाली होगा.

V5 में नया क्या है: FullHash और FullHashDetail को अलग कर दिया गया है. अगर कोई हैश ऐसी साइट को दिखाता है जिस पर कई तरह के खतरे मौजूद हैं (जैसे, MALWARE और SOCIAL_ENGINEERING, दोनों), तो पूरे हैश को V4 की तरह दो बार भेजने की ज़रूरत नहीं है. इसके अलावा, कैश मेमोरी की अवधि को एक ही 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 की नीति है. वर्शनिंग की नीति के लिए, https://cloud.google.com/apis/design/versioning देखें. इसलिए, क्लाइंट को FullHashDetail मैसेज पाने के लिए तैयार रहना चाहिए. इन मैसेज में ThreatType enum वैल्यू या ThreatAttribute enum वैल्यू होती हैं, जिन्हें क्लाइंट अमान्य मानता है. इसलिए, यह क्लाइंट की ज़िम्मेदारी है कि वह सभी ThreatType और ThreatAttribute enum वैल्यू की वैधता की जांच करे. अगर कोई वैल्यू अमान्य मानी जाती है, तो क्लाइंट को पूरे FullHashDetail मैसेज को अनदेखा करना होगा.

JSON के काेड में दिखाना 
{
  "threatType": enum (ThreatType),
  "attributes": [
    enum (ThreatAttribute)
  ]
}
फ़ील्ड
threatType

enum (ThreatType)

खतरे का टाइप. यह फ़ील्ड कभी खाली नहीं होगा.
attributes[]

enum (ThreatAttribute)

बिना क्रम वाली सूची. उन पूरे हैश के बारे में अन्य एट्रिब्यूट. यह खाली हो सकता है.

ThreatAttribute

खतरों के एट्रिब्यूट. इन एट्रिब्यूट से, किसी खास खतरे के बारे में ज़्यादा जानकारी मिल सकती है. हालांकि, इससे खतरे के टाइप पर कोई असर नहीं पड़ेगा. उदाहरण के लिए, किसी एट्रिब्यूट के लिए कॉन्फ़िडेंस लेवल कम हो सकता है, जबकि किसी दूसरे एट्रिब्यूट के लिए कॉन्फ़िडेंस लेवल ज़्यादा हो सकता है. आने वाले समय में, इसमें और एट्रिब्यूट जोड़े जा सकते हैं.

Enums
THREAT_ATTRIBUTE_UNSPECIFIED अनजान एट्रिब्यूट. अगर सर्वर से यह वैल्यू मिलती है, तो क्लाइंट FullHashDetail को पूरी तरह से अनदेखा कर देगा.
CANARY इससे पता चलता है कि threatType का इस्तेमाल, नीति उल्लंघन ठीक करने के लिए नहीं किया जाना चाहिए.
FRAME_ONLY इससे पता चलता है कि threatType का इस्तेमाल सिर्फ़ फ़्रेम पर लागू करने के लिए किया जाना चाहिए.