सुरक्षित ब्राउज़िंग अपडेट एपीआई (v4)

खास जानकारी

Update API की मदद से, आपके क्लाइंट ऐप्लिकेशन, सुरक्षित ब्राउज़िंग की सूचियों के हैश किए गए वर्शन डाउनलोड कर सकते हैं. ऐसा, स्थानीय डेटाबेस में स्टोर करने के लिए किया जाता है. इसके बाद, यूआरएल की जांच स्थानीय तौर पर की जा सकती है. अगर क्लाइंट को स्थानीय डेटाबेस में कोई मैच मिलता है, तो ही उसे सुरक्षित ब्राउज़िंग के सर्वर को अनुरोध भेजना होगा. इससे यह पुष्टि की जा सकेगी कि यूआरएल, सुरक्षित ब्राउज़िंग की सूचियों में शामिल है या नहीं.

अपडेट एपीआई का इस्तेमाल करने से पहले, आपको एक लोकल डेटाबेस सेट अप करना होगा. सुरक्षित ब्राउज़िंग की सुविधा से Go वाला वह पैकेज जिसका इस्तेमाल आसानी से किया जा सकता है. ज़्यादा जानकारी के लिए, लोकल डेटाबेस में जाकर, डेटाबेस सेटअप सेक्शन देखें.

लोकल डेटाबेस अपडेट करना

अपडेट रखने के लिए, क्लाइंट को समय-समय पर अपने स्थानीय डेटाबेस. बैंडविड्थ बचाने के लिए, क्लाइंट रॉ यूआरएल के बजाय, यूआरएल के हैश प्रीफ़िक्स डाउनलोड करते हैं. उदाहरण के लिए, अगर "www.badurl.com/" सुरक्षित ब्राउज़िंग की सूची में है, तो क्लाइंट उस यूआरएल के बजाय, SHA256 हैश प्रीफ़िक्स डाउनलोड करते हैं. ज़्यादातर मामलों में, हैश के प्रीफ़िक्स चार बाइट लंबे होते हैं. इसका मतलब है कि कंप्रेस करने से पहले, सूची की एक एंट्री को डाउनलोड करने के लिए, औसत बैंडविड्थ की लागत चार बाइट होती है.

स्थानीय डेटाबेस में सुरक्षित ब्राउज़िंग की सूचियों को अपडेट करने के लिए, threatListUpdates.fetch तरीके पर एचटीटीपी POST अनुरोध भेजें:

• एचटीटीपी POST अनुरोध में, अपडेट की जाने वाली सूचियों के नामों के साथ-साथ क्लाइंट की कई पाबंदियां भी शामिल होती हैं. इन पाबंदियों की मदद से, मेमोरी और बैंडविड्थ की सीमाओं का हिसाब लगाया जाता है.
• एचटीटीपी POST रिस्पॉन्स, पूरा अपडेट या आंशिक अपडेट दिखाता है. जवाब में, इंतज़ार करने की कम से कम अवधि भी दिख सकती है.

उदाहरण: errorListUpdate.fetch

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

यहां दिए गए उदाहरण में, सुरक्षित ब्राउज़िंग की किसी एक सूची के लिए अपडेट का अनुरोध किया गया है.

अनुरोध का हेडर

अनुरोध के हेडर में, अनुरोध का यूआरएल और कॉन्टेंट का टाइप शामिल होता है. यूआरएल में API_KEY के लिए अपनी एपीआई (एपीआई) कुंजी का इस्तेमाल करना न भूलें.

POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1
Content-Type: application/json

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

अनुरोध के मुख्य हिस्से में क्लाइंट की जानकारी (आईडी और वर्शन) और अपडेट की जानकारी (सूची का नाम, सूची की स्थिति, और क्लाइंट की पाबंदियां) शामिल होती है. ज़्यादा जानकारी के लिए, यह देखें threatListअपडेट.फ़ेच अनुरोध का मुख्य हिस्सा और वे एक्सप्लेनेशंस भी होंगे जो कोड वाले उदाहरण के मुताबिक होंगे.

