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

مثال: errorListUpdates.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 التالية:

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

مثال: newHashes.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 بايت.

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

ملاحظة: يجب دائمًا استخدام الحقل hash في واجهة برمجة التطبيقات Update API والطريقة totalHashes.find، وليست الحقل 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 دقائق) قبل إرسال طلب كامل آخر. يُرجى العِلم بأنّه قد يتم تضمين فترة انتظار في الردّ أو لا يتم تضمينه (راجِع معدل تكرار الطلب).