Method: hashes.search

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

Đây là một phương thức tuỳ chỉnh theo định nghĩa của https://google.aip.dev/136 (phương thức tuỳ chỉnh đề cập đến phương thức này có tên tuỳ chỉnh trong quy tắc đặt tên chung khi phát triển API 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/v5/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. Tiền tố hàm băm cần tra cứu. Ứng dụng KHÔNG ĐƯỢC gửi quá 1.000 tiền tố băm. Tuy nhiên, theo quy trình xử lý URL, các ứng dụng KHÔNG NÊN cần gửi quá 30 tiền tố băm.

Hiện tại, mỗi tiền tố băm phải có chính xác 4 byte. Quy định này CÓ THỂ được nới lỏng trong tương lai.

Một chuỗi được mã hoá base64.

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 mối đe doạ.

Nếu không tìm thấy nội dung 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ự tách biệt giữa FullHash và FullHashDetail. Trong trường hợp một hàm băm đại diện cho một trang web có nhiều mối đe doạ (ví dụ: cả PHẦN MỀM ĐỘC HẠI và KỸ THUẬT TẤN CÔNG DỰA TRÊN XÃ HỘI), bạn không cần gửi toàn bộ hàm băm hai lần như trong phiên bản 4. Ngoài ra, thời lượng lưu vào 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ự. Danh sách băm đầy đủ không theo thứ tự được tìm thấy.
cacheDuration

string (Duration format)

Thời lượng bộ nhớ đệm phía máy khách. Ứng dụng phải thêm khoảng thời gian 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ố băm mà ứng dụng khách truy vấn trong yêu cầu, bất kể có bao nhiêu giá trị băm đầy đủ được trả về trong phản hồi. Ngay cả khi máy chủ không trả về hàm băm đầy đủ cho một tiền tố hàm băm cụ thể, thì ứng dụng cũng PHẢI lưu trữ thông tin này vào bộ nhớ đệm.

Nếu và chỉ khi trường fullHashes trống, thì ứng dụng CÓ THỂ tăng cacheDuration để xác định thời gian hết hạn mới muộn hơn thời gian do máy chủ chỉ định. Trong mọi trường hợp, thời gian lưu vào 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 khoảng thời gian lưu vào bộ nhớ đệm cho tất cả các phản hồi. Máy chủ CÓ THỂ chọn thời lượng lưu vào bộ nhớ đệm khác nhau cho các phản hồi khác nhau tuỳ thuộc vào tình huống.

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

FullHash

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)

Giá trị băm đầy đủ trùng khớp. Đây là hàm băm SHA256. Độ dài sẽ chính xác là 32 byte.

Một 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 các thông tin chi tiết liên quan đến hàm băm đầy đủ này.

FullHashDetail

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

Một 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 loại mối đe doạ và thuộc tính mối đe doạ mới bất cứ lúc nào; những nội dung bổ sung đó được coi là các thay đổi nhỏ về phiên bản. Theo chính sách của Google, các số phiên bản phụ sẽ không xuất hiện trong API (xem https://cloud.google.com/apis/design/versioning để biết chính sách về việc tạo phiên bản). Do đó, các ứng dụng phải chuẩn bị sẵn sàng để nhận các thông báo FullHashDetail chứa các giá trị enum ThreatType hoặc các giá trị enum ThreatAttribute mà ứng dụng coi là không hợp lệ. Do đó, máy khách có trách nhiệm kiểm tra tính hợp lệ của tất cả các giá trị enum ThreatType và ThreatAttribute; nếu bất kỳ giá trị nào được coi là không hợp lệ, thì máy khách 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 về những hàm băm đầy đủ đó. Bạn có thể để trống trường này.

ThreatAttribute

Thuộc tính của các mối đe doạ. Các thuộc tính này có thể mang thêm ý nghĩa cho một mối đe doạ cụ thể nhưng sẽ 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. Sau này, chúng tôi có thể thêm các thuộc tính khác.

Enum
THREAT_ATTRIBUTE_UNSPECIFIED Thuộc tính không xác định. Nếu máy chủ trả về giá trị này, thì ứng dụng sẽ hoàn toàn bỏ qua FullHashDetail bao quanh.
CANARY Cho biết rằng không nên sử dụng threatType để thực thi.
FRAME_ONLY Cho biết rằng threatType chỉ nên được dùng để thực thi trên các khung hình.