{
  "client": {
    "clientId":       "yourcompanyname",
    "clientVersion":  "1.5.2"
  },
  "listUpdateRequests": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "state":           "Gg4IBBADIgYQgBAiAQEoAQ==",
    "constraints": {
      "maxUpdateEntries":      2048,
      "maxDatabaseEntries":    4096,
      "region":                "US",
      "supportedCompressions": ["RAW"]
    }
  }]
}

क्लाइंट की जानकारी

clientID और clientVersion फ़ील्ड से, किसी क्लाइंट के लागू होने की खास तौर पर पहचान होनी चाहिए, न कि किसी उपयोगकर्ता की. क्लाइंट की जानकारी का इस्तेमाल, सर्वर-साइड लॉगिंग में किया जाता है. आपके पास ये विकल्प हैं: क्लाइंट आईडी के लिए कोई भी नाम हो, लेकिन हमारा सुझाव है कि आप एक ऐसा नाम चुनें जो क्लाइंट आईडी की वास्तविक पहचान क्लाइंट, जैसे आपकी कंपनी का नाम, अंग्रेज़ी के छोटे अक्षर में, एक शब्द के रूप में दिखाया जाता है.)

सुरक्षित ब्राउज़िंग की सूचियां

threatType, platformType, और threatEntryType फ़ील्ड को सुरक्षित ब्राउज़िंग की सूचियों की पहचान (नाम) करने के लिए किया जाता है. उदाहरण में, एक सूची बताई गई है: मैलवेयर/Windows/यूआरएल. अनुरोध भेजने से पहले, पक्का करें कि आपने टाइप के जो कॉम्बिनेशन तय किए हैं वे मान्य हों (सुरक्षित ब्राउज़िंग की सूचियां देखें).

क्लाइंट की स्थिति

state फ़ील्ड में, सुरक्षित ब्राउज़िंग की सूची के लिए क्लाइंट की मौजूदा स्थिति होती है. (क्लाइंट स्टेटस, threatListUpdates.fetch response के newClientState फ़ील्ड में दिखाए जाते हैं.) शुरुआती अपडेट के लिए, state फ़ील्ड को खाली छोड़ दें.

साइज़ कंस्ट्रेंट

maxUpdateEntries फ़ील्ड से पता चलता है कि क्लाइंट कितने अपडेट मैनेज कर सकता है (उदाहरण के लिए, 2048). maxDatabaseEntries फ़ील्ड से पता चलता है कि लोकल डेटाबेस में कितनी एंट्री मैनेज की जा सकती हैं. उदाहरण के लिए, 4096. क्लाइंट को साइज़ से जुड़ी पाबंदियां सेट करनी चाहिए, ताकि मेमोरी और बैंडविड्थ की सीमाओं को सुरक्षित रखा जा सके. साथ ही, सूची के बढ़ने से बचा जा सके. ज़्यादा जानकारी के लिए, (Update Constraints देखें).

इस्तेमाल किए जा सकने वाले कम्प्रेशन

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

एचटीटीपी पोस्ट रिस्पॉन्स

इस उदाहरण में, रिस्पॉन्स, अनुरोध किया गया संपीड़न प्रकार.

रिस्पॉन्स हेडर

रिस्पॉन्स हेडर में एचटीटीपी स्टेटस कोड शामिल होता है और कॉन्टेंट किस तरह का है. जिन क्लाइंट को एचटीटीपी/200 के अलावा कोई दूसरा स्टेटस कोड मिलता है उन्हें बैक-ऑफ़ मोड में जाना होगा (अनुरोध की फ़्रीक्वेंसी देखें).

HTTP/1.1 200 OK
Content-Type: application/json

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

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

{
  "listUpdateResponses": [{
    "threatType":      "MALWARE",
    "threatEntryType": "URL",
    "platformType":    "WINDOWS",
    "responseType" :   "PARTIAL_UPDATE",
    "additions": [{
      "compressionType": "RAW",
      "rawHashes": {
        "prefixSize": 4,
        "rawHashes":  "rnGLoQ=="
      }
    }],
    "removals": [{
      "compressionType": "RAW",
      "rawIndices": {
        "indices": [0, 2, 4]
      }
    }],
    "newClientState": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
    "checksum": {
      "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
    }
  }],
  "minimumWaitDuration": "593.440s"
}

डेटाबेस के बारे में अपडेट

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

नई क्लाइंट स्थिति

