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

نظرة عامة

تتيح واجهة برمجة تطبيقات Lookup لتطبيقات تطبيقاتك إرسال طلبات إلى خوادم التصفح الآمن للتحقق مما إذا تم تضمين عناوين URL في أي من قوائم التصفح الآمن أم لا. إذا تم العثور على عنوان URL في قائمة واحدة أو أكثر، يتم عرض المعلومات المطابقة.

التحقق من عناوين URL

للتحقّق مما إذا كان عنوان URL ضمن قائمة "التصفّح الآمن"، أرسِل طلب HTTP POST إلى طريقة threatMatches.find:

• يمكن أن يتضمّن طلب HTTP POST ما يصل إلى 500 عنوان URL. ويجب أن تكون عناوين URL صالحة (راجِع RFC 2396) ولكن ليس من الضروري أن تكون أساسية أو أن يتم ترميزها.
• تعرض استجابة HTTP POST عناوين URL المطابقة بالإضافة إلى مدة ذاكرة التخزين المؤقت.

مثال: تهديدات تطابق.العثور

طلب HTTP POST

في المثال التالي، يتم إرسال قائمتَي "التصفّح الآمن" و3 عناوين 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 من بين عناوين 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 غير آمن (راجع التخزين المؤقت).