Trang này được dịch bởi Cloud Translation API.

API cập nhật tính năng Duyệt web an toàn (v4)

Tổng quan

Update API cho phép các ứng dụng khách của bạn tải xuống các phiên bản đã băm của danh sách Duyệt web an toàn cho trong cơ sở dữ liệu cục bộ. Sau đó, bạn có thể kiểm tra URL cục bộ. Chỉ khi tìm thấy kết quả trùng khớp trong cơ sở dữ liệu cục bộ, ứng dụng mới cần gửi yêu cầu đến máy chủ Duyệt web an toàn để xác minh xem URL có nằm trong danh sách của Duyệt web an toàn hay không.

Trước khi sử dụng Update API, bạn cần thiết lập cơ sở dữ liệu cục bộ. Tính năng Duyệt web an toàn cung cấp một gói Go mà bạn có thể sử dụng để bắt đầu. Để biết thêm thông tin chi tiết, hãy xem phần Thiết lập cơ sở dữ liệu trong phần Cơ sở dữ liệu cục bộ.

Cập nhật cơ sở dữ liệu cục bộ

Để luôn cập nhật, ứng dụng phải định kỳ cập nhật danh sách của tính năng Duyệt web an toàn trong cơ sở dữ liệu cục bộ. Để tiết kiệm băng thông, ứng dụng sẽ tải các tiền tố băm của URL thay vì tải các URL thô. Ví dụ: nếu "www.badurl.com/" nằm trong danh sách Tìm kiếm an toàn, thì ứng dụng sẽ tải tiền tố băm SHA256 của URL đó thay vì chính URL đó. Trong hầu hết các trường hợp, tiền tố hàm băm có độ dài 4 byte, nghĩa là chi phí băng thông trung bình để tải một mục danh sách xuống là 4 byte trước khi nén.

Để cập nhật danh sách của tính năng Duyệt web an toàn trong cơ sở dữ liệu cục bộ, hãy gửi yêu cầu POST HTTP đến phương thức threatListUpdates.fetch:

Yêu cầu POST HTTP bao gồm tên của các danh sách cần cập nhật cùng với nhiều điều kiện ràng buộc của ứng dụng để tính đến các giới hạn về bộ nhớ và băng thông.
Phản hồi HTTP POST trả về bản cập nhật đầy đủ hoặc bản cập nhật một phần. Phản hồi cũng có thể trả về thời gian chờ tối thiểu.

Ví dụ: threatListUpdates.fetch

Yêu cầu POST qua HTTP

Trong ví dụ sau, các yêu cầu cập nhật cho một danh sách Duyệt web an toàn.

Tiêu đề yêu cầu

Tiêu đề yêu cầu bao gồm URL yêu cầu và loại nội dung. Hãy nhớ thay thế khoá API cho API_KEY trong URL.

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

Nội dung yêu cầu

Nội dung yêu cầu bao gồm thông tin ứng dụng (mã và phiên bản) và thông tin cập nhật (mã tên danh sách, trạng thái danh sách và giới hạn của ứng dụng khách). Để biết thêm thông tin, hãy xem phần nội dung yêu cầu threatListUpdates.fetch và nội dung giải thích theo sau ví dụ về mã.

{
  "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"]
    }
  }]
}

Thông tin khách hàng

Các trường clientID và clientVersion phải xác định duy nhất một cách triển khai ứng dụng, chứ không phải một người dùng cá nhân. (Thông tin ứng dụng được dùng trong tính năng ghi nhật ký phía máy chủ. Bạn có thể chọn bất kỳ tên nào cho mã ứng dụng khách, nhưng bạn nên chọn một tên thể hiện danh tính thực của khách hàng của bạn, ví dụ như tên công ty, được trình bày dưới dạng tất cả một từ, bằng chữ thường.)

Danh sách của tính năng Duyệt web an toàn

Các trường threatType, platformType và threatEntryType được kết hợp để xác định (tên) các danh sách của tính năng Duyệt web an toàn. Trong ví dụ này, một danh sách được xác định: MALWARE/WINDOWS/URL. Trước khi gửi yêu cầu, hãy đảm bảo rằng các tổ hợp loại mà bạn chỉ định là hợp lệ (xem Danh sách của tính năng Duyệt web an toàn).

