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

نظرة عامة

تسمح واجهة برمجة التطبيقات Update API لتطبيقات العميل بتنزيل نُسخ مجزّأة من قوائم "التصفّح الآمن" بهدف تخزينها في قاعدة بيانات محلية. ويمكن بعد ذلك التحقّق من عناوين URL على الجهاز. فقط إذا تم العثور على تطابق في يحتاج العميل إلى إرسال طلب إلى خوادم التصفح الآمن للتحقق من قاعدة البيانات المحلية ما إذا كان عنوان URL مدرَجًا في قوائم "التصفّح الآمن" أم لا.

قبل استخدام Update API، عليك إعداد قاعدة بيانات محلية. توفّر ميزة "التصفّح الآمن" حزمة Go يمكنك استخدامها للبدء. لمزيد من التفاصيل، راجع القسم إعداد قاعدة البيانات ضمن قواعد البيانات المحلية.

تعديل قاعدة البيانات المحلية

للاطّلاع على أحدث المعلومات، يُطلب من العملاء تحديث قوائم "التصفّح الآمن" بشكل دوري في بقاعدة بيانات محلية. لتوفير معدل نقل البيانات، يُنزِّل العملاء بادئات التجزئة لعناوين URL بدلاً من عناوين URL الأولية. على سبيل المثال، إذا كان "www.badurl.com/" مُدرجة في قائمة "التصفح الآمن"، فسينزّل العملاء بادئة التجزئة SHA256 لعنوان URL هذا بدلاً من عنوان URL نفسه. في معظم الحالات، تكون بادئات التجزئة بطول 4 بايت، ما يعني أنّ متوسط تكلفة النطاق الترددي لتنزيل إدخال واحد في القائمة هو 4 بايت قبل الضغط.

لتعديل قوائم "التصفّح الآمن" في قاعدة البيانات المحلية، أرسِل طلب HTTP POST إلى threatListUpdates.fetch :

• يتضمن طلب HTTP POST أسماء القوائم التي سيتم تعديلها مع برامج مختلفة. لمراعاة قيود الذاكرة والنطاق الترددي.
• تعرض استجابة HTTP POST إما تعديلاً كاملاً أو تعديلاً جزئيًا. الردّ قد يعرض أيضًا الحد الأدنى لمدة الانتظار.

مثال: fireListUpdates.fetch

طلب HTTP POST

في المثال التالي، يتم طلب إجراء التعديلات لقائمة واحدة من قوائم "التصفّح الآمن".

عنوان الطلب

يتضمّن عنوان الطلب عنوان URL للطلب ونوع المحتوى. تذكَّر استبدال مفتاح واجهة برمجة التطبيقات API_KEY في عنوان URL.

POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1
Content-Type: application/json

نص الطلب

يتضمّن نص الطلب معلومات العميل (رقم التعريف والإصدار) ومعلومات التعديل (اسم العميل وحالة القائمة والقيود المفروضة على العميل). لمزيد من التفاصيل، يُرجى مراجعة نص طلب threatListUpdates.fetch والتفسيرات التي تتبع مثال التعليمة البرمجية.

{
  "client": {
    "clientId":       "yourcompanyname",
    "clientVersion":  "1.5.2"
  },
  "listUpdateRequests": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "state":           "Gg4IBBADIgYQgBAiAQEoAQ==",
    "constraints": {
      "maxUpdateEntries":      2048,
      "maxDatabaseEntries":    4096,
      "region":                "US",
      "supportedCompressions": ["RAW"]
    }
  }]
}

معلومات العميل

يجب أن يحدّد الحقلان clientID وclientVersion عملية تنفيذ العميل بشكل فريد، وليس مستخدم فردي. (يتم استخدام معلومات العميل في التسجيل من جهة الخادم. يمكنك اختيار أي اسم لمعرّف العميل، ولكن ننصحك باختيار اسم يمثّل الهوية الحقيقية للعميل، مثل اسم شركتك، والذي يتم تقديمه ككلمة واحدة بأحرف أبجدية صغيرة فقط.)

قوائم التصفّح الآمن

الحقول threatType وplatformType وthreatEntryType لتحديد (اسم) قوائم التصفح الآمن. في المثال، تم تحديد قائمة واحدة: MALWARE/WINDOWS/URL. قبل إرسال طلب، تأكَّد من أنّ مجموعات الأنواع التي تحدّدها صالحة (يُرجى الاطّلاع على قوائم التصفّح الآمن).

حالة العميل

يعرض الحقل state حالة العميل الحالية لقائمة "التصفح الآمن". (يتم عرض حالات العميل في حقل newClientState من استجابة threatListUpdates.fetch.) بالنسبة إلى التعديلات الأولية، اترك الحقل state فارغًا.

