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

نظرة عامة

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

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

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

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

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

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

مثال: تهديداتListList.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 المعني، سيتم اعتبار عنوان 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. للحصول على مزيد من التفاصيل، يمكنك الاطّلاع على نص الطلب 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. قبل إرسال الطلب، تأكد من صلاحية مجموعات الأنواع التي تحددها (راجع قوائم التصفح الآمن).

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

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

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

ملاحظة: يجب أن تستخدم واجهة برمجة التطبيقات Update والطريقة 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 دقائق) قبل إرسال طلب تجزئة كامل آخر. تجدر الإشارة إلى أنه قد يتم تضمين فترة انتظار في الاستجابة أو لا يتم تضمينها (راجع فترة تكرار الطلب).