Trạng thái ứng dụng

Trường state lưu giữ trạng thái ứng dụng hiện tại trong danh sách Duyệt web an toàn. (Trạng thái ứng dụng được trả về trong trường newClientState của phản hồithreatListUpdates.fetch.) Đối với những lần cập nhật đầu tiên, hãy để trống trường state.

Quy tắc ràng buộc về kích thước

Trường maxUpdateEntries chỉ định tổng số bản cập nhật mà ứng dụng có thể quản lý (tính bằng ví dụ: 2048). Trường maxDatabaseEntries chỉ định tổng số mục nhập mà cơ sở dữ liệu cục bộ có thể quản lý (trong ví dụ là 4096). Khách hàng nên đặt giới hạn về kích thước để bảo vệ các giới hạn bộ nhớ và băng thông cũng như để chống lại danh sách tăng trưởng. Để biết thêm thông tin, (xem phần Cập nhật giới hạn).

Các định dạng nén được hỗ trợ

Trường supportedCompressions liệt kê các loại nén mà ứng dụng hỗ trợ. Trong ví dụ này, ứng dụng chỉ hỗ trợ dữ liệu thô, không nén. Tuy nhiên, Duyệt web an toàn hỗ trợ thêm (xem phần Nén).

Phản hồi HTTP POST

Trong ví dụ này, phản hồi sẽ trả về một phần nội dung cập nhật cho danh sách Duyệt web an toàn bằng cách sử dụng loại nén đã yêu cầu.

Tiêu đề phản hồi

Tiêu đề phản hồi có mã trạng thái HTTP và loại nội dung. Các ứng dụng nhận được mã trạng thái không phải là HTTP/200 phải chuyển sang chế độ đợi (xem Tần suất yêu cầu).

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

Nội dung phản hồi

Nội dung phản hồi bao gồm thông tin cập nhật (tên danh sách, loại phản hồi, bổ sung và loại bỏ sẽ được áp dụng cho cơ sở dữ liệu cục bộ, ứng dụng mới trạng thái và một giá trị tổng kiểm). Trong ví dụ này, phản hồi cũng bao gồm thời gian chờ tối thiểu. Để biết thêm thông tin chi tiết, hãy xem nội dung phản hồi threatListUpdates.fetch và nội dung giải thích theo sau ví dụ về mã.

{
  "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"
}

Nội dung cập nhật về cơ sở dữ liệu

Trường responseType sẽ cho biết nội dung cập nhật một phần hay toàn bộ. Trong ví dụ này, một phần cập nhật sẽ được trả về, vì vậy, phản hồi sẽ bao gồm cả nội dung thêm và xoá. Có thể có nhiều tập hợp lần bổ sung, nhưng chỉ một nhóm yêu cầu xoá (xem nội dung Cập nhật cơ sở dữ liệu).

Trạng thái ứng dụng mới

Trường newClientState chứa trạng thái ứng dụng mới cho danh sách mới cập nhật của tính năng Tìm kiếm an toàn. Ứng dụng phải lưu trạng thái ứng dụng mới cho các yêu cầu cập nhật tiếp theo (trường state trong threatListUpdates.fetch yêu cầu hoặc trường clientStates trong yêu cầu fullHashes.find).

Giá trị tổng kiểm

Giá trị tổng kiểm cho phép khách hàng xác minh rằng cơ sở dữ liệu cục bộ không bị hỏng. Nếu giá trị tổng kiểm không khớp, máy khách phải xoá cơ sở dữ liệu và phát hành lại bản cập nhật bằng một giá trị trống Trường state. Tuy nhiên, trong trường hợp này, ứng dụng vẫn phải tuân theo khoảng thời gian cập nhật (xem phần Tần suất yêu cầu).

Thời gian chờ tối thiểu

Trường minimumWaitDuration cho biết ứng dụng phải đợi 593,44 giây (9,89 phút) trước khi gửi yêu cầu cập nhật khác. Xin lưu ý rằng khoảng thời gian chờ có thể có hoặc không có trong phản hồi (xem phần Tần suất yêu cầu).

