Package google.security.safebrowsing.v5alpha1

ดัชนี

SafeBrowsing

Safe Browsing API ช่วยให้ลูกค้าตรวจสอบทรัพยากรบนเว็บ (ส่วนใหญ่เป็น URL) เทียบกับรายการทรัพยากรบนเว็บที่ไม่ปลอดภัยของ Google ได้ ซึ่งมีการอัปเดตอยู่เป็นประจำ

BatchGetHashLists

rpc BatchGetHashLists(BatchGetHashListsRequest) returns (BatchGetHashListsResponse)

รับรายการแฮชหลายรายการพร้อมกัน

เป็นเรื่องปกติที่ไคลเอ็นต์จะต้องมีรายการแฮชหลายรายการ แนะนำให้ใช้วิธีการนี้มากกว่าการใช้เมธอด Get ปกติหลายครั้ง

นี่คือเมธอด Get แบบกลุ่มมาตรฐาน ตามที่กำหนดโดย https://google.aip.dev/231 และเมธอด HTTP ก็เป็น GET เช่นกัน
GetHashList

rpc GetHashList(GetHashListRequest) returns (HashList)

รับเนื้อหาล่าสุดของรายการแฮช รายการแฮชอาจอิงตามรายการภัยคุกคามหรือรายการที่ไม่ใช่ภัยคุกคาม เช่น แคชทั่วโลก

ซึ่งเป็นเมธอด Get มาตรฐานตามที่กำหนดโดย https://google.aip.dev/131 และเมธอด HTTP ก็ใช้ GET เช่นกัน
ListHashLists

rpc ListHashLists(ListHashListsRequest) returns (ListHashListsResponse)

แสดงรายการแฮช

ใน API เวอร์ชัน 5 Google จะไม่นำรายการแฮชที่เคยส่งคืนมาด้วยวิธีนี้ออก วิธีนี้จะช่วยให้ไคลเอ็นต์ข้ามการใช้วิธีการนี้และทำฮาร์ดโค้ดรายการแฮชทั้งหมดที่ต้องการได้อย่างง่ายดาย

ซึ่งเป็นเมธอดรายการมาตรฐานที่กำหนดโดย https://google.aip.dev/132 และเมธอด HTTP คือ GET
SearchHashes

rpc SearchHashes(SearchHashesRequest) returns (SearchHashesResponse)

ค้นหาแฮชแบบเต็มที่ตรงกับคำนำหน้าที่ระบุ

ซึ่งเป็นเมธอดที่กำหนดเองซึ่ง https://google.aip.dev/136 กำหนด (เมธอดที่กำหนดเองหมายถึงวิธีนี้มีชื่อที่กำหนดเองภายในระบบการตั้งชื่อ API ทั่วไปของ Google และไม่ได้หมายถึงการใช้เมธอด HTTP ที่กำหนดเอง)

BatchGetHashListsRequest

คำขอรับรายการแฮชหลายรายการพร้อมกัน

ช่อง
names[]

string

ต้องระบุ ชื่อของรายการแฮชที่ต้องการ รายการนี้อาจเป็นรายการภัยคุกคาม หรืออาจเป็น Global Cache ชื่อต้องไม่ซ้ำ หากชื่อซ้ำกัน ไคลเอ็นต์จะพบข้อผิดพลาด
version[]

bytes

เวอร์ชันของรายการแฮชที่ไคลเอ็นต์มีอยู่แล้ว หากไคลเอ็นต์ดึงข้อมูลรายการแฮชเป็นครั้งแรก ควรเว้นช่องนี้ว่างไว้ ไม่เช่นนั้น ไคลเอ็นต์ควรจัดหาเวอร์ชันที่ได้รับจากเซิร์ฟเวอร์ก่อนหน้านี้ ไคลเอ็นต์ต้องไม่จัดการกับไบต์เหล่านั้น

ไคลเอ็นต์ไม่จำเป็นต้องส่งเวอร์ชันในลำดับเดียวกันกับชื่อรายการที่เกี่ยวข้อง ไคลเอ็นต์อาจส่งคำขอในเวอร์ชันน้อยกว่าหรือมากกว่าที่มีชื่อ แต่ไคลเอ็นต์ต้องไม่ส่งหลายเวอร์ชันที่สอดคล้องกับชื่อเดียวกัน หากส่ง ไคลเอ็นต์จะพบข้อผิดพลาด

หมายเหตุในอดีต: ใน API เวอร์ชัน 4 โดยใช้ชื่อว่า states ตอนนี้เปลี่ยนชื่อเป็น version เพื่อความชัดเจน
desired_hash_length

HashLength

ความยาวของคำนำหน้าแฮชที่ต้องการของแฮชที่แสดงผลในหน่วยไบต์ จากนั้นเซิร์ฟเวอร์จะส่งคืนคำนำหน้าแฮชทั้งหมดในความยาวที่ระบุนี้