قيود الحجم

ويحدِّد الحقل maxUpdateEntries إجمالي عدد التحديثات التي يمكن للعميل إدارتها (ضمن على سبيل المثال، 2048). يحدد الحقل maxDatabaseEntries إجمالي عدد الإدخالات المحلية التي يمكن لقاعدة البيانات إدارتها (في المثال، 4096). يجب على العملاء تعيين قيود الحجم لحماية القيود المفروضة على الذاكرة والنطاق الترددي، وللوقاية من عرض البيانات النمو. لمزيد من المعلومات (يُرجى الاطّلاع على قيود التعديل).

طرق الضغط المتوافقة

يسرد الحقل supportedCompressions أنواع الضغط التي يتيحها العميل. في جلسة المعمل، على سبيل المثال، لا يدعم العميل سوى البيانات الأولية غير المضغوطة. إلا أن التصفح الآمن يتيح استخدام أنواع الضغط (راجع الضغط).

استجابة HTTP POST

في هذا المثال، تعرض الاستجابة تعديلاً جزئيًا لقائمة "التصفّح الآمن" باستخدام نوع الضغط الذي تمّ طلبه.

عنوان الاستجابة

يتضمّن عنوان الاستجابة رمز حالة HTTP. ونوع المحتوى. يجب على العملاء الذين يتلقون رمز حالة بخلاف HTTP/200 الدخول في وضع التراجع (راجِع معدل تكرار الطلب).

HTTP/1.1 200 OK
Content-Type: application/json

نص الاستجابة

يتضمن نص الاستجابة معلومات التحديث (مثل اسم القائمة ونوع الاستجابة إضافات وعمليات الإزالة لتطبيقها على قاعدة البيانات المحلية، فسيعمل العميل الجديد والحالة والمجموع الاختباري). في المثال، يتضمّن الردّ أيضًا الحدّ الأدنى لمدة الانتظار. لمزيد من المعلومات، التفاصيل، راجع نص استجابة threatListUpdates.fetch والتفسيرات التي تتبع مثال التعليمة البرمجية.

{
  "listUpdateResponses": [{
    "threatType":      "MALWARE",
    "threatEntryType": "URL",
    "platformType":    "WINDOWS",
    "responseType" :   "PARTIAL_UPDATE",
    "additions": [{
      "compressionType": "RAW",
      "rawHashes": {
        "prefixSize": 4,
        "rawHashes":  "rnGLoQ=="
      }
    }],
    "removals": [{
      "compressionType": "RAW",
      "rawIndices": {
        "indices": [0, 2, 4]
      }
    }],
    "newClientState": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
    "checksum": {
      "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
    }
  }],
  "minimumWaitDuration": "593.440s"
}

تحديثات قاعدة البيانات

سيشير الحقل responseType إلى تحديث جزئي أو كامل. في المثال، يتم عرض تعديل جزئي ، لذا يتضمّن الردّ كلّ من الإضافات والعمليات التي تمّت إزالتها. قد تكون هناك مجموعات متعددة من ولكن مجموعة واحدة فقط من عمليات الإزالة (يُرجى الاطّلاع على تحديثات قاعدة البيانات).

حالة العميل الجديد

يحتوي الحقل newClientState على حالة العميل الجديدة لقائمة "التصفّح الآمن" التي تم تعديلها مؤخرًا. على العملاء حفظ حالة العميل الجديدة لطلبات التعديل اللاحقة (حقل state في طلب threatListUpdates.fetch أو حقل clientStates في طلب fullHashes.find).

المجاميع الاختبارية

يتيح المجموع الاختباري للعملاء التحقّق من أنّ قاعدة البيانات المحلية لم تتعرّض لأي تلف. إذا لم يتطابق فحص صحة ، على العميل محو قاعدة البيانات وإعادة إصدار تحديث بحقل state فارغ. ومع ذلك، يجب أن يتّبع العملاء في هذه الحالة الفترات الزمنية المحدّدة للتعديلات (راجِع وتيرة الطلبات).

الحد الأدنى لفترات الانتظار

يشير الحقل minimumWaitDuration إلى أنّه يجب أن ينتظر العميل مدة 593.44 ثانية (9.89 دقيقة). قبل إرسال طلب تحديث آخر. يُرجى العِلم أنّه قد يتم تضمين فترة انتظار في ردّ أو قد لا يتم تضمينها (راجِع وتيرة الطلبات).

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