Kiểm tra URL

Để kiểm tra xem một URL có nằm trong danh sách của tính năng Duyệt web an toàn hay không, trước tiên, ứng dụng phải tính toán hàm băm và tiền tố hàm băm của URL (xem phần URL và hàm băm). Khách hàng sau đó truy vấn cơ sở dữ liệu cục bộ để xác định xem có kết quả trùng khớp hay không. Nếu tiền tố hàm băm là không hiện diện trong cơ sở dữ liệu cục bộ, thì URL đó sẽ được coi là an toàn (không nằm trên trang Duyệt qua danh sách).

Nếu có tiền tố hàm băm trong cơ sở dữ liệu cục bộ (xung đột tiền tố hàm băm), ứng dụng phải gửi tiền tố băm đến máy chủ Duyệt web an toàn để xác minh. Các máy chủ sẽ trả về tất cả hàm băm SHA 256 có độ dài đầy đủ có chứa tiền tố hàm băm đã cho. Nếu một trong các hàm băm có độ dài đầy đủ đó khớp với hàm băm đầy đủ của URL đang được đề cập, thì URL đó sẽ bị coi là không an toàn. Nếu không có hàm băm nào đủ thời lượng khớp với hàm băm đầy đủ của URL hữu quan, thì URL đó sẽ được coi là an toàn.

Google không bao giờ biết về những URL mà bạn đang kiểm tra. Google có học hàm băm tiền tố của URL, nhưng các tiền tố băm không cung cấp nhiều thông tin về các URL thực tế.

Để kiểm tra xem một URL có nằm trong danh sách của tính năng Duyệt web an toàn hay không, hãy gửi một yêu cầu POST HTTP đến phương thức fullHashes.find:

Yêu cầu HTTP POST có thể đưa vào tối đa 500 mục nhập mối đe doạ.
Yêu cầu HTTP POST bao gồm các tiền tố băm của URL cần kiểm tra. Bạn nên tạo nhiều mục nhập mối đe doạ thành một lô trong một yêu cầu để giảm mức sử dụng băng thông.
Phản hồi HTTP POST trả về các hàm băm có độ dài đầy đủ phù hợp cùng với các giá trị dương và thời lượng bộ nhớ đệm âm. Phản hồi cũng có thể trả về thời gian chờ tối thiểu.

Ví dụ: fullHashes.find

Yêu cầu POST qua HTTP

Trong ví dụ sau, tên của hai danh sách Duyệt web an toàn và ba tiền tố hàm băm sẽ được gửi để so sánh và xác minh.

Tiêu đề yêu cầu

Tiêu đề yêu cầu bao gồm URL yêu cầu và loại nội dung. Nhớ thay thế khoá API cho API_KEY trong URL.

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

Nội dung yêu cầu

Nội dung yêu cầu bao gồm thông tin về ứng dụng (mã nhận dạng và phiên bản), trạng thái ứng dụng và thông tin về mối đe doạ (tên danh sách và tiền tố hàm băm). Đối với các yêu cầu JSON, tiền tố hàm băm phải được gửi dưới dạng mã hoá base64. Để biết thêm thông tin, hãy xem nội dung yêu cầu fullHashes.find và nội dung giải thích theo sau ví dụ về mã.

{
  "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=="}
    ]
  }
}

Thông tin ứng dụng

Các trường clientID và clientVersion phải xác định duy nhất một cách triển khai ứng dụng, chứ không phải một người dùng cá nhân. (Thông tin ứng dụng được dùng trong tính năng ghi nhật ký phía máy chủ. Bạn có thể chọn bất kỳ tên nào cho client ID, nhưng chúng tôi khuyên bạn nên chọn tên thể hiện danh tính thực của khách hàng, chẳng hạn như tên công ty của bạn, được trình bày toàn bộ từ một từ, bằng chữ thường.)

Tất cả trạng thái ứng dụng

Trường clientStates lưu giữ các trạng thái ứng dụng cho tất cả danh sách Duyệt web an toàn trong cơ sở dữ liệu cục bộ của khách hàng. (Trạng thái ứng dụng được trả về trong trường newClientState của phản hồithreatListUpdates.fetch.)