newClientState फ़ील्ड में, सुरक्षित ब्राउज़िंग की नई सूची के लिए क्लाइंट की नई स्थिति होती है. क्लाइंट को बाद में अपडेट करने के अनुरोध करने के लिए, नई क्लाइंट स्थिति को सेव करना होगा (जैसे, state फ़ील्ड threatListअपडेट.फ़ेच अनुरोध या clientStates फ़ील्ड में fullHashes.find का अनुरोध है.

चेकसम

चेकसम क्लाइंट को यह पुष्टि करने देता है कि स्थानीय डेटाबेस को कोई खराब नहीं हुआ है. अगर चेकसम मेल नहीं खाता है, तो क्लाइंट को डेटाबेस को साफ़ करना होगा और एक खाली state फ़ील्ड. हालांकि, इस स्थिति में क्लाइंट को अब भी अपडेट के लिए समय अंतराल का पालन करना होगा (अनुरोध की फ़्रीक्वेंसी देखें).

इंतज़ार का कम से कम समय

minimumWaitDuration फ़ील्ड से पता चलता है कि अपडेट का दूसरा अनुरोध भेजने से पहले, क्लाइंट को 593.44 सेकंड (9.89 मिनट) इंतज़ार करना होगा. ध्यान दें कि रिस्पॉन्स में, इंतज़ार की अवधि शामिल हो सकती है या नहीं (अनुरोध की फ़्रीक्वेंसी देखें).

यूआरएल की जांच करना

यह पता लगाने के लिए कि कोई यूआरएल सुरक्षित ब्राउज़िंग सूची में है या नहीं, क्लाइंट को सबसे पहले हैश और हैश फ़ंक्शन को पूरा करना होगा यूआरएल का प्रीफ़िक्स (यूआरएल और हैशिंग देखें). क्लाइंट इसके बाद, लोकल डेटाबेस से क्वेरी करके पता लगाता है कि कोई मैच है या नहीं. अगर स्थानीय डेटाबेस में हैश प्रीफ़िक्स मौजूद नहीं है, तो यूआरएल को सुरक्षित माना जाता है. इसका मतलब है कि वह सुरक्षित ब्राउज़िंग की सूचियों में शामिल नहीं है.

अगर हैश प्रीफ़िक्स, लोकल डेटाबेस में मौजूद है (हैश प्रीफ़िक्स का कोलिज़न), तो क्लाइंट को पुष्टि के लिए, हैश प्रीफ़िक्स को सुरक्षित ब्राउज़िंग सर्वर पर भेजना होगा. सर्वर, पूरी लंबाई वाले सभी SHA 256 हैश दिखाएंगे जिनमें दिया गया हैश प्रीफ़िक्स शामिल है. अगर उनमें से कोई पूरी लंबाई वाला हैश, बताए गए यूआरएल की पूरी लंबाई के हैश से मेल खाता है, तो तो यूआरएल को असुरक्षित माना जाता है. अगर कोई भी पूरा हैश, जांचे जा रहे यूआरएल के पूरे हैश से मेल नहीं खाता है, तो उस यूआरएल को सुरक्षित माना जाता है.

Google को कभी भी उन यूआरएल के बारे में नहीं पता चलता जिनकी जांच की जा रही है. Google हैश को सीखता है यूआरएल के प्रीफ़िक्स हैं, लेकिन हैश प्रीफ़िक्स असल यूआरएल के बारे में ज़्यादा जानकारी नहीं देते.

यह देखने के लिए कि कोई यूआरएल सुरक्षित ब्राउज़िंग की सूची में है या नहीं, उस यूआरएल पर एचटीटीपी POST अनुरोध भेजें fullHashes.find तरीका:

• एचटीटीपी POST अनुरोध में, खतरे की ज़्यादा से ज़्यादा 500 एंट्री हो सकती हैं.
• एचटीटीपी POST अनुरोध में, जांच किए जाने वाले यूआरएल के हैश प्रीफ़िक्स शामिल होते हैं. हम क्लाइंट को एक ही अनुरोध में, खतरे से जुड़ी कई एंट्री को एक साथ भेजने का सुझाव देते हैं, ताकि बैंडविड्थ का इस्तेमाल कम किया जा सके.
• एचटीटीपी POST रिस्पॉन्स, पॉज़िटिव और कैश मेमोरी में सेव किया गया समय. जवाब एक कम से कम इंतज़ार की अवधि भी लौटा सकता है.

उदाहरण: fullHashes.find

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

नीचे दिए गए उदाहरण में, तुलना और पुष्टि करने के लिए, सुरक्षित ब्राउज़िंग की दो सूचियों और तीन हैश प्रीफ़िक्स के नाम भेजे गए हैं.

अनुरोध का हेडर

अनुरोध हेडर में, अनुरोध का यूआरएल और कॉन्टेंट टाइप शामिल होता है. यूआरएल में API_KEY के लिए अपनी एपीआई पासकोड का इस्तेमाल करना न भूलें.

POST https://safebrowsing.googleapis.com/v4/fullHashes:find?key=API_KEY HTTP/1.1
Content-Type: application/json

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

अनुरोध के मुख्य हिस्से में क्लाइंट की जानकारी (आईडी और वर्शन), क्लाइंट की जानकारी, और खतरे की जानकारी (सूची के नाम और हैश प्रीफ़िक्स). JSON अनुरोधों के लिए, हैश प्रीफ़िक्स को base64 कोड में बदलकर भेजना ज़रूरी है. ज़्यादा जानकारी के लिए, यह देखें fullHashes.find के अनुरोध का मुख्य हिस्सा और वे एक्सप्लेनेशंस भी होंगे जो कोड वाले उदाहरण के मुताबिक होंगे.

{
  "client": {
    "clientId":      "yourcompanyname",
    "clientVersion": "1.5.2"
  },
  "clientStates": [
    "ChAIARABGAEiAzAwMSiAEDABEAE=",
    "ChAIAhABGAEiAzAwMSiAEDABEOgH"
  ],
  "threatInfo": {
    "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
    "platformTypes":    ["WINDOWS"],
    "threatEntryTypes": ["URL"],
    "threatEntries": [
      {"hash": "WwuJdQ=="},
      {"hash": "771MOg=="},
      {"hash": "5eOrwQ=="}
    ]
  }
}

क्लाइंट की जानकारी

clientID और clientVersion फ़ील्ड में, क्लाइंट लागू करने के तरीके की खास तौर पर पहचान की जानी चाहिए, न कि एक अलग उपयोगकर्ता है. क्लाइंट की जानकारी का इस्तेमाल, सर्वर-साइड लॉगिंग में किया जाता है. आप इवेंट के लिए कोई भी नाम चुन सकते हैं लेकिन हमारा सुझाव है कि आप क्लाइंट की वास्तविक पहचान दिखाने वाला नाम चुनें, जैसे आपकी कंपनी का नाम, छोटे अक्षरों में, एक ही शब्द में दिखना चाहिए.)

