Method: hashes.search

Tìm kiếm hàm băm đầy đủ khớp với các tiền tố đã chỉ định.

Đây là một phương thức tuỳ chỉnh do https://google.aip.dev/136 xác định (phương thức tuỳ chỉnh dùng để chỉ phương thức này có tên tuỳ chỉnh trong thuật ngữ phát triển API chung của Google; phương thức này không đề cập đến việc sử dụng phương thức HTTP tuỳ chỉnh).

Yêu cầu HTTP

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

URL sử dụng cú pháp Chuyển mã gRPC.

Tham số truy vấn

Tham số
hashPrefixes[]

string (bytes format)

Bắt buộc. Các tiền tố hàm băm cần được tra cứu. Ứng dụng KHÔNG ĐƯỢC gửi nhiều hơn 1.000 tiền tố băm. Tuy nhiên, theo quy trình xử lý URL, ứng dụng KHÔNG NÊN gửi nhiều hơn 30 tiền tố băm.

Hiện tại, mỗi tiền tố hàm băm bắt buộc phải dài chính xác 4 byte. Có thể sau này bạn sẽ thấy thoải mái hơn.

Chuỗi được mã hoá base64.
filter

string

Không bắt buộc. Nếu ứng dụng muốn lọc, chẳng hạn như chỉ truy xuất các loại mối đe doạ cụ thể, thì ứng dụng có thể được chỉ định. Nếu bỏ qua, tất cả mối đe doạ phù hợp sẽ được trả về. Bạn nên bỏ qua thuộc tính này để có được khả năng bảo vệ toàn diện nhất mà tính năng Duyệt web an toàn có thể cung cấp.

Bộ lọc này được chỉ định bằng Ngôn ngữ diễn đạt thông thường của Google, có tại https://github.com/google/cel-spec cùng với các ví dụ chung. Sau đây là một số ví dụ cụ thể mà bạn có thể tham khảo:

Bộ lọc "threatType == ThreatType.SOCIAL_ENGINEERING" yêu cầu kiểu mối đe doạ trong FullHashDetail phải là SOCIAL_ENGINEERING. Giá trị nhận dạng "threatType" cho biết kiểu mối đe doạ hiện tại. Giá trị nhận dạng "ThreatType" đề cập đến tập hợp tất cả các kiểu mối đe doạ có thể xảy ra.

Bộ lọc "threatType in [ ThreatType.UNWANTED_SOFTWARE, ThreatType.MALWARE ]" yêu cầu kiểu mối đe doạ phải là UNWANTED_SOFTWARE hoặc MALWARE.

Nội dung yêu cầu

Nội dung yêu cầu phải trống.

Nội dung phản hồi

Phản hồi được trả về sau khi tìm kiếm hàm băm về mối đe doạ.

Nếu không tìm thấy kết quả nào, máy chủ sẽ trả về trạng thái OK (mã trạng thái HTTP 200) với trường fullHashes trống, thay vì trả về trạng thái NOT_FOUND (mã trạng thái HTTP 404).

Tính năng mới trong phiên bản 5: Có sự khác biệt giữa FullHash và FullHashDetail. Trong trường hợp hàm băm đại diện cho một trang web có nhiều mối đe doạ (ví dụ: cả MALWARE và SOCIAL_EngineERING), thì bạn không cần gửi hàm băm đầy đủ hai lần như trong phiên bản 4. Ngoài ra, thời lượng bộ nhớ đệm đã được đơn giản hoá thành một trường cacheDuration duy nhất.

Nếu thành công, phần nội dung phản hồi sẽ chứa dữ liệu có cấu trúc sau:

Biểu diễn dưới dạng JSON 
{
  "fullHashes": [
    {
      object (FullHash)
    }
  ],
  "cacheDuration": string
}
Trường
fullHashes[]

object (FullHash)

Danh sách không theo thứ tự. Đã tìm thấy danh sách hàm băm đầy đủ không theo thứ tự.
cacheDuration

string (Duration format)