Danh sách của tính năng Duyệt web an toàn

threatTypes, platformTypes và threatEntryTypes các trường kết hợp để xác định (tên) các trường An toàn Duyệt qua danh sách. Trong ví dụ này, hai danh sách được xác định: MALWARE/WINDOWS/URL và SOCIAL_METHODERING/WINDOWS/URL. Trước khi gửi yêu cầu, hãy đảm bảo rằng các kiểu kết hợp chỉ định là hợp lệ (xem Danh sách duyệt web an toàn).

Tiền tố cho hàm băm về mối đe doạ

MảngMẹoEntries chứa tiền tố băm của những URL mà bạn muốn kiểm tra. Trường hash phải chứa chính xác tiền tố hàm băm có trong cơ sở dữ liệu cục bộ. Để ví dụ: nếu tiền tố hàm băm cục bộ dài 4 byte, thì mục nhập mối đe doạ phải dài 4 byte. Nếu tiền tố hàm băm cục bộ đã được kéo dài thành 7 byte, thì mục nhập mối đe doạ phải dài 7 byte.

Trong ví dụ này, yêu cầu bao gồm 3 tiền tố hàm băm. Cả ba tiền tố sẽ được so sánh dựa vào từng danh sách Duyệt web an toàn để xác định xem có hàm băm toàn thời gian phù hợp hay không.

Lưu ý: Update API và phương thức fullHashes.find phải luôn sử dụng trường hash, không bao gồm trường URL (xem ThreatEntry).

Phản hồi HTTP POST

Trong ví dụ sau, phản hồi sẽ trả về dữ liệu phù hợp, được sắp xếp theo danh sách Duyệt web an toàn, cùng với bộ nhớ đệm và thời gian chờ.

Tiêu đề phản hồi

Tiêu đề phản hồi bao gồm mã trạng thái HTTP và loại nội dung. Các ứng dụng nhận được mã trạng thái khác với HTTP/200 phải đợi (xem phần Tần suất yêu cầu).

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

Nội dung phản hồi

Nội dung phản hồi bao gồm thông tin trùng khớp (tên danh sách và hàm băm đầy đủ độ dài, siêu dữ liệu (nếu có) và thời lượng của bộ nhớ đệm). Trong ví dụ này, nội dung phản hồi cũng bao gồm thời lượng chờ tối thiểu. Để biết thêm thông tin, hãy xem phần phần nội dung phản hồi fullHashes.find và phần giải thích theo sau ví dụ về mã.

{
  "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"
}

Liên kết

Đối tượng Matches trả về một hàm băm có độ dài đầy đủ khớp với hai trong số các tiền tố hàm băm. Các URL tương ứng với các hàm băm này đều được coi là không an toàn. Không tìm thấy kết quả trùng khớp cho tiền tố hàm băm thứ ba, nên không có kết quả nào được trả về; URL tương ứng với tiền tố hàm băm này được coi là an toàn.

Lưu ý rằng ví dụ này khớp một hàm băm có độ dài đầy đủ với một tiền tố hàm băm; tuy nhiên, có thể nhiều hàm băm đầy đủ liên kết với cùng một tiền tố hàm băm.

Metadata

Trường threatEntryMetadata là trường không bắt buộc và cung cấp thêm thông tin về mối đe doạ khớp. Hiện tại, siêu dữ liệu có sẵn cho danh sách MALWARE/WINDOWS/URL trong tính năng Duyệt web an toàn (xem phần Siêu dữ liệu).

Thời lượng bộ nhớ đệm

Trường cacheDuration và negativeCacheDuration cho biết số tiền thời gian thì các hàm băm phải được coi là không an toàn hoặc an toàn (xem bài viết Lưu vào bộ nhớ đệm).

Thời gian chờ tối thiểu

Trường minimumWaitDuration cho biết ứng dụng phải đợi 300 giây (5 phút) trước khi đang gửi một yêu cầu fullHashes khác. Lưu ý rằng thời gian chờ có thể được hoặc không được đưa vào câu trả lời (xem Tần suất yêu cầu).