نظرة عامة
تسمح واجهة برمجة التطبيقات Lookup API لتطبيقات العميل بإرسال طلبات إلى خوادم "التصفُّح الآمن" للتحقق مما إذا كانت عناوين URL مضمَّنة في أي من قوائم "التصفُّح الآمن". إذا تم العثور على عنوان URL في قائمة واحدة أو أكثر، سيتم عرض المعلومات المطابقة.
التحقق من عناوين URL
للتحقّق مما إذا كان عنوان URL مُدرجًا في قائمة "التصفّح الآمن"، أرسِل طلب HTTP POST
إلى طريقة
threatMatches.find:
- يمكن أن يتضمّن طلب HTTP
POST
ما يصل إلى 500 عنوان URL. ويجب أن تكون عناوين URL صالحة (راجِع RFC 2396) ولكن ليس من الضروري تحديد عنوان URL الأساسي لها أو تشفيرها. - تعرض استجابة HTTP
POST
عناوين URL المطابقة مع مدة ذاكرة التخزين المؤقت.
مثال: usermatchs.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). للحصول على مزيد من التفاصيل، يُرجى الاطّلاع على نص الطلب threatMatches.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) سيتم التحقّق منها مقابل قائمتَي التصفّح الآمن.
ملاحظة: يجب أن تستخدم واجهة برمجة تطبيقات Lookup وطريقة threatMatches
الحقل URL
دائمًا،
وليس الحقل hash
(يمكنك الاطّلاع على ThreatEntry).
استجابة HTTP POST
في المثال التالي، يعرض الردّ نتيجة مطابقة. تم العثور على عنوانَين من عناوين URL الثلاثة المحدّدة في الطلب في إحدى قائمتَي "التصفح الآمن" المحدّدتَين في الطلب.
عنوان الاستجابة
يتضمن عنوان الاستجابة رمز حالة HTTP ونوع المحتوى.
HTTP/1.1 200 OK Content-Type: application/json
نص الاستجابة
ويتضمّن نص الاستجابة معلومات المطابقة (أسماء القوائم وعناوين URL المتوفّرة في هذه القوائم والبيانات الوصفية، إن توفّرت ومدد ذاكرة التخزين المؤقت). للحصول على مزيد من التفاصيل، يُرجى الاطّلاع على نص الاستجابة threatMatches.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 غير آمن
(يُرجى الاطّلاع على التخزين المؤقت).