نظرة عامة
تسمح واجهة برمجة تطبيقات البحث لتطبيقات العميل بإرسال طلبات إلى ميزة "التصفح الآمن". التحقق من تضمين عناوين URL في أي من قوائم التصفح الآمن. إذا تم العثور على عنوان URL على أحد المواقع الإلكترونية على المزيد من القوائم، يتم عرض المعلومات المطابقة.
التحقق من عناوين URL
للتأكّد من أنّ عنوان URL مدرَج في قائمة "التصفّح الآمن"، أرسِل طلب HTTP POST
إلى
threatMatches.find
:
- ويمكن أن يتضمّن طلب HTTP
POST
ما يصل إلى 500 عنوان URL. يجب أن تكون عناوين URL صالحة. (راجِع RFC 2396) ولكن ليس من الضروري تحديد عنوان URL الأساسي لها أو ترميزها. - تعرض استجابة HTTP
POST
عناوين URL المطابقة بالإضافة إلى مدة ذاكرة التخزين المؤقت.
مثال: recognizedMatch.find
طلب HTTP POST
في المثال التالي، يتم إرسال قائمتين من التصفح الآمن وثلاثة عناوين URL إلى الخادم إلى لتحديد ما إذا كان هناك تطابق.
عنوان الطلب
يتضمّن عنوان الطلب عنوان URL للطلب ونوع المحتوى. تذكر أن تستبدل
مفتاح واجهة برمجة التطبيقات لـ API_KEY
في عنوان URL.
POST https://safebrowsing.googleapis.com/v4/threatMatches:find?key=API_KEY HTTP/1.1 Content-Type: application/json
نص الطلب
يتضمّن نص الطلب معلومات العميل (رقم التعريف والإصدار) ومعلومات التهديد. (أسماء القوائم وعناوين URL). لمزيد من التفاصيل، يُرجى مراجعة threatمباريات.find نص الطلب والتفسيرات التي تتبع مثال التعليمة البرمجية.
{ "client": { "clientId": "yourcompanyname", "clientVersion": "1.5.2" }, "threatInfo": { "threatTypes": ["MALWARE", "SOCIAL_ENGINEERING"], "platformTypes": ["WINDOWS"], "threatEntryTypes": ["URL"], "threatEntries": [ {"url": "http://www.urltocheck1.org/"}, {"url": "http://www.urltocheck2.org/"}, {"url": "http://www.urltocheck3.com/"} ] } }
معلومات العميل
يجب أن يحدّد الحقلان clientID
وclientVersion
عملية تنفيذ العميل بشكل فريد، وليس
مستخدم فردي. (تُستخدم معلومات العميل للتسجيل والمحاسبة من جانب الخادم. يمكنك الاختيار مما يلي:
أي اسم لمعرف العميل، ولكننا نقترح عليك اختيار اسم يمثل الهوية الحقيقية
العميل، مثل اسم شركتك، فيكون مكونًا من كلمة واحدة وبأحرف لاتينية صغيرة فقط).
قوائم التصفّح الآمن
الحقول threatType
وplatformType
وthreatEntryType
لتحديد (الاسم) قوائم التصفح الآمن. في المثال، تم تحديد قائمتَين:
MALWARE/WINDOWS/URL وSOCIAL_ENGINEERING/WINDOWS/URL. قبل إرسال طلب، تأكَّد من أنّ نوع الطلب
التي تُحدِّدها صالحة (يمكنك الاطِّلاع على قوائم التصفُّح الآمن).
عناوين URL للتهديد
في المثال، تحتوي المصفوفة threatEntries
على ثلاثة عناوين URL (urltocheck1.org وurltocheck2.org
وurltocheck3.org) التي سيتم التحقق منها مقابل قائمتي التصفح الآمن.
ملاحظة: يجب أن تستخدم واجهة برمجة تطبيقات البحث والطريقة threatMatches
دائمًا الحقل URL
،
أبدًا hash
(راجِع ThreatEntry).
استجابة HTTP POST
في المثال التالي، تعرض الإجابة مطابقة؛ اثنين من عناوين URL الثلاثة المحددة في طلبك في إحدى قائمتي التصفح الآمن المحددين في الطلب.
عنوان الاستجابة
يتضمّن عنوان الاستجابة رمز حالة HTTP. ونوع المحتوى.
HTTP/1.1 200 OK Content-Type: application/json
نص الاستجابة
يتضمن نص الاستجابة معلومات المطابقة (أسماء القوائم وعناوين URL الموجودة على وتلك القوائم والبيانات الوصفية، إن توفرت، ومدد ذاكرة التخزين المؤقت). لمزيد من التفاصيل، يُرجى مراجعة threatمباريات.find نص الاستجابة والتفسيرات التي تتبع مثال التعليمة البرمجية.
ملاحظة: في حال لم تكن هناك أي مطابقات (أي إذا لم يكن هناك أي من عناوين URL المحدَّدة)
في الطلب في أي قائمة من القوائم المحددة في أحد الطلبات)، أو استجابة HTTP POST
كائنًا فارغًا في نص الاستجابة.
{ "matches": [{ "threatType": "MALWARE", "platformType": "WINDOWS", "threatEntryType": "URL", "threat": {"url": "http://www.urltocheck1.org/"}, "threatEntryMetadata": { "entries": [{ "key": "malware_threat_type", "value": "landing" }] }, "cacheDuration": "300.000s" }, { "threatType": "MALWARE", "platformType": "WINDOWS", "threatEntryType": "URL", "threat": {"url": "http://www.urltocheck2.org/"}, "threatEntryMetadata": { "entries": [{ "key": "malware_threat_type", "value": "landing" }] }, "cacheDuration": "300.000s" }] }
سلسلة مطابقة لـ
يسرد الكائن matches
أسماء قوائم "التصفح الآمن" وعناوين URL، في حال
هناك تطابق. في المثال، تم العثور على عنوانَي URL (urltocheck1.org وurltocheck2.org) على أحد
قوائم التصفح الآمن (MALWARE/WINDOWS/عنوان URL) لذلك يتم عرض المعلومات المطابقة. عنوان URL الثالث
لم يتم العثور على (urltocheck3.org) في أي من القائمتين، لذلك لا يتم عرض أي معلومات لعنوان URL هذا.
البيانات الوصفية
الحقل threatEntryMetadata
اختياري ويقدم معلومات إضافية عن
تطابق التهديد. في الوقت الحالي، تتوفر البيانات الوصفية لقائمة "التصفح الآمن" لبرامج MALWARE/WINDOWS/URL
(راجع البيانات الوصفية).
مُدد ذاكرة التخزين المؤقت
يشير الحقل cacheDuration
إلى المدّة الزمنية التي يجب أن يتم فيها اعتبار عنوان URL غير آمن.
(يُرجى الاطّلاع على التخزين المؤقت).