क्लाइंट की सभी स्थितियां

clientStates फ़ील्ड में, सुरक्षित ब्राउज़िंग की सभी सूचियों के लिए क्लाइंट की स्थितियां तय होती हैं क्लाइंट के लोकल डेटाबेस में रखा जाता है. (क्लाइंट स्टेटस, threatListUpdates.fetch response के newClientState फ़ील्ड में दिखाए जाते हैं.)

सुरक्षित ब्राउज़िंग की सूचियां

threatTypes, platformTypes, और threatEntryTypes फ़ील्ड, सुरक्षित की पहचान (नाम) करने के लिए आपस में जुड़ जाते हैं ब्राउज़िंग सूचियां. उदाहरण में, दो सूचियों की पहचान की गई है: MALWARE/WINDOWS/URL और SOCIAL_ENGINEERING/WINDOWS/URL. अनुरोध भेजने से पहले, पक्का करें कि आपने जो टाइप कॉम्बिनेशन बताए हैं वे मान्य हों. इसके लिए, सुरक्षित ब्राउज़िंग की सूचियां देखें.

थ्रेट हैश प्रीफ़िक्स

sellersEntries के कलेक्शन में, उन यूआरएल के हैश प्रीफ़िक्स होते हैं जिनकी आपको जांच करनी है. hash फ़ील्ड में, स्थानीय डेटाबेस में मौजूद हैश प्रीफ़िक्स होना चाहिए. इसके लिए उदाहरण के लिए, अगर लोकल हैश प्रीफ़िक्स चार बाइट का है, तो खतरे की एंट्री चार बाइट होनी चाहिए. अगर लोकल हैश प्रीफ़िक्स को सात बाइट तक बढ़ाया गया है, तो खतरे की एंट्री सात बाइट की होनी चाहिए.

