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

نظرة عامة

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