Method: hashes.search

البحث عن علامات تجزئة كاملة تطابق البادئات المحدّدة

هذه طريقة مخصّصة وفقًا لتعريف https://google.aip.dev/136 (تشير الطريقة المخصّصة إلى أنّ لهذه الطريقة اسم مخصّص ضمن التسمية العامة لتطوير واجهة برمجة التطبيقات من Google، ولا تشير إلى استخدام طريقة HTTP مخصّصة).

طلب HTTP

GET https://safebrowsing.googleapis.com/v5/hashes:search

يستخدِم عنوان URL بنية تحويل ترميز gRPC.

معامِلات طلب البحث

المعلمات
hashPrefixes[]

string (bytes format)

مطلوب. بادئات التجزئة المطلوب البحث عنها. يجب ألا يرسل العملاء أكثر من 1,000 بادئة تجزئة. ومع ذلك، ووفقًا لإجراء معالجة عناوين URL، "ينبغي ألا يحتاج العملاء إلى إرسال أكثر من 30 بادئة تجزئة.

في الوقت الحالي، يجب أن يكون طول كل بادئة تجزئة 4 بايت بالضبط. وقد يكون هذا مريحًا في المستقبل.

سلسلة بترميز base64.

نص الطلب

يجب أن يكون نص الطلب فارغًا.

نص الاستجابة

ظهرت الاستجابة بعد البحث في تجزئات التهديد.

إذا لم يتم العثور على أي شيء، سيعرض الخادم حالة "صالح" (رمز حالة HTTP 200) مع ترك الحقل fullHashes فارغًا، بدلاً من عرض حالة NOT_FOUND (رمز حالة HTTP 404).

الجديد في V5: هناك فصل بين FullHash وFullHashDetail. في حال تمثيل التجزئة لموقع إلكتروني يواجه تهديدات متعددة (على سبيل المثال، MALWARE وSOCIAL_ENGINEERING)، ليس من الضروري إرسال التجزئة الكاملة مرتين كما في الإصدار 4. بالإضافة إلى ذلك، تم تبسيط مدة ذاكرة التخزين المؤقت في حقل cacheDuration واحد.

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل JSON
{
  "fullHashes": [
    {
      object (FullHash)
    }
  ],
  "cacheDuration": string
}
الحقول
fullHashes[]

object (FullHash)

قائمة بدون ترتيب. تم العثور على قائمة بدون ترتيب بالتجزئات الكاملة.

cacheDuration

string (Duration format)

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

إذا كان الحقل fullHashes فارغًا فقط، يمكن أن يزيد العميل cacheDuration لتحديد تاريخ انتهاء صلاحية جديد يأتي بعد الفترة المحدَّدة التي حددها الخادم. وفي أي حالة، يجب ألا تزيد مدة ذاكرة التخزين المؤقت الزائدة عن 24 ساعة.

هام: يجب ألا يفترض العميل أن الخادم سيعرض مدة ذاكرة التخزين المؤقت نفسها لجميع الاستجابات. قد يختار الخادم مُدد ذاكرة تخزين مؤقتة مختلفة لاستجابات مختلفة، وذلك وفقًا للموقف.

مدة بالثواني مكونة من تسعة أرقام كسور كحد أقصى وتنتهي بالأرقام "s" مثال: "3.5s"

FullHash

التجزئة الكاملة التي تم تحديدها بتطابق واحد أو أكثر.

تمثيل JSON
{
  "fullHash": string,
  "fullHashDetails": [
    {
      object (FullHashDetail)
    }
  ]
}
الحقول
fullHash

string (bytes format)

التجزئة الكاملة المطابقة هذه هي تجزئة SHA256. يجب أن يكون الطول 32 بايت بالضبط.

سلسلة بترميز base64.

fullHashDetails[]

object (FullHashDetail)

قائمة بدون ترتيب. حقل متكرّر لتحديد التفاصيل ذات الصلة بهذه التجزئة الكاملة

FullHashDetail

تفاصيل حول تجزئة كاملة مطابقة

