الفهرس
SafeBrowsing
(واجهة)Checksum
(رسالة)ClientInfo
(رسالة)CompressionType
(تعداد)FetchThreatListUpdatesRequest
(رسالة)FetchThreatListUpdatesRequest.ListUpdateRequest
(رسالة)FetchThreatListUpdatesRequest.ListUpdateRequest.Constraints
(رسالة)FetchThreatListUpdatesResponse
(رسالة)FetchThreatListUpdatesResponse.ListUpdateResponse
(رسالة)FetchThreatListUpdatesResponse.ListUpdateResponse.ResponseType
(تعداد)FindFullHashesRequest
(رسالة)FindFullHashesResponse
(رسالة)FindThreatMatchesRequest
(رسالة)FindThreatMatchesResponse
(رسالة)ListThreatListsResponse
(رسالة)PlatformType
(تعداد)RawHashes
(رسالة)RawIndices
(رسالة)RiceDeltaEncoding
(رسالة)ThreatEntry
(رسالة)ThreatEntryMetadata
(رسالة)ThreatEntryMetadata.MetadataEntry
(رسالة)ThreatEntrySet
(رسالة)ThreatEntryType
(تعداد)ThreatInfo
(رسالة)ThreatListDescriptor
(رسالة)ThreatMatch
(رسالة)ThreatType
(تعداد)
SafeBrowsing
تتيح واجهات برمجة التطبيقات للتصفح الآمن للعملاء التحقق من موارد الويب (معظم عناوين URL الشائعة) بمقارنتها بقوائم موارد الويب غير الآمنة التي تُحدِّثها Google باستمرار. تتميز واجهات برمجة التطبيقات للتصفح الآمن (الإصدار 4) بواجهة برمجة التطبيقات للتحديث وواجهة برمجة تطبيقات Lookup.
تم تصميم واجهة برمجة التطبيقات Update API لعملائنا الكبار وتتضمن طريقتي FindFullHashes وFetchThreatListUpdates . تتطلّب واجهة برمجة التطبيقات Update API من العملاء الاحتفاظ بقوائم تهديدات تم تنزيلها في قاعدة بيانات محلية.
أولاً، يتطابق العملاء مع قوائمهم المحلية لتحديد حالة مورد الويب المعيّن (آمن أو غير آمن). تتألف القوائم غالبًا من بادئات تجزئة من تعبيرات عناوين URL المدرجة في القائمة السوداء. للتحقق من عنوان URL، ينشئ العملاء تجزئات لعنوان URL معين ويتحققون من تضاربات البادئات في القوائم المحلية؛ إذا تم العثور على بادئة مطابقة، يحصل العميل على التجزئات الكاملة المرتبطة ببادئة التجزئة المطابقة عبر طريقة FindFullHashes . يقارن العميل بعد ذلك التجزئة الكاملة المحلية بالتجزئات الكاملة المعروضة؛ وتشير المطابقة إلى أن عنوان URL غير آمن.
ثانيًا، يحصل العملاء على تحديثات لقواعد البيانات المحلية باستخدام طريقة FetchThreatListUpdates، والتي تأخذ الحالة الراهنة للعميل وتُرجع حالة العميل المُعدَّلة إلى جانب التغييرات التي على العميل تطبيقها على قوائم التهديدات المحلية.
تم تصميم واجهة برمجة التطبيقات Lookup API لعملاءنا الأصغر حجمًا، كما تسمح لهم بمطابقة الموارد مباشرةً مع قوائم تهديد "التصفُّح الآمن" باستخدام طريقة FindThreatMatch.
يمكن للعملاء الذين يستخدمون واجهة برمجة التطبيقات Update API أو واجهة برمجة تطبيقات Lookup API الحصول على قائمة بقوائم تهديدات "التصفح الآمن" المتاحة للتنزيل من خلال طريقة ListThreatLists.
{-- TRUSTED_THREAT_REPORTER: يمكن لعملاء التهديدات الموثوق بهم إرسال تقارير إلى Google لتحليلها باستخدام طريقة SendThreatReport. --}
FetchThreatListUpdates |
---|
يجلب آخر تعديلات قائمة التهديدات. يمكن للعميل طلب تحديثات لقوائم متعددة في آنٍ واحد. |
FindFullHashes |
---|
للبحث عن التجزئات الكاملة التي تطابق بادئات التجزئة المطلوبة. |
FindThreatMatches |
---|
للبحث عن إدخالات التهديد التي تتطابق مع قوائم "التصفُّح الآمن". |
ListThreatLists |
---|
يسرد قوائم تهديدات "التصفح الآمن" المتاحة للتنزيل. |
المجموع الاختباري
الحالة المتوقعة لقاعدة البيانات المحلية للعميل.
الحقول | |
---|---|
sha256 |
تجزئة SHA256 لحالة العميل؛ أي من القائمة المصنفة لجميع التجزئات الموجودة في قاعدة البيانات. |
ClientInfo
البيانات الوصفية للعميل المرتبطة بطلبات واجهة برمجة التطبيقات للتصفح الآمن
الحقول | |
---|---|
client_id |
معرّف عميل (نأمل) يعرّف بشكل فريد تنفيذ العميل لواجهة برمجة تطبيقات التصفح الآمن. |
client_version |
إصدار تنفيذ العميل. |
CompressionType
الطرق التي يمكن من خلالها ضغط مجموعات إدخال التهديد.
عمليات التعداد | |
---|---|
COMPRESSION_TYPE_UNSPECIFIED |
غير معروف. |
RAW |
البيانات الأولية وغير المضغوطة. |
RICE |
بيانات مرمّزة من نوع Rice-Golomb |
FetchThreatListUpdatesRequest
يصِف طلب تحديث واجهة برمجة التطبيقات للتصفح الآمن. يمكن للعملاء طلب تحديثات لقوائم متعددة في طلب واحد. قد لا يستجيب الخادم لجميع الطلبات في حال لم تتوفر لدى الخادم أي تحديثات لهذه القائمة. ملاحظة: فهرس الحقل 2 غير مستخدم. التالي: 5
الحقول | |
---|---|
client |
البيانات الوصفية للعميل |
list_update_requests[] |
تم تعديل قائمة التهديدات المطلوبة. |
ListUpdateRequest
طلب تعديل قائمة واحدة
الحقول | |
---|---|
threat_type |
تشير هذه السمة إلى نوع التهديد الذي تمثله الإدخالات المدرَجة في القائمة. |
platform_type |
تشير هذه السمة إلى نوع المنصة المعرّضة للخطر من خلال الإدخالات المدرَجة في القائمة. |
threat_entry_type |
تمثّل هذه السمة أنواع الإدخالات المتاحة في القائمة. |
state |
الحالة الحالية للعميل للقائمة المطلوبة (حالة العميل المشفرة التي تم تلقّيها من آخر تحديث ناجح للقائمة). |
constraints |
القيود المرتبطة بهذا الطلب. |
القيود
القيود المفروضة على هذا التعديل
الحقول | |
---|---|
max_update_entries |
الحد الأقصى للحجم في عدد الإدخالات. لن يتضمّن التعديل إدخالات أكثر من هذه القيمة. يجب أن تكون هذه الأُس تساوي 2 بين 2**10 و2**20. إذا كانت القيمة صفرًا، لن يتم ضبط حدّ أقصى لحجم التحديث. |
max_database_entries |
لضبط الحد الأقصى لعدد الإدخالات التي يرغب العميل في الحصول عليها في قاعدة البيانات المحلية للقائمة المحددة. يجب أن تكون هذه الأُس تساوي 2 بين 2**10 و2**20. إذا كانت القيمة صفرًا، لن يتم ضبط حدّ أقصى لحجم قاعدة البيانات. |
region |
يطلب القائمة لموقع جغرافي معين. وفي حال تم ترك السياسة بدون ضبط، قد يختار الخادم تلك القيمة استنادًا إلى عنوان IP للمستخدم. من المتوقع استخدام تنسيق ISO 3166-1 alpha-2. |
supported_compressions[] |
أنواع الضغط المتوافقة مع البرنامج. |
language |
طلب القوائم للغة معينة. يُتوقع استخدام تنسيق ISO 639 alpha-2. |
device_location |
الموقع الجغرافي الفعلي للعميل، ويتم التعبير عنه برمز المنطقة ISO 31166-1 alpha-2. |
FetchThreatListUpdatesResponse
الحقول | |
---|---|
list_update_responses[] |
تعديلات القائمة التي طلبها العملاء. قد يكون عدد الردود هنا أقل من عدد الطلبات التي أرسلها العملاء. ويحدث ذلك، على سبيل المثال، إذا لم يحصل الخادم على أي تحديثات لقائمة معيّنة. |
minimum_wait_duration |
الحدّ الأدنى للمدة التي يجب أن ينتظرها العميل قبل إصدار أي طلب تعديل. في حال عدم ضبط هذا الحقل، يمكن أن يتم تعديل العملاء في حال أرادوا ذلك. |
ListUpdateResponse
تعديل على قائمة فردية
الحقول | |
---|---|
threat_type |
نوع التهديد الذي يتم عرض البيانات له. |
threat_entry_type |
تنسيق التهديدات |
platform_type |
نوع النظام الأساسي الذي يتم إرجاع البيانات له. |
response_type |
نوع الردّ وقد يشير ذلك إلى أنّ العميل سيطلب اتخاذ إجراء عند تلقّي الردّ. |
additions[] |
مجموعة من الإدخالات لإضافتها إلى قائمة نوع تهديد محلي. يتم تكرار هذه الطريقة للسماح بإرسال مجموعة من البيانات المضغوطة والبيانات الأولية في ردّ واحد. |
removals[] |
يشير ذلك المصطلح إلى مجموعة من الإدخالات المطلوب إزالتها من قائمة نوع تهديد محلي. من الناحية العملية، يكون هذا الحقل فارغًا أو يحتوي على ThreatEntrySet واحد فقط. |
new_client_state |
حالة العميل الجديدة، بتنسيق مشفّر. عدم شفافية للعملاء. |
checksum |
تجزئة SHA256 المتوقعة لحالة العميل، أي من القائمة المرتبة لجميع التجزئات الموجودة في قاعدة البيانات بعد تطبيق التحديث المقدم. إذا لم تتطابق حالة العميل مع الحالة المتوقَّعة، على العميل تجاهل هذا التعديل وإعادة المحاولة لاحقًا. |
ResponseType
نوع الردّ المُرسَل إلى العميل
عمليات التعداد | |
---|---|
RESPONSE_TYPE_UNSPECIFIED |
غير معروف. |
PARTIAL_UPDATE |
ويتم تطبيق التحديثات الجزئية على قاعدة البيانات المحلية الحالية للعميل. |
FULL_UPDATE |
تحل التحديثات الكاملة محل قاعدة البيانات المحلية بالكامل للعميل. وهذا يعني أنّ العميل كان قديمًا أو يعتقد أنّه تالف. |
FindFullHashesRequest
طلب عرض تجزئات كاملة متطابقة مع بادئات التجزئة المقدّمة.
الحقول | |
---|---|
client |
البيانات الوصفية للعميل |
client_states[] |
حالات العميل الحالي لكل قائمة من قوائم التهديدات المحلية للعميل |
threat_info |
القوائم والتجزئات المطلوب التحقّق منها. |
api_client |
البيانات الوصفية للعميل المرتبطة بمقدِّمي واجهات برمجة التطبيقات ذات المستوى الأعلى والمستندة إلى عملية تنفيذ العميل |
FindFullHashesResponse
الحقول | |
---|---|
matches[] |
التجزئات الكاملة التي تطابقت مع البادئات المطلوبة. |
minimum_wait_duration |
الحدّ الأدنى للمدة التي يجب أن ينتظرها العميل قبل إصدار أي طلب للبحث عن علامات تجزئة. في حال عدم ضبط هذا الحقل، يمكن للعملاء إصدار طلب بالسرعة التي يريدونها. |
negative_cache_duration |
بالنسبة إلى الكيانات المطلوبة التي لا تتطابق مع قائمة التهديدات، يتم تحديد مدة التخزين المؤقت للاستجابة. |
FindThreatMatchesRequest
طلب التحقق من الإدخالات مقارنةً بالقوائم.
الحقول | |
---|---|
client |
البيانات الوصفية للعميل |
threat_info |
القوائم والإدخالات المطلوب التحقّق منها بحثًا عن حالات مطابقة. |
FindThreatMatchesResponse
الحقول | |
---|---|
matches[] |
تتطابق قائمة التهديدات. |
ListThreatListsResponse
الحقول | |
---|---|
threat_lists[] |
القوائم المتاحة للتنزيل من قِبل العميل. |
PlatformType
أنواع المنصات.
عمليات التعداد | |
---|---|
PLATFORM_TYPE_UNSPECIFIED |
منصة غير معروفة. |
WINDOWS |
يمثل هذا التهديد لنظام Windows. |
LINUX |
التهديد الناتج عن Linux. |
ANDROID |
تمثّل هذه السمة التهديد الناتج عن Android. |
OSX |
هناك تهديد على نظام التشغيل OS X. |
IOS |
يمثل التهديد لنظام iOS. |
ANY_PLATFORM |
تمثّل هذه السمة تهديدًا على منصة واحدة على الأقل من المنصات المحدّدة. |
ALL_PLATFORMS |
تمثّل هذه السمة التهديد الناتج عن جميع المنصات المحدّدة. |
CHROME |
تمثّل هذه السمة التهديد الناتج عن Chrome. |
RawHashes
إدخالات التهديد غير المضغوطة بتنسيق تجزئة بطول بادئة معيّنة. يمكن أن يتراوح حجم علامات التجزئة بين 4 و32 بايت. وتبلغ معظم علامات التجزئة 4 بايت، ولكن تطول بعض علامات التجزئة إذا اصطدمت بتجزئة عنوان URL شائع.
يُستخدم لإرسال ThreatEntrySet إلى برامج لا تتيح الضغط، أو عند إرسال تجزئات غير 4 بايت إلى البرامج التي تعتمد الضغط.
الحقول | |
---|---|
prefix_size |
عدد وحدات البايت لكل بادئة تم ترميزها أدناه. يمكن أن يتراوح هذا الحقل بين 4 (أقصر بادئة) و32 (تجزئة SHA256 كاملة). |
raw_hashes |
يتم دمج علامات التجزئة في تنسيق ثنائي في سلسلة واحدة طويلة. يتم فرز التجزئات بترتيب قاموسي. وبالنسبة إلى مستخدمي JSON API، تكون قيم التجزئة بترميز base64. |
RawIndices
مجموعة من الفهارس الأولية لإزالتها من قائمة محلية
الحقول | |
---|---|
indices[] |
الفهارس المطلوب إزالتها من قائمة محلية تم ترتيبها بشكل لغوي |
RiceDeltaEncoding
بيانات Rice-Golomb المشفَّرة. يُستخدم لإرسال علامات تجزئة مضغوطة بحجم 4 بايت أو فهارس إزالة مضغوطة.
الحقول | |
---|---|
first_value |
إزاحة الإدخال الأول في البيانات المُشفرة، أو قيمة هذا العدد الصحيح الفردي، إذا تم تشفير عدد صحيح واحد فقط. وإذا كان الحقل فارغًا أو مفقودًا، لنفترض أنّ القيمة صفر. |
rice_parameter |
مَعلمة Golomb-Rice، وهي رقم يتراوح بين 2 و28. هذا الحقل غير متوفّر (أي صفر) إذا كانت قيمة |
num_entries |
عدد الإدخالات التي تم ترميزها دلتا في البيانات المشفرة. إذا تم ترميز عدد صحيح واحد فقط، سيكون هذا العدد صفرًا وسيتم تخزين القيمة المفردة في |
encoded_data |
يشير ذلك المصطلح إلى مجموعات الدلتا المشفرة التي تم ترميزها باستخدام برنامج ترميز Golomb-Rice. |
ThreatEntry
تهديد فردي، مثل عنوان URL ضار أو تمثيل تجزئة خاص به يجب ضبط حقل واحد فقط من هذه الحقول.
الحقول | |
---|---|
hash |
بادئة تجزئة تتكوّن من أهم 4 إلى 32 بايت من تجزئة SHA256. هذا الحقل في تنسيق ثنائي. بالنسبة إلى طلبات JSON، تكون علامات التجزئة بترميز base64. |
url |
عنوان URL: |
digest |
ملخّص لملف قابل للتنفيذ بتنسيق SHA256. تتيح واجهة برمجة التطبيقات استخدام الملخصات الثنائية والست عشرية. بالنسبة إلى طلبات JSON، تكون الملخّصات بترميز base64. |
ThreatEntryMetadata
البيانات الوصفية المرتبطة بإدخال تهديد محدد من المتوقّع أن يعرف العميل أزواج مفتاح/قيم البيانات الوصفية المرتبطة بكل نوع من أنواع التهديد.
الحقول | |
---|---|
entries[] |
إدخالات بيانات التعريف. |
MetadataEntry
إدخال بيانات وصفية واحد.
الحقول | |
---|---|
key |
مفتاح إدخال البيانات الوصفية. بالنسبة إلى طلبات JSON، يكون المفتاح بترميز base64. |
value |
قيمة إدخال البيانات الوصفية. بالنسبة إلى طلبات JSON، تكون القيمة بترميز base64. |
ThreatEntrySet
يشير ذلك المصطلح إلى مجموعة من التهديدات يجب إضافتها أو إزالتها من قاعدة البيانات المحلية للعميل.
الحقول | |
---|---|
compression_type |
نوع الضغط للإدخالات في هذه المجموعة. |
raw_hashes |
تمثّل هذه السمة الإدخالات الأولية بتنسيق SHA256. |
raw_indices |
مؤشرات الإزالة الأولية لقائمة محلية. |
rice_hashes |
البادئات الـ 4 بايت المشفرة للإدخالات بتنسيق SHA256، باستخدام ترميز Golomb-Rice. يتم تحويل التجزئات إلى uint32، ويتم فرزها بترتيب تصاعدي، ثم تشفير دلتا وتخزينها كـ RDFa_data. |
rice_indices |
فهارس قوائم محلية مرمّزة تم ترتيبها بشكل لغوي، وذلك باستخدام ترميز Golomb-Rice يتم استخدام البيانات لإرسال فهارس إزالة مضغوطة. يتم فرز فهارس الإزالة (uint32) بترتيب تصاعدي، ثم تشفير دلتا وتخزينها كـ RDFa_data. |
ThreatEntryType
أنواع الإدخالات التي تشكّل تهديدًا قوائم التهديدات هي مجموعات من الإدخالات من نوع واحد.
عمليات التعداد | |
---|---|
THREAT_ENTRY_TYPE_UNSPECIFIED |
غير محدد |
URL |
عنوان URL: |
EXECUTABLE |
برنامج تنفيذي. |
ThreatInfo
يشير هذا المصطلح إلى المعلومات المتعلّقة بتهديد واحد أو أكثر يرسله العميل عند البحث عن محتوى مطابق في قوائم التهديدات.
الحقول | |
---|---|
threat_types[] |
أنواع التهديدات التي يجب التحقّق منها. |
platform_types[] |
أنواع المنصّات التي يجب التحقّق منها. |
threat_entry_types[] |
أنواع الإدخالات المطلوب التحقّق منها. |
threat_entries[] |
إدخالات التهديد التي سيتم التحقق منها. |
ThreatListDescriptor
يصف قائمة تهديد فردية. يتم تحديد القائمة من خلال ثلاث معلَمات: نوع التهديد المتمثّل، ونوع النظام الأساسي الذي يستهدفه التهديد، ونوع الإدخالات الواردة في القائمة.
الحقول | |
---|---|
threat_type |
نوع التهديد الذي تمثِّله إدخالات القائمة |
platform_type |
نوع النظام الأساسي الذي تستهدفه إدخالات القائمة. |
threat_entry_type |
تمثّل هذه السمة أنواع الإدخالات المضمَّنة في القائمة. |
ThreatMatch
تطابق عند التحقُّق من إدخال تهديد في قوائم تهديد "التصفُّح الآمن".
الحقول | |
---|---|
threat_type |
نوع التهديد الذي يتطابق مع هذا التهديد. |
platform_type |
نوع النظام الأساسي الذي يتطابق مع هذا التهديد. |
threat_entry_type |
نوع إدخال التهديد الذي يطابق هذا التهديد. |
threat |
التهديد الذي يطابق هذا التهديد. |
threat_entry_metadata |
بيانات وصفية اختيارية مرتبطة بهذا التهديد |
cache_duration |
عمر ذاكرة التخزين المؤقت للمطابقة التي تم إرجاعها. يجب ألا يخزّن العملاء هذه الاستجابة في ذاكرة التخزين المؤقت لأكثر من هذه المدة لتجنُّب ظهور نتائج موجبة خاطئة. |
ThreatType
أنواع التهديدات:
عمليات التعداد | |
---|---|
THREAT_TYPE_UNSPECIFIED |
غير معروف. |
MALWARE |
نوع التهديد بالبرامج الضارة |
SOCIAL_ENGINEERING |
نوع تهديد الهندسة الاجتماعية |
UNWANTED_SOFTWARE |
نوع تهديد البرامج غير المرغوب فيه |
POTENTIALLY_HARMFUL_APPLICATION |
نوع تهديد التطبيق الذي قد يتسبّب بضرر |