بررسی اجمالی
به‌روزرسانی API به برنامه‌های مشتری شما امکان می‌دهد نسخه‌های هش‌شده فهرست‌های مرور ایمن را برای ذخیره در یک پایگاه داده محلی دانلود کنند. سپس URL ها را می توان به صورت محلی بررسی کرد. تنها در صورت یافتن یک تطابق در پایگاه داده محلی، مشتری باید درخواستی را به سرورهای مرور ایمن ارسال کند تا بررسی کند که آیا URL در لیست های مرور ایمن گنجانده شده است یا خیر.
قبل از استفاده از Update API، باید یک پایگاه داده محلی راه اندازی کنید. مرور ایمن یک بسته Go را ارائه می دهد که می توانید از آن برای شروع استفاده کنید. برای جزئیات بیشتر، به بخش تنظیم پایگاه داده در پایگاه‌های داده محلی مراجعه کنید.
به روز رسانی پایگاه داده محلی
برای به‌روز ماندن، مشتریان باید به‌طور دوره‌ای فهرست‌های مرور ایمن را در پایگاه داده محلی خود به‌روزرسانی کنند. برای صرفه جویی در پهنای باند، مشتریان پیشوندهای هش URL ها را به جای URL های خام دانلود می کنند. برای مثال، اگر «www.badurl.com/» در فهرست مرور ایمن باشد، مشتریان پیشوند هش SHA256 آن URL را به جای خود URL دانلود می‌کنند. در اکثر موارد، پیشوندهای هش 4 بایت هستند، به این معنی که میانگین هزینه پهنای باند دانلود یک ورودی فهرست، 4 بایت قبل از فشرده سازی است.
برای به‌روزرسانی فهرست‌های مرور ایمن در پایگاه داده محلی، یک درخواست HTTP POST به روش gefListUpdates.fetch ارسال کنید:
- درخواست HTTP
POSTشامل نام لیست هایی است که باید به همراه محدودیت های مختلف کلاینت برای در نظر گرفتن محدودیت های حافظه و پهنای باند به روز شوند. - پاسخ HTTP
POSTیا یک به روز رسانی کامل یا یک به روز رسانی جزئی را برمی گرداند. پاسخ همچنین ممکن است حداقل مدت زمان انتظار را برگرداند.
مثال: gefListUpdates.fetch
درخواست HTTP POST
در مثال زیر، به روز رسانی برای یک لیست مرور ایمن درخواست شده است.
هدر درخواست
هدر درخواست شامل URL درخواست و نوع محتوا است. به یاد داشته باشید که کلید API خود را با API_KEY در URL جایگزین کنید.
POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1 Content-Type: application/json
درخواست بدن
بدنه درخواست شامل اطلاعات مشتری (شناسه و نسخه) و اطلاعات به روز رسانی (نام لیست، وضعیت لیست و محدودیت های مشتری) است. برای جزئیات بیشتر، به بدنه درخواست gefListUpdates.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 برای شناسایی (نام) فهرست‌های Safe Browsing ترکیب می‌شوند. در مثال، یک لیست مشخص شده است: MALWARE/WINDOWS/URL. قبل از ارسال درخواست، مطمئن شوید که ترکیب‌های نوع مشخصی معتبر هستند (به فهرست‌های مرور ایمن مراجعه کنید).
دولت متکی
فیلد state وضعیت فعلی مشتری لیست Safe Browsing را نگه می دارد. (حالت های سرویس گیرنده در قسمت newClientState پاسخ gefListUpdates.fetch برگردانده می شوند.) برای به روز رسانی های اولیه، فیلد state را خالی بگذارید.
محدودیت های اندازه
فیلد maxUpdateEntries تعداد کل به‌روزرسانی‌هایی را که کلاینت می‌تواند مدیریت کند را مشخص می‌کند (در مثال، 2048). فیلد maxDatabaseEntries تعداد کل ورودی هایی را که پایگاه داده محلی می تواند مدیریت کند را مشخص می کند (در مثال، 4096). مشتریان باید محدودیت های اندازه را برای محافظت از محدودیت های حافظه و پهنای باند و برای محافظت در برابر رشد لیست تعیین کنند. برای اطلاعات بیشتر، ( به‌روزرسانی محدودیت‌ها را ببینید).
فشرده سازی های پشتیبانی شده
فیلد supportedCompressions انواع فشرده سازی را که مشتری پشتیبانی می کند فهرست می کند. در مثال، کلاینت فقط از داده های خام و فشرده نشده پشتیبانی می کند. با این حال، مرور ایمن از انواع فشرده سازی اضافی پشتیبانی می کند (به فشرده سازی مراجعه کنید).
پاسخ HTTP POST
در این مثال، پاسخ با استفاده از نوع فشرده‌سازی درخواستی، به‌روزرسانی جزئی را برای فهرست مرور ایمن برمی‌گرداند.
سربرگ پاسخ
هدر پاسخ شامل کد وضعیت HTTP و نوع محتوا است. کلاینت هایی که کد وضعیتی غیر از HTTP/200 دریافت می کنند باید به حالت عقب نشینی وارد شوند ( به درخواست فرکانس مراجعه کنید).
HTTP/1.1 200 OK Content-Type: application/json
بدن پاسخگو
بدنه پاسخ شامل اطلاعات به روز رسانی (نام لیست، نوع پاسخ، اضافات و حذف هایی است که باید در پایگاه داده محلی اعمال شود، وضعیت مشتری جدید، و یک جمع کنترلی). در مثال، پاسخ همچنین شامل حداقل مدت زمان انتظار است. برای جزئیات بیشتر، به بدنه پاسخ gefListUpdates.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 وضعیت سرویس گیرنده جدید را برای لیست تازه به روز شده Safe Browsing نگه می دارد. کلاینت‌ها باید حالت کلاینت جدید را برای درخواست‌های به‌روزرسانی بعدی ذخیره کنند (فیلد state در درخواست gefListUpdates.fetch یا قسمت clientStates در درخواست fullHashes.find ).
جمع های چک
چک‌سام به مشتریان اجازه می‌دهد تا تأیید کنند که پایگاه داده محلی هیچ گونه خرابی نداشته است. اگر جمع چک مطابقت نداشته باشد، کلاینت باید پایگاه داده را پاک کند و یک به روز رسانی را با یک فیلد state خالی دوباره منتشر کند. با این حال، مشتریان در این شرایط همچنان باید فواصل زمانی را برای به روز رسانی دنبال کنند (به درخواست فرکانس مراجعه کنید).
حداقل مدت زمان انتظار
فیلد minimumWaitDuration نشان می دهد که مشتری باید 593.44 ثانیه (9.89 دقیقه) قبل از ارسال درخواست به روز رسانی دیگر صبر کند. توجه داشته باشید که ممکن است یک دوره انتظار در پاسخ گنجانده شود یا نباشد (به دفعات درخواست مراجعه کنید).
بررسی URL ها
برای بررسی اینکه آیا یک URL در فهرست مرور ایمن قرار دارد، مشتری باید ابتدا پیشوند هش و هش URL را محاسبه کند (به URL ها و درهم سازی مراجعه کنید). سپس مشتری از پایگاه داده محلی پرس و جو می کند تا تعیین کند که آیا مطابقت دارد یا خیر. اگر پیشوند هش در پایگاه داده محلی وجود نداشته باشد ، URL امن در نظر گرفته می شود (نه در لیست های مرور ایمن).
اگر پیشوند هش در پایگاه داده محلی وجود داشته باشد (تصادف پیشوند هش)، مشتری باید پیشوند هش را برای تأیید به سرورهای مرور ایمن ارسال کند. سرورها تمام هش های SHA 256 تمام طولی را که حاوی پیشوند هش داده شده هستند را برمی گردانند. اگر یکی از آن هش های تمام قد با هش تمام قد URL مورد نظر مطابقت داشته باشد، URL ناامن در نظر گرفته می شود. اگر هیچ یک از هش های کامل با هش کامل URL مورد نظر مطابقت نداشته باشد، آن URL ایمن در نظر گرفته می شود.
گوگل به هیچ وجه از URL هایی که شما در حال بررسی آن هستید یاد نمی گیرد. گوگل پیشوندهای هش URL ها را یاد می گیرد، اما پیشوندهای هش اطلاعات زیادی در مورد URL های واقعی ارائه نمی دهند.
برای بررسی اینکه آیا یک URL در لیست مرور ایمن قرار دارد، یک درخواست HTTP POST به روش fullHashes.find ارسال کنید:
- درخواست HTTP
POSTمی تواند تا 500 ورودی تهدید را شامل شود. - درخواست HTTP
POSTشامل پیشوندهای هش URLهایی است که باید بررسی شوند. مشتریان تشویق می شوند تا چندین ورودی تهدید را در یک درخواست واحد جمع کنند تا استفاده از پهنای باند را کاهش دهند. - پاسخ HTTP
POSTهش های تمام طول منطبق را به همراه مدت زمان کش مثبت و منفی برمی گرداند. پاسخ همچنین ممکن است حداقل مدت زمان انتظار را برگرداند.
مثال: fullHashes.find
درخواست HTTP POST
در مثال زیر، نام دو لیست مرور ایمن و سه پیشوند هش برای مقایسه و تأیید ارسال شده است.
هدر درخواست
هدر درخواست شامل URL درخواست و نوع محتوا است. به یاد داشته باشید که کلید API خود را با 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 وضعیت های کلاینت را برای همه لیست های Safe Browsing در پایگاه داده محلی مشتری نگه می دارد. (حالت های سرویس گیرنده در قسمت newClientState پاسخ gefListUpdates.fetch برگردانده می شوند.)
لیست های مرور ایمن
فیلدهای threatTypes ، platformTypes و threatEntryTypes برای شناسایی (نام) فهرست‌های Safe Browsing ترکیب می‌شوند. در مثال، دو لیست شناسایی می شوند: MALWARE/WINDOWS/URL و SOCIAL_ENGINEERING/WINDOWS/URL. قبل از ارسال درخواست، مطمئن شوید که ترکیب‌های نوع مشخصی معتبر هستند (به فهرست‌های مرور ایمن مراجعه کنید).
پیشوندهای هش تهدید
آرایه تهدیدات حاوی پیشوندهای هش URL هایی است که می خواهید بررسی کنید. فیلد hash باید حاوی پیشوند هش دقیقی باشد که در پایگاه داده محلی وجود دارد. برای مثال، اگر پیشوند هش محلی 4 بایت باشد، ورودی تهدید باید 4 بایت باشد. اگر پیشوند هش محلی به 7 بایت طولانی شد، ورودی تهدید باید 7 بایت باشد.
در مثال، درخواست شامل سه پیشوند هش است. هر سه پیشوند با هر یک از فهرست‌های مرور ایمن مقایسه می‌شوند تا مشخص شود که آیا یک هش کامل منطبق وجود دارد یا خیر.
توجه: Update API و روش 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"
}
مسابقات
شیء Matches یک هش تمام طول منطبق را برای دو پیشوند هش برمی گرداند. URL های مربوط به این هش ها ناامن در نظر گرفته می شوند. هیچ منطبقی برای پیشوند هش سوم یافت نشد، بنابراین چیزی برگردانده نمی شود. URL مربوط به این پیشوند هش امن در نظر گرفته می شود.
توجه داشته باشید که این مثال یک هش تمام قد را با یک پیشوند هش مطابقت می دهد. با این حال، ممکن است چندین هش کامل وجود داشته باشد که به یک پیشوند هش نگاشت می شود.
فراداده
قسمت threatEntryMetadata اختیاری است و اطلاعات بیشتری در مورد تطابق تهدید ارائه می دهد. در حال حاضر، ابرداده برای فهرست مرور ایمن MALWARE/WINDOWS/URL در دسترس است (به فراداده مراجعه کنید).
مدت زمان کش
فیلدهای cacheDuration و negativeCacheDuration مدت زمانی را نشان می دهد که هش ها باید ناامن یا ایمن در نظر گرفته شوند (به ذخیره سازی مراجعه کنید).
حداقل مدت زمان انتظار
فیلد minimumWaitDuration نشان می دهد که مشتری باید 300 ثانیه (5 دقیقه) قبل از ارسال درخواست fullHashes دیگر صبر کند. توجه داشته باشید که ممکن است یک دوره انتظار در پاسخ گنجانده شود یا نباشد (به دفعات درخواست مراجعه کنید).