Safe Browsing Lookup API (v4)

نمای کلی

Lookup API به برنامه های کاربردی سرویس گیرنده شما اجازه می دهد تا درخواست هایی را به سرورهای مرور ایمن ارسال کنند تا بررسی کنند آیا URL ها در لیست های مرور ایمن گنجانده شده اند یا خیر. اگر یک URL در یک یا چند لیست یافت شود، اطلاعات منطبق برگردانده می شود.

بررسی URL ها

برای بررسی اینکه آیا یک URL در لیست مرور ایمن قرار دارد یا خیر، یک درخواست HTTP POST را به روش gefMatches.find ارسال کنید:

• درخواست HTTP POST می تواند تا 500 URL را شامل شود. URL ها باید معتبر باشند (به RFC 2396 مراجعه کنید) اما نیازی به متعارف سازی یا کدگذاری ندارند.
• پاسخ HTTP POST URL های منطبق را به همراه مدت زمان کش برمی گرداند.

مثال: gefMatches.find

درخواست HTTP POST

در مثال زیر، دو لیست Safe Browsing و سه URL به سرور ارسال می‌شوند تا مشخص شود که آیا مطابقت دارد یا خیر.

هدر درخواست

هدر درخواست شامل URL درخواست و نوع محتوا است. به یاد داشته باشید که کلید API خود را با API_KEY در URL جایگزین کنید.

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

درخواست بدن

بدنه درخواست شامل اطلاعات مشتری (شناسه و نسخه) و اطلاعات تهدید (نام لیست و آدرس‌های اینترنتی) است. برای جزئیات بیشتر، به بدنه درخواست gefMatches.find و توضیحاتی که از نمونه کد پیروی می کند، مراجعه کنید.

  {
    "client": {
      "clientId":      "yourcompanyname",
      "clientVersion": "1.5.2"
    },
    "threatInfo": {
      "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
      "platformTypes":    ["WINDOWS"],
      "threatEntryTypes": ["URL"],
      "threatEntries": [
        {"url": "http://www.urltocheck1.org/"},
        {"url": "http://www.urltocheck2.org/"},
        {"url": "http://www.urltocheck3.com/"}
      ]
    }
  }

اطلاعات مشتری

فیلدهای clientID و clientVersion باید به طور منحصربه‌فرد پیاده‌سازی مشتری را شناسایی کنند، نه یک کاربر منفرد. (اطلاعات مشتری برای ثبت و حسابداری سمت سرور استفاده می شود. شما می توانید هر نامی را برای شناسه مشتری انتخاب کنید، اما پیشنهاد می کنیم نامی را انتخاب کنید که نشان دهنده هویت واقعی مشتری باشد، مانند نام شرکت شما، که همه یک کلمه ارائه می شود. ، با حروف کوچک.)

لیست های مرور ایمن

فیلدهای threatType ، platformType ، و threatEntryType برای شناسایی (نام) لیست های مرور ایمن ترکیب می شوند. در مثال، دو لیست شناسایی می شوند: MALWARE/WINDOWS/URL و SOCIAL_ENGINEERING/WINDOWS/URL. قبل از ارسال درخواست، مطمئن شوید که ترکیب‌های نوع مشخصی معتبر هستند (به فهرست‌های مرور ایمن مراجعه کنید).

URL های تهدید

در مثال، آرایه threatEntries شامل سه URL (urltocheck1.org، urltocheck2.org و urltocheck3.org) است که در مقابل دو لیست Safe Browsing بررسی خواهند شد.

توجه: API Lookup و متد threatMatches همیشه باید از فیلد URL استفاده کنند، نه از فیلد hash (به ThreatEntry مراجعه کنید).

پاسخ HTTP POST

در مثال زیر، پاسخ مطابقت را برمی‌گرداند. دو تا از سه URL مشخص شده در درخواست در یکی از دو فهرست مرور ایمن مشخص شده در درخواست یافت می شوند.

سربرگ پاسخ

هدر پاسخ شامل کد وضعیت HTTP و نوع محتوا است.

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

بدن پاسخگو

بدنه پاسخ شامل اطلاعات تطابق (نام لیست و نشانی‌های اینترنتی موجود در آن فهرست‌ها، ابرداده، در صورت وجود، و مدت زمان حافظه پنهان) است. برای جزئیات بیشتر، به بدنه پاسخ gefMatches.find و توضیحاتی که از نمونه کد پیروی می کند، مراجعه کنید.

توجه: اگر هیچ تطابقی وجود نداشته باشد (یعنی اگر هیچ یک از URL های مشخص شده در درخواست در هیچ یک از لیست های مشخص شده در یک درخواست یافت نشد)، پاسخ HTTP POST به سادگی یک شی خالی در بدنه پاسخ برمی گرداند.

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat":          {"url": "http://www.urltocheck1.org/"},
    "threatEntryMetadata": {
      "entries": [{
        "key": "malware_threat_type",
        "value": "landing"
     }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat":          {"url": "http://www.urltocheck2.org/"},
    "threatEntryMetadata": {
      "entries": [{
        "key":   "malware_threat_type",
        "value": "landing"
     }]
    },
    "cacheDuration": "300.000s"
  }]
}

مسابقات

شیء matches نام فهرست‌های مرور ایمن و نشانی‌های اینترنتی را فهرست می‌کند - در صورت وجود مطابقت. در مثال، دو URL (urltocheck1.org و urltocheck2.org) در یکی از فهرست‌های مرور ایمن (MALWARE/WINDOWS/URL) یافت شد، بنابراین اطلاعات منطبق برگردانده می‌شوند. URL سوم (urltocheck3.org) در هیچ یک از لیست ها یافت نشد، بنابراین هیچ اطلاعاتی برای این URL بازگردانده نمی شود.

فراداده

قسمت threatEntryMetadata اختیاری است و اطلاعات بیشتری در مورد تطابق تهدید ارائه می دهد. در حال حاضر، ابرداده برای فهرست مرور ایمن MALWARE/WINDOWS/URL در دسترس است (به فراداده مراجعه کنید).

مدت زمان کش

فیلد cacheDuration مدت زمانی را نشان می دهد که URL باید ناامن در نظر گرفته شود (به ذخیره سازی مراجعه کنید).