للتحقّق مما إذا كان عنوان URL مُدرَجًا في قائمة "التصفّح الآمن"، على العميل أولاً احتساب التجزئة والتجزئة. بادئة عنوان URL (راجِع عناوين URL والتجزئة). العميل ثم الاستعلامات في قاعدة البيانات المحلية لتحديد ما إذا كان هناك تطابق. إذا كانت بادئة التجزئة هي غير موجود في قاعدة البيانات المحلية، عندها سيتم اعتبار عنوان URL آمنًا (وليس على قاعدة البيانات قوائم التصفُّح).

إذا كانت بادئة التجزئة متوفّرة في قاعدة البيانات المحلية (تعارض بادئة التجزئة)، على العميل إرسال بادئة التجزئة إلى خوادم "التصفّح الآمن" للتحقّق منها. ستعرض الخوادم جميع تجزئات SHA 256 الكاملة التي تحتوي على بادئة التجزئة المحددة. إذا تطابقت إحدى هذه التجزئات الكاملة مع التجزئة الكاملة لعنوان URL المعني، سيتم اعتبار عنوان URL غير آمن. في حال عدم تطابق أي من التجزئات الكاملة مع قيمة التجزئة الكاملة عن عنوان URL المعنيّ، فيُعتبَر ذلك العنوان آمنًا.

لا تتعرّف Google على عناوين URL التي تفحصها في أي وقت. يتعرّف محرّك بحث Google على بادئات التجزئة لعناوين URL، ولكنّ بادئات التجزئة لا تقدّم الكثير من المعلومات عن عناوين URL الفعلية.

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

• يمكن أن يتضمن طلب HTTP POST ما يصل إلى 500 إدخال تهديد.
• يتضمّن طلب HTTP POST بادئات التجزئة لعناوين URL المطلوب التحقّق منها. العملاء هم وشجعنا على تجميع إدخالات تهديد متعددة في طلب واحد لخفض استخدام معدل نقل البيانات.
• تعرض استجابة HTTP POST التجزئات المطابقة بالطول الكامل بالإضافة إلى مدّتَي ذاكرة التخزين المؤقت الإيجابية والسلبية. قد يعرض الردّ أيضًا حدًّا أدنى لمدة الانتظار.

مثال: FullHashes.find

طلب HTTP POST

في المثال التالي، يتم إرسال أسماء قائمتَي "التصفّح الآمن" وثلاث بادئات للتشفير للمقارنة والتحقّق.

عنوان الطلب

يتضمّن عنوان الطلب عنوان URL للطلب ونوع المحتوى. تذكَّر استبدال مفتاح واجهة برمجة التطبيقات بـ API_KEY في عنوان URL.

POST https://safebrowsing.googleapis.com/v4/fullHashes:find?key=API_KEY HTTP/1.1
Content-Type: application/json

نص الطلب

يتضمن نص الطلب معلومات العميل (رقم التعريف والإصدار) وحالات العميل معلومات التهديد (أسماء القوائم وبادئات التجزئة). بالنسبة إلى طلبات JSON، يجب إرسال بادئات التجزئة بترميز base64. لمزيد من التفاصيل، يُرجى الاطّلاع على body request fullHashes.find والتفسيرات التي تتبع مثال الرمز البرمجي.

{
  "client": {
    "clientId":      "yourcompanyname",
    "clientVersion": "1.5.2"
  },
  "clientStates": [
    "ChAIARABGAEiAzAwMSiAEDABEAE=",
    "ChAIAhABGAEiAzAwMSiAEDABEOgH"
  ],
  "threatInfo": {
    "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
    "platformTypes":    ["WINDOWS"],
    "threatEntryTypes": ["URL"],
    "threatEntries": [
      {"hash": "WwuJdQ=="},
      {"hash": "771MOg=="},
      {"hash": "5eOrwQ=="}
    ]
  }
}

معلومات العميل

يجب أن يحدّد الحقلان clientID وclientVersion عملية تنفيذ العميل بشكل فريد، وليس مستخدم فردي. (يتم استخدام معلومات العميل في التسجيل من جهة الخادم. يمكنك اختيار أي اسم معرِّف العميل، ولكننا نقترح عليك اختيار اسم يمثل الهوية الحقيقية للعميل، مثل اسم شركتك، ويجب أن تكون مكونة من كلمة واحدة وبأحرف لاتينية صغيرة فقط).

جميع حالات العميل

يحتوي الحقل clientStates على حالات العميل في جميع قوائم "التصفح الآمن" في قاعدة بيانات العميل المحلية. (يتم عرض حالات العميل في حقل newClientState من استجابة threatListUpdates.fetch.)

قوائم التصفّح الآمن