รายการแฮชที่ต่างกันมีข้อกำหนดที่แตกต่างกันเกี่ยวกับค่าที่ยอมรับได้ของช่อง desired_hash_length จะอยู่ในช่อง supported_hash_lengths ใน HashListMetadata หาก desired_hash_length ไม่ได้ระบุค่าภายใน supported_hash_lengths ระบบจะแสดงข้อผิดพลาดไปยังไคลเอ็นต์

โดยเฉพาะอย่างยิ่งสำหรับ BatchGetHashListsRequest ลูกค้าไม่สามารถระบุ desired_hash_length ที่แตกต่างกันสำหรับรายการที่แตกต่างกันได้ หากจำเป็นต้องทำเช่นนั้น ลูกค้าควรแยกเป็น BatchGetHashListsRequest หลายรายการ
size_constraints

SizeConstraints

ข้อจำกัดด้านขนาดในแต่ละรายการ หากไม่ระบุ จะไม่มีข้อจำกัดใดๆ โปรดทราบว่าขนาดที่แสดงนี้เป็นขนาดต่อรายการ ไม่ใช่ขนาดในรายการทั้งหมด

BatchGetHashListsResponse

คำตอบที่มีรายการแฮชหลายรายการ

ช่อง
hash_lists[]

HashList

รายการแฮชในลำดับเดียวกันกับที่ระบุไว้ในคำขอ

FullHash

แฮชแบบเต็มที่ระบุตรงกับรายการที่ตรงกันอย่างน้อย 1 รายการ

ช่อง
full_hash

bytes

แฮชแบบเต็มที่ตรงกัน นี่คือแฮช SHA256 ความยาวจะอยู่ที่ 32 ไบต์พอดี
full_hash_details[]

FullHashDetail

รายการที่ไม่เรียงลำดับ ช่องที่ซ้ำซึ่งระบุรายละเอียดที่เกี่ยวข้องกับแฮชแบบเต็มนี้

FullHashDetail

รายละเอียดเกี่ยวกับแฮชแบบเต็มที่ตรงกัน