ملاحظة مُهمّة حول التوافق مع نظام التشغيل: يمكن أن يضيف الخادم أنواع تهديدات جديدة وسمات تهديد جديدة في أي وقت تعتبر هذه الإضافات تغييرات طفيفة في الإصدار. تنص سياسة Google على عدم الكشف عن أرقام إصدارات ثانوية في واجهات برمجة التطبيقات (يُرجى الاطّلاع على https://cloud.google.com/apis/design/versioning للاطّلاع على سياسة تحديد الإصدارات)، لذلك يجب أن يكون العملاء مستعدّين لتلقّي رسائل FullHashDetail التي تحتوي على قيم تعداد ThreatType أو قيم تعداد لـ ThreatAttribute يعتبرها العميل غير صالحة. وبالتالي، تقع على عاتق العميل مسؤولية التحقّق من صلاحية جميع قيم التعداد للسمة ThreatType وThreatAttribute. وإذا تم اعتبار أي قيمة غير صالحة، على العميل تجاهل رسالة FullHashDetail بالكامل.

تمثيل JSON
{
  "threatType": enum (ThreatType),
  "attributes": [
    enum (ThreatAttribute)
  ]
}
الحقول
threatType

enum (ThreatType)

يشير ذلك المصطلح إلى نوع التهديد. لن يكون هذا الحقل فارغًا أبدًا.

attributes[]

enum (ThreatAttribute)

قائمة بدون ترتيب. سمات إضافية عن علامات التجزئة الكاملة هذه قد يكون هذا الحقل فارغًا.

ThreatType

أنواع التهديدات.

عمليات التعداد
THREAT_TYPE_UNSPECIFIED نوع تهديد غير معروف وفي حال عرض الخادم هذه الرسالة، سيتجاهل العميل سياسة FullHashDetail المضمّنة تمامًا.
MALWARE

نوع تهديد البرامج الضارة البرامج الضارّة هي أي تطبيق للأجهزة الجوّالة أو برنامج تم تصميمه خصيصًا لإلحاق الضرر بجهاز الكمبيوتر أو بالجهاز الجوّال أو ببرامج الجهاز أو بمستخدميه. وتُظهِر البرامج الضارة سلوكًا خبيثًا يمكن أن يشمل تثبيت برامج بدون موافقة المستخدم وتثبيت برامج ضارة، مثل الفيروسات.

يمكنك الاطّلاع على مزيد من المعلومات هنا.

SOCIAL_ENGINEERING

نوع تهديد الهندسة الاجتماعية. تدّعي صفحات الهندسة الاجتماعية كذبًا أن تتصرف نيابةً عن طرف ثالث بهدف إرباك المشاهدين وحثّهم على تنفيذ إجراء لا يثق المشاهدون به إلا في وكيل حقيقي لتلك الجهة الخارجية. التصيّد الاحتيالي هو نوع من الهندسة الاجتماعية يخدع المُشاهد لتنفيذ إجراء معيّن وهو تقديم المعلومات، مثل بيانات اعتماد تسجيل الدخول.

يمكنك الاطّلاع على مزيد من المعلومات هنا.

UNWANTED_SOFTWARE نوع تهديد البرامج غير المرغوب فيه البرامج غير المرغوب فيها هي أي برامج لا تلتزم بمبادئ برمجيات Google ولكنها ليست برامج ضارة.
POTENTIALLY_HARMFUL_APPLICATION نوع تهديد من التطبيقات يُحتمَل أن يكون ضارًا كما هو الحال في خدمة "Google Play للحماية" في "متجر Play"

ThreatAttribute

سمات التهديدات. وقد تضيف هذه السمات معنى إضافيًا لتهديد معيّن ولكنها لن تؤثر في نوع التهديد. على سبيل المثال، قد تحدّد إحدى السمات مستوى ثقة أعلى، في حين أنّ سمة مختلفة قد تحدّد مستوى ثقة أعلى. ويمكن إضافة المزيد من السمات في المستقبل.

عمليات التعداد
THREAT_ATTRIBUTE_UNSPECIFIED سمة غير معروفة. وفي حال عرض الخادم هذه الرسالة، سيتجاهل العميل سياسة FullHashDetail المضمّنة تمامًا.
CANARY يشير هذا الرمز إلى وجوب عدم استخدام نوع التهديد لإجراء تنفيذ.
FRAME_ONLY يشير إلى أنّه يجب استخدام نوع التهديد فقط لتنفيذ الإجراء على الإطارات.