يتم دمج الحقول threatTypes وplatformTypes وthreatEntryTypes لتحديد (اسم) قوائم "التصفّح الآمن". في المثال، تم تحديد قائمتين: MALWARE/WINDOWS/URL SOCIAL_ENGINEERING/WINDOWS/عنوان URL. قبل إرسال طلب، تأكَّد من أنّ مجموعات الأنواع التي تحدّدها صالحة (راجِع قوائم التصفّح الآمن).

بادئات تجزئة التهديدات

تحتوي مصفوفة SpamEntries على بادئات التجزئة الخاصة بعناوين URL التي تريد التحقّق منها. يجب أن يحتوي الحقل hash على بادئة التجزئة نفسها المتوفّرة في قاعدة البيانات المحلية. بالنسبة على سبيل المثال، إذا كان طول بادئة التجزئة المحلية 4 بايت، يجب أن يبلغ طول إدخال التهديد 4 بايت. إذا كانت تم إطالة بادئة التجزئة المحلية إلى 7 بايت، ثم يجب أن يبلغ طول إدخال التهديد 7 بايت.

في المثال، يتضمّن الطلب ثلاث بادئات علامات هاشتاغ. ستتم مقارنة البادئات الثلاث جميعها مقابل كل قائمة من قوائم "التصفح الآمن" لتحديد ما إذا كانت هناك تجزئة مطابقة كاملة الطول.

ملاحظة: يجب أن تستخدم Update API وطريقة fullHashes.find دائمًا الحقل hash، وليس الحقل URL مطلقًا (راجِع ThreatEntry).

استجابة HTTP POST

في المثال التالي، تعرض الاستجابة البيانات المطابقة، مرتبة حسب قائمة التصفح الآمن، إلى جانب ذاكرة التخزين المؤقت وفترات الانتظار.

عنوان الاستجابة

يتضمّن عنوان الاستجابة رمز حالة HTTP ونوع المحتوى. يجب على العملاء الذين يتلقون رمز حالة بخلاف HTTP/200 التراجع (راجع معدل تكرار الطلب).

HTTP/1.1 200 OK
Content-Type: application/json

نص الاستجابة

يتضمن نص الاستجابة معلومات المطابقة (أسماء القوائم وتجزئات الطول الكامل، وبيانات التعريف، إن وجدت، ومدد ذاكرة التخزين المؤقت). في المثال، يتضمّن نص الاستجابة أيضًا الحد الأدنى لمدة الانتظار. لمزيد من التفاصيل، يُرجى مراجعة نص الاستجابةfullHashes.find والتفسيرات التي تتبع مثال التعليمة البرمجية.

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4="
    },
    "threatEntryMetadata": {
      "entries": [{
        "key": "bWFsd2FyZV90aHJlYXRfdHlwZQ==",  // base64-encoded "malware_threat_type"
        "value": "TEFORElORw=="  // base64-encoded "LANDING"
       }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "SOCIAL_ENGINEERING",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "771MOrRPMn6xPKlCrXx_CrR-wmCk0LgFFoSgGy7zUiA="
    },
    "threatEntryMetadata": {
      "entries": []
    },
    "cacheDuration": "300.000s"
  }],
  "minimumWaitDuration": "300.000s",
  "negativeCacheDuration": "300.000s"
}

المطابقات

يعرض الكائن التطابقات تجزئة كاملة مطابِقة لاثنتين من بادئات التجزئة. عناوين URL المقابلة لهذه التجزئات تعتبر غير آمنة. لم يتم العثور على تطابق لبادئة التجزئة الثالثة، لذلك لا يتم إرجاع أي شيء؛ يُعتبر عنوان URL المقابل لبادئة التجزئة هذه آمنًا.

يُرجى العِلم أنّ هذا المثال يطابق تجزئة واحدة كاملة مع بادئة تجزئة واحدة، ولكن قد يكون هناك تجزئات كاملة متعددة يتم ربطها ببادئة التجزئة نفسها.

البيانات الوصفية

حقل threatEntryMetadata اختياري ويقدّم معلومات إضافية عن مطابقة التهديد. في الوقت الحالي، تتوفر البيانات الوصفية لقائمة "التصفح الآمن" لبرامج MALWARE/WINDOWS/URL (راجع البيانات الوصفية).

مدد ذاكرة التخزين المؤقت

يشير الحقلان cacheDuration وnegativeCacheDuration إلى المدّة التي يجب فيها اعتبار التجزئات إما غير آمنة أو آمنة (راجِع التخزين المؤقت).

الحد الأدنى لفترات الانتظار

يشير الحقل minimumWaitDuration إلى أنّه على العميل الانتظار لمدة 300 ثانية (5 دقائق) قبل أن إرسال طلب كامل آخر. يُرجى العِلم أنّه قد يتم أو لا يشمل الردّ فترة انتظار. (راجِع معدل تكرار الطلب).