หมายเหตุสำคัญเกี่ยวกับความเข้ากันได้ในอนาคต: เซิร์ฟเวอร์อาจเพิ่มประเภทภัยคุกคามและแอตทริบิวต์ของภัยคุกคามใหม่ได้ทุกเมื่อ ส่วนเพิ่มเติมดังกล่าวถือว่าเป็นการเปลี่ยนแปลงเวอร์ชันเล็กน้อย Google มีนโยบายที่จะไม่เปิดเผยหมายเลขเวอร์ชันย่อยใน API (โปรดดูนโยบายการกำหนดเวอร์ชันใน https://cloud.google.com/apis/design/versioning) ดังนั้นไคลเอ็นต์ต้องเตรียมรับข้อความ FullHashDetail ที่มีค่า enum ของ ThreatType หรือค่า enum ThreatAttribute ที่ไคลเอ็นต์ถือว่าไม่ถูกต้อง ดังนั้น ลูกค้ามีหน้าที่ตรวจสอบความถูกต้องของค่า enum ของ ThreatType และ ThreatAttribute ทั้งหมด หากค่าใดค่าหนึ่งถือว่าไม่ถูกต้อง ไคลเอ็นต์จะต้องเพิกเฉยต่อข้อความ FullHashDetail ทั้งหมด

ช่อง
threat_type

ThreatType

ประเภทของภัยคุกคาม ช่องนี้จะไม่ว่าง
attributes[]

ThreatAttribute

รายการที่ไม่เรียงลำดับ แอตทริบิวต์เพิ่มเติมเกี่ยวกับแฮชแบบเต็มเหล่านั้น ส่วนนี้อาจว่างเปล่า

GetHashListRequest

คําขอที่จะรับรายการแฮช ซึ่งอาจเป็นรายการภัยคุกคามหรือรายการที่ไม่ใช่ภัยคุกคาม เช่น เซิร์ฟเวอร์แคชทั่วโลก

มีอะไรใหม่ใน V5: ก่อนหน้านี้ states ใน V4 เปลี่ยนชื่อเป็น version เพื่อความชัดเจน ตอนนี้เราได้ตั้งชื่อรายการแล้ว นำประเภทแพลตฟอร์มและประเภทรายการภัยคุกคามออก ตอนนี้รายการหลายรายการอาจมีภัยคุกคามประเภทเดียวกัน หรือรายการเดียวที่เกี่ยวข้องกับภัยคุกคามหลายประเภท ไคลเอ็นต์มีความสามารถใหม่ในการระบุความยาวแฮชที่ต้องการ นี่เป็นส่วนหนึ่งของคำตอบเกี่ยวกับคำนำหน้าแฮชที่มีความยาวตัวแปรของ V4 ซึ่งทำให้เกิดปัญหาในการใช้งานไคลเอ็นต์หลายอย่าง นั่นคือตอนนี้แฮชทั้งหมดในรายการจะมีความยาวเดียว ทำให้สามารถติดตั้งใช้งานไคลเอ็นต์ได้อย่างมีประสิทธิภาพมากขึ้น ลดความซับซ้อนของข้อจำกัดและนำประเภทการบีบอัดออก (มีการใช้การบีบอัดเสมอ)

ช่อง
name

string

ต้องระบุ ชื่อของรายการแฮชนี้ โดยอาจเป็นรายการภัยคุกคาม หรืออาจเป็น Global Cache
version

bytes

เวอร์ชันของรายการแฮชที่ไคลเอ็นต์มีอยู่แล้ว หากไคลเอ็นต์ดึงข้อมูลรายการแฮชเป็นครั้งแรก ช่องนี้ต้องเว้นว่างไว้ ไม่เช่นนั้น ไคลเอ็นต์ควรจัดหาเวอร์ชันที่ได้รับมาจากเซิร์ฟเวอร์ก่อนหน้านี้ ไคลเอ็นต์ต้องไม่จัดการกับไบต์เหล่านั้น

มีอะไรใหม่ใน V5: ใน API เวอร์ชัน 4 โดยใช้ชื่อว่า states และตอนนี้เปลี่ยนชื่อเป็น version เพื่อความชัดเจน
desired_hash_length

HashLength

ความยาวของคำนำหน้าแฮชที่ต้องการของแฮชที่แสดงผลในหน่วยไบต์ จากนั้นเซิร์ฟเวอร์จะส่งคืนคำนำหน้าแฮชทั้งหมดในความยาวที่ระบุนี้

รายการแฮชที่ต่างกันมีข้อกำหนดที่แตกต่างกันเกี่ยวกับค่าที่ยอมรับได้ของช่อง desired_hash_length จะอยู่ในช่อง supported_hash_lengths ใน HashListMetadata หาก desired_hash_length ไม่ได้ระบุค่าภายใน supported_hash_lengths ระบบจะแสดงข้อผิดพลาด
size_constraints

SizeConstraints

ข้อจำกัดด้านขนาดในรายการ หากไม่ระบุ จะไม่มีข้อจำกัดใดๆ ขอแนะนำให้ใช้ข้อจำกัดในอุปกรณ์ทั้งหมดที่ใช้พลังงานในการประมวลผล แบนด์วิดท์ หรือพื้นที่เก็บข้อมูลที่จำกัด

HashList

รายการแฮชที่ระบุตามชื่อ

ช่อง
name

string

ชื่อของรายการแฮช โปรดทราบว่า Global Cache เป็นเพียงรายการแฮชที่สามารถอ้างอิงถึงได้ที่นี่
version

bytes

เวอร์ชันของรายการแฮช ไคลเอ็นต์ต้องไม่จัดการกับไบต์เหล่านั้น
partial_update

bool

เมื่อเป็นจริง นี่จะเป็นความแตกต่างบางส่วนที่มีการเพิ่มและการนำออกตามสิ่งที่ลูกค้ามีอยู่แล้ว เมื่อเป็นเท็จ นี่คือรายการแฮชทั้งหมด

เมื่อเป็นเท็จ ไคลเอ็นต์จะต้องลบเวอร์ชันที่เก็บไว้ในเครื่องสำหรับรายการแฮชนี้ ซึ่งหมายความว่าเวอร์ชันที่ไคลเอ็นต์ใช้นั้นล้าสมัยเป็นอย่างมากหรือเชื่อว่าข้อมูลลูกค้าอาจเสียหาย ช่อง compressed_removals จะว่างเปล่า

เมื่อเป็นจริง ไคลเอ็นต์จะต้องอัปเดตเพิ่มเติมโดยใช้การนำออกและการเพิ่ม
compressed_removals

RiceDeltaEncoded32Bit

ดัชนีนำออกเวอร์ชันที่เข้ารหัสแบบเดลต้าข้าว เนื่องจากรายการแฮชแต่ละรายการมีน้อยกว่า 2^32 รายการ ดัชนีจึงถือเป็นจํานวนเต็ม 32 บิตและมีการเข้ารหัส
minimum_wait_duration

Duration

ไคลเอ็นต์ควรรอนานเท่านี้จึงจะได้รายการแฮชอีกครั้ง หากไม่ระบุหรือเป็น 0 ไคลเอ็นต์ควรดึงข้อมูลทันทีเนื่องจากระบุว่าเซิร์ฟเวอร์มีการอัปเดตเพิ่มเติมที่จะส่งไปให้ไคลเอ็นต์ แต่ไม่สามารถทำได้เนื่องด้วยข้อจำกัดที่ไคลเอ็นต์ระบุ
metadata

HashListMetadata

ข้อมูลเมตาเกี่ยวกับรายการแฮช ค่านี้ไม่ได้สร้างขึ้นโดยเมธอด GetHashList แต่สร้างขึ้นโดยเมธอด ListHashLists
ฟิลด์สหภาพ compressed_additions เวอร์ชันเพิ่มเติมที่เข้ารหัสแบบ Rice-delta ความยาวของคำนำหน้าแฮชของการเพิ่มเติมจะเท่ากันในทุกส่วนเพิ่มเติมในรายการ ซึ่งจะเป็น desired_hash_length ที่ลูกค้าส่งมา หรือค่าที่เซิร์ฟเวอร์เลือกหากไคลเอ็นต์ละฟิลด์ดังกล่าวไป compressed_additions ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
additions_four_bytes

RiceDeltaEncoded32Bit

ข้อมูลที่เพิ่มเข้ามาแบบ 4 ไบต์
additions_eight_bytes

RiceDeltaEncoded64Bit

การเพิ่มเติม 8 ไบต์
additions_sixteen_bytes

RiceDeltaEncoded128Bit

การเพิ่มเติมขนาด 16 ไบต์
additions_thirty_two_bytes

RiceDeltaEncoded256Bit

ข้อมูลที่เพิ่มเข้ามาแบบ 32 ไบต์
ฟิลด์สหภาพ checksum นี่คือผลรวมตรวจสอบสำหรับรายการแฮชที่จัดเรียงของแฮชทั้งหมดที่มีอยู่ในฐานข้อมูลหลังจากนำการอัปเดตที่ระบุไปใช้ นี่คือช่อง "1of" สำหรับอนุญาตอัลกอริทึมการแฮชหลายรายการ นอกจากนี้ เซิร์ฟเวอร์ยังอาจข้ามช่องนี้ (ในกรณีที่ไม่มีการอัปเดต) เพื่อระบุว่าไคลเอ็นต์ควรใช้ checksum ที่มีอยู่ checksum ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
sha256_checksum

bytes

รายการแฮชทั้งหมดที่จัดเรียงแล้ว ซึ่งแฮชอีกครั้งด้วย SHA256

HashListMetadata

ข้อมูลเมตาเกี่ยวกับรายการแฮชที่เฉพาะเจาะจง

ช่อง
threat_types[]

ThreatType

รายการที่ไม่เรียงลำดับ หากเป็นค่าว่าง จะระบุว่ารายการแฮชเป็นรายการภัยคุกคามประเภทหนึ่ง และจะระบุประเภทของภัยคุกคามที่เชื่อมโยงกับแฮชหรือคํานําหน้าแฮชในรายการแฮชนี้ อาจว่างเปล่าหากรายการนั้นไม่ได้แสดงถึงภัยคุกคาม เช่น ในกรณีที่แสดงถึงประเภทที่ปลอดภัย
likely_safe_types[]

LikelySafeType

รายการที่ไม่เรียงลำดับ หากไม่ว่างเปล่า จะระบุว่ารายการแฮชแสดงรายการของแฮชที่น่าจะปลอดภัย และแจกแจงวิธีที่ระบบพิจารณาว่าน่าจะปลอดภัย ช่องนี้แยกต่างหากพร้อมกับช่อง Threat_types
mobile_optimized

bool

เพิ่มประสิทธิภาพรายการสำหรับอุปกรณ์เคลื่อนที่ (Android และ iOS) หรือไม่
description

string

คำอธิบายที่มนุษย์อ่านได้เกี่ยวกับรายการนี้ เขียนเป็นภาษาอังกฤษ
supported_hash_lengths[]

HashLength

ความยาวแฮชที่รองรับสำหรับรายการแฮชนี้ รายการแฮชแต่ละรายการจะรองรับความยาวได้อย่างน้อย 1 ความยาว ดังนั้นฟิลด์นี้จะว่างเปล่า

HashLength

ความยาวของแฮชในรายการแฮช

Enum
HASH_LENGTH_UNSPECIFIED ไม่ได้ระบุความยาว เซิร์ฟเวอร์จะไม่ส่งคืนค่านี้ในการตอบกลับไปยังไคลเอ็นต์ (ในช่อง supported_hash_lengths) แต่ไคลเอ็นต์จะส่งค่านี้ไปยังเซิร์ฟเวอร์ได้ (ในช่อง desired_hash_length) ซึ่งในกรณีนี้เซิร์ฟเวอร์จะเลือกค่าโดยอัตโนมัติ ไคลเอ็นต์ควรให้เซิร์ฟเวอร์เลือกค่า
FOUR_BYTES แฮชแต่ละรายการจะเป็นคำนำหน้าแบบ 4 ไบต์
EIGHT_BYTES แฮชแต่ละรายการจะขึ้นต้นด้วย 8 ไบต์
SIXTEEN_BYTES แฮชแต่ละรายการจะขึ้นต้นด้วย 16 ไบต์
THIRTY_TWO_BYTES แฮชแต่ละรายการจะเป็นแฮชแบบเต็ม 32 ไบต์

LikelySafeType

ประเภทเว็บไซต์ที่น่าจะปลอดภัย

โปรดทราบว่า SearchHashesResponse จงใจไม่มี LikelySafeType

Enum
LIKELY_SAFE_TYPE_UNSPECIFIED ไม่รู้จัก
GENERAL_BROWSING เว็บไซต์นี้น่าจะปลอดภัยเพียงพอสำหรับการท่องเว็บทั่วไป หรือเรียกอีกอย่างหนึ่งว่าแคชส่วนกลาง
CSD เว็บไซต์นี้น่าจะปลอดภัยมากพอที่จะไม่จำเป็นต้องเรียกใช้โมเดลการตรวจจับฝั่งไคลเอ็นต์หรือการตรวจสอบการป้องกันด้วยรหัสผ่าน
DOWNLOAD เว็บไซต์นี้น่าจะปลอดภัยมากพอที่จะไม่ต้องตรวจสอบการดาวน์โหลดจากเว็บไซต์

ListHashListsRequest

คำขอเพื่อแสดงรายการแฮชที่ใช้ได้

ช่อง
page_size

int32

จำนวนรายการแฮชสูงสุดที่จะแสดงได้ บริการอาจแสดงผลน้อยกว่าค่านี้ หากไม่ระบุ เซิร์ฟเวอร์จะเลือกขนาดหน้า ซึ่งอาจมากกว่าจำนวนรายการแฮชเพื่อจะได้ไม่ต้องใส่เลขหน้า
page_token

string

โทเค็นของหน้าเว็บที่ได้รับจากการโทร ListHashLists ครั้งก่อน ระบุข้อมูลนี้เพื่อเรียกหน้าถัดไป

ListHashListsResponse

คำตอบที่มีข้อมูลเมตาเกี่ยวกับรายการแฮช

ช่อง
hash_lists[]

HashList

รายการแฮชจะอยู่ในลำดับที่กำหนดเอง ระบบจะรวมเฉพาะข้อมูลเมตาเกี่ยวกับรายการแฮชเท่านั้น แต่จะไม่รวมเนื้อหา
next_page_token

string

โทเค็นที่ส่งเป็น page_token เพื่อเรียกดูหน้าถัดไปได้ หากเว้นช่องนี้ไว้ ก็จะไม่เห็นหน้าต่อๆ ไป

การเข้ารหัส RiceDelta128 บิต

เหมือนกับ RiceDeltaEncoded32Bit ยกเว้นว่ารายการนี้เข้ารหัสหมายเลข 128 บิต

ช่อง
first_value_hi

uint64

64 บิตบนของรายการแรกในข้อมูลที่เข้ารหัส (แฮช) หากช่องนี้ว่างเปล่า 64 บิตด้านบนจะเป็น 0 ทั้งหมด
first_value_lo

fixed64

64 บิตล่างของรายการแรกในข้อมูลที่เข้ารหัส (แฮช) หากช่องนี้เว้นว่างไว้ 64 บิตล่างจะเป็น 0 ทั้งหมด
rice_parameter

int32

พารามิเตอร์ Golomb-Rice พารามิเตอร์นี้รับประกันได้ว่าจะอยู่ระหว่าง 99 ถึง 126
entries_count

int32

จำนวนรายการที่เข้ารหัสแบบเดลต้าในข้อมูลที่เข้ารหัส หากมีการเข้ารหัสจำนวนเต็มค่าเดียว ค่านี้จะเป็น 0 และจะเก็บค่าเดี่ยวไว้ใน first_value
encoded_data

bytes

เดลต้าที่เข้ารหัสซึ่งเข้ารหัสโดยใช้ตัวแปลงรหัส Golomb-Rice

RiceDeltaEncrypted256 บิต

เหมือนกับ RiceDeltaEncoded32Bit ยกเว้นว่ารายการนี้เข้ารหัสหมายเลข 256 บิต

ช่อง
first_value_first_part

uint64

64 บิตแรกของรายการแรกในข้อมูลที่เข้ารหัส (แฮช) หากช่องนี้ว่างเปล่า 64 บิตแรกจะเป็น 0 ทั้งหมด
first_value_second_part

fixed64

บิต 65 ถึง 128 บิตของรายการแรกในข้อมูลที่เข้ารหัส (แฮช) หากช่องนี้ว่างเปล่า บิตที่ 65 ถึง 128 บิตจะเป็น 0 ทั้งหมด
first_value_third_part

fixed64

บิต 129 ถึง 192 บิตของรายการแรกในข้อมูลที่เข้ารหัส (แฮช) หากช่องนี้ว่างเปล่า บิต 129 ถึง 192 บิตจะเป็น 0 ทั้งหมด
first_value_fourth_part

fixed64

64 บิตสุดท้ายของรายการแรกในข้อมูลที่เข้ารหัส (แฮช) หากเว้นช่องนี้ว่างไว้ 64 บิตสุดท้ายจะเป็น 0 ทั้งหมด
rice_parameter

int32

พารามิเตอร์ Golomb-Rice รับประกันได้ว่าพารามิเตอร์นี้อยู่ระหว่าง 227 ถึง 254
entries_count

int32

จำนวนรายการที่เข้ารหัสแบบเดลต้าในข้อมูลที่เข้ารหัส หากมีการเข้ารหัสจำนวนเต็มค่าเดียว ค่านี้จะเป็น 0 และจะเก็บค่าเดี่ยวไว้ใน first_value
encoded_data

bytes

เดลต้าที่เข้ารหัสซึ่งเข้ารหัสโดยใช้ตัวแปลงรหัส Golomb-Rice

RiceDeltaEncrypted32 บิต

ข้อมูลที่เข้ารหัส Rice-Golomb ใช้สำหรับแฮชหรือดัชนีการลบ โดยจะรับประกันว่าแฮชหรือดัชนีทุกรายการในส่วนนี้มีความยาวเท่ากัน และความยาวคือ 32 บิตเท่านั้น

โดยทั่วไปแล้ว หากเราจัดเรียงรายการทั้งหมดแบบพจนานุกรม เราจะพบว่าบิตของลำดับที่สูงกว่าไม่มีการเปลี่ยนแปลงบ่อยเท่ากับบิตของลำดับที่ต่ำกว่า ซึ่งหมายความว่าหากเราใช้ผลต่างที่ใกล้เคียงกันระหว่างรายการด้วย บิตของลำดับที่สูงกว่าก็มีโอกาสที่จะเป็น 0 สูง การใช้ประโยชน์จากความน่าจะเป็นที่สูงนี้เป็น 0 ด้วยการเลือกจำนวนบิตที่กำหนด สำหรับบิตทั้งหมดที่สำคัญมากกว่านี้มีแนวโน้มที่จะเป็น 0 เราจึงใช้การเข้ารหัสแบบเอกนารี โปรดดูช่อง rice_parameter

หมายเหตุในอดีต: มีการใช้การเข้ารหัสแบบเดลต้าไรซ์เป็นครั้งแรกในเวอร์ชัน 4 ของ API นี้ ใน V5 ได้มีการปรับปรุงที่สำคัญ 2 อย่าง อย่างแรกคือการเข้ารหัสแบบเดลต้าข้าวพร้อมใช้งานกับคำนำหน้าแฮชที่ยาวกว่า 4 ไบต์ ประการที่ 2 จะถือว่าข้อมูลที่เข้ารหัสเป็นข้อมูลขนาดใหญ่ เพื่อหลีกเลี่ยงขั้นตอนการจัดเรียงที่มีค่าใช้จ่ายสูง

ช่อง
first_value

uint32

รายการแรกในข้อมูลที่เข้ารหัส (แฮชหรือดัชนี) หรือหากมีการเข้ารหัสคำนำหน้าแฮชหรือดัชนีเพียงค่าเดียว ค่าของรายการนั้น หากช่องนี้เว้นว่างไว้ รายการนั้นจะมีค่าเป็น 0
rice_parameter

int32

พารามิเตอร์ Golomb-Rice รับประกันได้ว่าพารามิเตอร์นี้อยู่ระหว่าง 3 ถึง 30
entries_count

int32

จำนวนรายการที่เข้ารหัสแบบเดลต้าในข้อมูลที่เข้ารหัส หากมีการเข้ารหัสจำนวนเต็มค่าเดียว ค่านี้จะเป็น 0 และจะเก็บค่าเดี่ยวไว้ใน first_value
encoded_data

bytes

เดลต้าที่เข้ารหัสซึ่งเข้ารหัสโดยใช้ตัวแปลงรหัส Golomb-Rice

การเข้ารหัส RiceDelta64 บิต

เหมือนกับ RiceDeltaEncoded32Bit ยกเว้นว่ารายการนี้เข้ารหัสหมายเลข 64 บิต

ช่อง
first_value

uint64

รายการแรกในข้อมูลที่เข้ารหัส (แฮช) หรือหากเข้ารหัสคำนำหน้าแฮชเพียงค่าเดียว ค่าของรายการนั้น หากช่องนี้เว้นว่างไว้ รายการนั้นจะมีค่าเป็น 0
rice_parameter

int32

พารามิเตอร์ Golomb-Rice รับประกันได้ว่าพารามิเตอร์นี้อยู่ระหว่าง 35 ถึง 62
entries_count

int32

จำนวนรายการที่เข้ารหัสแบบเดลต้าในข้อมูลที่เข้ารหัส หากมีการเข้ารหัสจำนวนเต็มค่าเดียว ค่านี้จะเป็น 0 และจะเก็บค่าเดี่ยวไว้ใน first_value
encoded_data

bytes

เดลต้าที่เข้ารหัสซึ่งเข้ารหัสโดยใช้ตัวแปลงรหัส Golomb-Rice

SearchHashesRequest

คำขอที่ไคลเอ็นต์มีปัญหาในการค้นหาคำนำหน้าแฮชที่เจาะจง

ซึ่งออกแบบมาเพื่อค้นหาเฉพาะรายการภัยคุกคาม และไม่ค้นหารายการที่ไม่ใช่ภัยคุกคาม เช่น เซิร์ฟเวอร์แคชทั่วโลก

มีอะไรใหม่ใน V5: ไคลเอ็นต์ไม่จำเป็นต้องระบุ ClientInfo หรือสถานะของรายการแฮชในฐานข้อมูลของเครื่อง ตัวเลือกนี้มีไว้เพื่อปรับปรุงความเป็นส่วนตัว นอกจากนี้ ลูกค้าไม่จำเป็นต้องส่งประเภทภัยคุกคามที่ตนสนใจ

ช่อง
hash_prefixes[]

bytes

ต้องระบุ คำนำหน้าแฮชที่ต้องค้นหา ไคลเอ็นต์ต้องไม่ส่งคำนำหน้าแฮชมากกว่า 1,000 รายการ แต่เมื่อทำตามขั้นตอนการประมวลผล URL ไคลเอ็นต์ไม่จำเป็นต้องส่งคำนำหน้าแฮชมากกว่า 30 รายการ

ปัจจุบันคำนำหน้าแฮชแต่ละรายการต้องมีความยาว 4 ไบต์พอดี การเปลี่ยนแปลงนี้อาจผ่อนปรนในอนาคต
filter

string

ไม่บังคับ คุณสามารถระบุเงื่อนไขนี้ได้หากไคลเอ็นต์สนใจในการกรอง เช่น การดึงข้อมูลภัยคุกคามบางประเภทเท่านั้น หากไม่ระบุ ระบบจะแสดงผลภัยคุกคามที่ตรงกันทั้งหมด เราขอแนะนำอย่างยิ่งให้ข้ามส่วนนี้ไปเพื่อให้ได้รับการปกป้องที่สมบูรณ์ที่สุดที่ Google Safe Browsing มอบให้

ตัวกรองจะระบุโดยใช้ Common Expression Language ของ Google ซึ่งดูได้ที่ https://github.com/google/cel-spec พร้อมกับตัวอย่างทั่วไป ตัวอย่างบางส่วนที่ใช้ได้ที่นี่มีดังนี้

ตัวกรอง "threat_type == ThreatType.SOCIAL_ENGINEERING" กำหนดว่าภายใน FullHashDetail ประเภทภัยคุกคามต้องเป็น SOCIAL_ENGINEERING ตัวระบุ "threat_type" หมายถึงประเภทของภัยคุกคามปัจจุบัน ตัวระบุ "ThreatType" หมายถึงคอลเล็กชันของประเภทภัยคุกคามทั้งหมดที่เป็นไปได้

ตัวกรอง "threat_type in [ ThreatType.UNWANTED_SOFTWARE, ThreatType.MALWARE ]" กำหนดว่าประเภทภัยคุกคามต้องเป็น UNWANTED_SOFTWARE หรือ MALWARE

SearchHashesResponse

การตอบสนองที่แสดงหลังจากค้นหาแฮชของภัยคุกคาม

หากไม่พบอะไรเลย เซิร์ฟเวอร์จะแสดงสถานะ OK (รหัสสถานะ HTTP 200) พร้อมกับช่อง full_hashes ที่ว่างเปล่า แทนที่จะส่งคืนสถานะ NOT_FOUND (รหัสสถานะ HTTP 404)

มีอะไรใหม่ใน V5: FullHash และ FullHashDetail แยกออกจากกัน ในกรณีที่แฮชแสดงถึงเว็บไซต์ที่มีภัยคุกคามหลายอย่าง (เช่น ทั้ง MALWARE และ SOCIAL_ENGINEERING) ไม่จำเป็นต้องส่งแฮชแบบเต็มเป็น 2 เท่าของเวอร์ชัน 4 นอกจากนี้ ได้ลดความซับซ้อนของระยะเวลาของแคชไว้ในช่อง cache_duration เพียงช่องเดียว

ช่อง
full_hashes[]

FullHash

รายการที่ไม่เรียงลำดับ พบรายการแฮชทั้งหมดแบบไม่เรียงลำดับ
cache_duration

Duration

ระยะเวลาของแคชฝั่งไคลเอ็นต์ ไคลเอ็นต์จะต้องเพิ่มระยะเวลานี้เป็นเวลาปัจจุบันเพื่อกำหนดเวลาหมดอายุ จากนั้นเวลาหมดอายุจะมีผลกับคำนำหน้าแฮชทั้งหมดที่ไคลเอ็นต์ค้นหาในคำขอ โดยไม่คำนึงถึงจำนวนแฮชแบบเต็มที่ตอบกลับในการตอบสนอง แม้ว่าเซิร์ฟเวอร์จะไม่แสดงผลแฮชแบบเต็มสำหรับคำนำหน้าแฮชที่เจาะจง แต่ไคลเอ็นต์จะต้องแคชข้อเท็จจริงนี้ไว้ด้วย

หากช่อง full_hashes ว่างเปล่า ไคลเอ็นต์อาจเพิ่ม cache_duration เพื่อระบุการหมดอายุใหม่ช้ากว่าที่เซิร์ฟเวอร์ระบุไว้ ไม่ว่าในกรณีใด ระยะเวลาของแคชที่เพิ่มขึ้นต้องไม่เกิน 24 ชั่วโมง

ข้อสำคัญ: ไคลเอ็นต์ต้องไม่คิดไปเองว่าเซิร์ฟเวอร์จะส่งคืนระยะเวลาแคชเดียวกันสำหรับการตอบกลับทั้งหมด เซิร์ฟเวอร์อาจเลือกระยะเวลาแคชที่แตกต่างกันสำหรับการตอบสนองที่แตกต่างกันขึ้นอยู่กับสถานการณ์

SizeConstraints

ข้อจำกัดของขนาดของรายการแฮช

ช่อง
max_update_entries

int32

จำนวนรายการสูงสุด การอัปเดตจะไม่มีรายการมากกว่าค่านี้ แต่ก็เป็นไปได้ว่าการอัปเดตจะมีรายการน้อยกว่าค่านี้ ค่านี้ต้องมีค่าอย่างน้อย 1024 หากไม่ระบุหรือเป็น 0 จะไม่มีการกำหนดขีดจำกัดขนาดของการอัปเดต
max_database_entries

int32

ตั้งค่าจำนวนรายการสูงสุดที่ไคลเอ็นต์ต้องการให้มีในฐานข้อมูลของเครื่องสำหรับรายการ (เซิร์ฟเวอร์อาจทำให้ไคลเอ็นต์จัดเก็บข้อมูลน้อยกว่าจำนวนนี้) หากไม่ระบุหรือเป็น 0 จะไม่มีการกำหนดขีดจำกัดขนาดฐานข้อมูล

ThreatAttribute

ลักษณะของภัยคุกคาม แอตทริบิวต์เหล่านี้อาจให้ความหมายเพิ่มเติมแก่ภัยคุกคามหนึ่งๆ ด้วย แต่จะไม่ส่งผลต่อประเภทของภัยคุกคาม เช่น แอตทริบิวต์อาจระบุความเชื่อมั่นต่ำกว่า แต่อีกแอตทริบิวต์หนึ่งอาจระบุความเชื่อมั่นที่สูงกว่า เราอาจเพิ่มแอตทริบิวต์อื่นๆ ในอนาคต

Enum
THREAT_ATTRIBUTE_UNSPECIFIED แอตทริบิวต์ที่ไม่รู้จัก หากเซิร์ฟเวอร์ส่งคืนค่านี้ ไคลเอ็นต์จะเพิกเฉยต่อ FullHashDetail ที่รวมอยู่ทั้งหมด
CANARY ระบุว่าไม่ควรใช้ Threat_type ในการบังคับใช้
FRAME_ONLY ระบุว่า Threat_type ควรใช้เพื่อบังคับใช้กับเฟรมเท่านั้น

ThreatType

ประเภทของภัยคุกคาม

Enum
THREAT_TYPE_UNSPECIFIED ไม่ทราบประเภทภัยคุกคาม หากเซิร์ฟเวอร์ส่งคืนค่านี้ ไคลเอ็นต์จะเพิกเฉยต่อ FullHashDetail ที่รวมอยู่ทั้งหมด
MALWARE

ประเภทภัยคุกคามมัลแวร์ มัลแวร์คือซอฟต์แวร์หรือแอปพลิเคชันบนอุปกรณ์เคลื่อนที่ใดๆ ก็ตามที่ออกแบบมาเพื่อสร้างความเสียหายแก่คอมพิวเตอร์ อุปกรณ์เคลื่อนที่ ซอฟต์แวร์ที่ทำงานอยู่ หรือผู้ใช้ซอฟต์แวร์นั้นๆ มัลแวร์มีลักษณะการทำงานที่เป็นอันตราย ซึ่งอาจรวมถึงการติดตั้งซอฟต์แวร์โดยไม่ได้รับคำยินยอมจากผู้ใช้ และการติดตั้งซอฟต์แวร์ที่เป็นอันตรายอย่างเช่น ไวรัส

ดูข้อมูลเพิ่มเติมได้ที่นี่
SOCIAL_ENGINEERING

ประเภทภัยคุกคามด้านวิศวกรรมสังคม หน้าวิศวกรรมสังคมที่แอบอ้างว่ากระทำการในนามของบุคคลที่สามโดยมีเจตนาสร้างความสับสนแก่ผู้ชมให้กระทำสิ่งที่ผู้ดูจะเชื่อถือตัวแทนที่แท้จริงของบุคคลที่สามนั้นเท่านั้น ฟิชชิงเป็นวิศวกรรมสังคมประเภทหนึ่งที่หลอกลวงผู้ชมให้ระบุข้อมูลเพื่อดำเนินการบางอย่าง เช่น ข้อมูลเข้าสู่ระบบ

ดูข้อมูลเพิ่มเติมได้ที่นี่
UNWANTED_SOFTWARE ประเภทภัยคุกคามซอฟต์แวร์ไม่พึงประสงค์ ซอฟต์แวร์ไม่พึงประสงค์คือซอฟต์แวร์ที่ไม่ปฏิบัติตามแนวนโยบายด้านซอฟต์แวร์ของ Google แต่ไม่ใช่มัลแวร์
POTENTIALLY_HARMFUL_APPLICATION ประเภทภัยคุกคามแอปพลิเคชันที่อาจเป็นอันตรายตามที่ Google Play Protect ใช้สำหรับ Play Store