इस उदाहरण में, अनुरोध में तीन हैश प्रीफ़िक्स शामिल हैं. तीनों प्रीफ़िक्स की तुलना की जाएगी हैश फ़ाइल को सुरक्षित ब्राउज़िंग की सूची में शामिल करता है.

ध्यान दें: अपडेट एपीआई और FullHashes.find वाले तरीके को हमेशा hash फ़ील्ड का इस्तेमाल करना चाहिए, URLफ़ील्ड का इस्तेमाल न करें (ThreatEntry देखें).

एचटीटीपी पीओएसटी रिस्पॉन्स

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

रिस्पॉन्स हेडर

रिस्पॉन्स हेडर में एचटीटीपी स्टेटस कोड शामिल होता है और कॉन्टेंट किस तरह का है. जिन क्लाइंट को एचटीटीपी/200 के अलावा कोई दूसरा स्टेटस कोड मिलता है उन्हें पीछे हट जाना चाहिए (अनुरोध की फ़्रीक्वेंसी देखें).

HTTP/1.1 200 OK
Content-Type: application/json

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

रिस्पॉन्स बॉडी में मैच की जानकारी शामिल होती है. जैसे, सूची के नाम और पूरी लंबाई के हैश, उपलब्ध होने पर मेटाडेटा, और कैश मेमोरी में डेटा सेव रहने की अवधि. उदाहरण में, जवाब के मुख्य हिस्से में यह भी शामिल होता है: कम से कम इंतज़ार का समय. ज़्यादा जानकारी के लिए, fullHashes.find response body और कोड के उदाहरण के बाद दी गई जानकारी देखें.

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4="
    },
    "threatEntryMetadata": {
      "entries": [{
        "key": "bWFsd2FyZV90aHJlYXRfdHlwZQ==",  // base64-encoded "malware_threat_type"
        "value": "TEFORElORw=="  // base64-encoded "LANDING"
       }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "SOCIAL_ENGINEERING",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "771MOrRPMn6xPKlCrXx_CrR-wmCk0LgFFoSgGy7zUiA="
    },
    "threatEntryMetadata": {
      "entries": []
    },
    "cacheDuration": "300.000s"
  }],
  "minimumWaitDuration": "300.000s",
  "negativeCacheDuration": "300.000s"
}

मैच

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

ध्यान दें कि इस उदाहरण में, पूरे लंबाई वाले एक हैश को एक हैश प्रीफ़िक्स से मैच किया गया है. हालांकि, एक ही हैश प्रीफ़िक्स से मैप होने वाले कई पूरे हैश हो सकते हैं.

मेटाडेटा

threatEntryMetadata फ़ील्ड भरना ज़रूरी नहीं है. इससे, खतरे से मिलते-जुलते कॉन्टेंट के बारे में ज़्यादा जानकारी मिलती है. फ़िलहाल, मेटाडेटा मैलवेयर/Windows/यूआरएल की सुरक्षित ब्राउज़िंग सूची के लिए उपलब्ध है (मेटाडेटा देखें).

कैश मेमोरी में सेव की जाने वाली फ़ाइलों के लिए स्टोरेज की अवधि

cacheDuration और negativeCacheDuration फ़ील्ड रकम की जानकारी देते हैं समय की हैशिंग असुरक्षित या सुरक्षित माना जाता है (कैशिंग देखें).

इंतज़ार का कम से कम समय

minimumWaitDuration फ़ील्ड से पता चलता है कि क्लाइंट को fullHashes का दूसरा अनुरोध भेजने से पहले, 300 सेकंड (पांच मिनट) इंतज़ार करना होगा. ध्यान दें कि जवाब में, कुछ समय के लिए इंतज़ार का समय शामिल किया जा सकता है और नहीं भी किया जा सकता (अनुरोध की फ़्रीक्वेंसी देखें).