Thời lượng bộ nhớ đệm phía máy khách. Ứng dụng PHẢI thêm thời lượng này vào thời gian hiện tại để xác định thời gian hết hạn. Sau đó, thời gian hết hạn sẽ áp dụng cho mọi tiền tố hàm băm mà ứng dụng truy vấn trong yêu cầu, bất kể có bao nhiêu hàm băm đầy đủ được trả về trong phản hồi. Ngay cả khi máy chủ không trả về toàn bộ hàm băm cho một tiền tố hàm băm cụ thể, thì thông tin này cũng PHẢI được ứng dụng lưu vào bộ nhớ đệm.

Nếu và chỉ khi trường fullHashes trống, ứng dụng CÓ THỂ tăng cacheDuration để xác định thời điểm hết hạn mới muộn hơn thời gian mà máy chủ chỉ định. Trong mọi trường hợp, thời lượng của bộ nhớ đệm tăng lên không được dài hơn 24 giờ.

Quan trọng: ứng dụng KHÔNG ĐƯỢC giả định rằng máy chủ sẽ trả về cùng một thời lượng bộ nhớ đệm cho tất cả phản hồi. Tuỳ vào tình huống, máy chủ CÓ THỂ chọn thời lượng bộ nhớ đệm khác nhau cho các phản hồi khác nhau.

Thời lượng tính bằng giây với tối đa 9 chữ số phân số, kết thúc bằng "s". Ví dụ: "3.5s".

FullHash

Giá trị băm đầy đủ được xác định bằng một hoặc nhiều kết quả trùng khớp.

Biểu diễn dưới dạng JSON 
{
  "fullHash": string,
  "fullHashDetails": [
    {
      object (FullHashDetail)
    }
  ]
}
Trường
fullHash

string (bytes format)

Hàm băm đầy đủ phù hợp. Đây là hàm băm SHA256. Độ dài sẽ chính xác là 32 byte.

Chuỗi được mã hoá base64.
fullHashDetails[]

object (FullHashDetail)

Danh sách không theo thứ tự. Một trường lặp lại để xác định thông tin liên quan đến toàn bộ hàm băm này.

FullHashDetail

Thông tin chi tiết về hàm băm đầy đủ trùng khớp.

Lưu ý quan trọng về khả năng tương thích chuyển tiếp: máy chủ có thể thêm các kiểu mối đe doạ và mối đe doạ mới bất cứ lúc nào; những nội dung bổ sung đó được coi là thay đổi nhỏ về phiên bản. Google có chính sách không tiết lộ số phiên bản nhỏ trong API (xem https://cloud.google.com/apis/design/versioning để biết chính sách về phiên bản), vì vậy, ứng dụng PHẢI chuẩn bị nhận thông báo FullHashDetail chứa giá trị enum ThreatType hoặc giá trị enum ThreatAttribute mà ứng dụng coi là không hợp lệ. Do đó, ứng dụng có trách nhiệm kiểm tra tính hợp lệ của tất cả giá trị enum ThreatType và ThreatAttribute; nếu có bất kỳ giá trị nào bị coi là không hợp lệ, thì ứng dụng PHẢI bỏ qua toàn bộ thông báo FullHashDetail.

Biểu diễn dưới dạng JSON 
{
  "threatType": enum (ThreatType),
  "attributes": [
    enum (ThreatAttribute)
  ]
}
Trường
threatType

enum (ThreatType)

Loại mối đe doạ. Trường này sẽ không bao giờ trống.
attributes[]

enum (ThreatAttribute)

Danh sách không theo thứ tự. Các thuộc tính bổ sung cho các hàm băm đầy đủ đó. Bạn có thể để trống trường này.

ThreatAttribute

Đặc điểm của các mối đe doạ. Những thuộc tính này có thể mang lại ý nghĩa bổ sung cho một mối đe doạ cụ thể nhưng không ảnh hưởng đến loại mối đe doạ đó. Ví dụ: một thuộc tính có thể chỉ định độ tin cậy thấp hơn trong khi một thuộc tính khác có thể chỉ định độ tin cậy cao hơn. Các thuộc tính khác có thể được thêm trong tương lai.

Enum
THREAT_ATTRIBUTE_UNSPECIFIED Thuộc tính không xác định. Nếu được máy chủ trả về, ứng dụng phải bỏ qua FullHashDetail đi kèm.
CANARY Cho biết không nên sử dụng loại mối đe doạ để thực thi.
FRAME_ONLY Cho biết rằng chỉ nên dùng mối đe doạ để thực thi đối với khung.