واجهة برمجة التطبيقات للبحث في التصفح الآمن (الإصدار 4)

نظرة عامة

تسمح واجهة برمجة التطبيقات 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 غير آمن (يُرجى الاطّلاع على التخزين المؤقت).