Package google.security.safebrowsing.v5alpha1

索引

• SafeBrowsing (介面)
• BatchGetHashListsRequest (訊息)
• BatchGetHashListsResponse (訊息)
• FullHash (訊息)
• FullHash.FullHashDetail (訊息)
• GetHashListRequest (訊息)
• HashList (訊息)
• HashListMetadata (訊息)
• HashListMetadata.HashLength (列舉)
• LikelySafeType (列舉)
• ListHashListsRequest (訊息)
• ListHashListsResponse (訊息)
• RiceDeltaEncoded128Bit (訊息)
• RiceDeltaEncoded256Bit (訊息)
• RiceDeltaEncoded32Bit (訊息)
• RiceDeltaEncoded64Bit (訊息)
• SearchHashesRequest (訊息)
• SearchHashesResponse (訊息)
• SearchUrlsRequest (訊息)
• SearchUrlsResponse (訊息)
• SizeConstraints (訊息)
• ThreatAttribute (列舉)
• ThreatType (列舉)
• ThreatUrl (訊息)

安全瀏覽

用戶端可透過 Safe Browsing API，根據 Google 持續更新的不安全網頁資源清單，檢查網頁資源 (最常見的是網址)。

BatchGetHashLists
rpc BatchGetHashLists(BatchGetHashListsRequest) returns (BatchGetHashListsResponse) 一次取得多個雜湊清單。 用戶端通常需要取得多個雜湊清單。建議使用這個方法，而非多次使用一般 Get 方法。 這是 https://google.aip.dev/231 定義的標準批次 Get 方法，HTTP 方法也是 GET。

GetHashList
rpc GetHashList(GetHashListRequest) returns (HashList) 取得雜湊清單的最新內容。雜湊清單可能是威脅清單，也可能不是威脅清單，例如全域快取。 這是 https://google.aip.dev/131 定義的標準 Get 方法，HTTP 方法也是 GET。

ListHashLists
rpc ListHashLists(ListHashListsRequest) returns (ListHashListsResponse) 列出雜湊清單。 在 V5 API 中，Google 絕不會移除這個方法傳回的任何雜湊清單。這可讓用戶端略過使用這個方法，直接將所需的所有雜湊清單硬式編碼。 這是 https://google.aip.dev/132 定義的標準 List 方法，HTTP 方法為 GET。

SearchHashes
rpc SearchHashes(SearchHashesRequest) returns (SearchHashesResponse) 搜尋與指定前置字串相符的完整雜湊。 這是自訂方法，定義於 https://google.aip.dev/136 (自訂方法是指這個方法在 Google 一般 API 開發命名法中具有自訂名稱，並非指使用自訂 HTTP 方法)。

SearchUrls
rpc SearchUrls(SearchUrlsRequest) returns (SearchUrlsResponse) 搜尋與已知威脅相符的網址。系統會檢查每個網址，以及主機後置字串和路徑前置字串運算式 (深度有限)。也就是說，回應可能包含要求中未列出的網址，但這些網址是所要求網址的運算式。

BatchGetHashListsRequest

同時取得多個雜湊清單的要求。

欄位
names[]	string 必填。特定雜湊清單的名稱。清單「可能」是威脅清單，也可能是全域快取。名稱不得重複，否則用戶端會收到錯誤訊息。
version[]	bytes 用戶端已有的雜湊清單版本。如果這是用戶端第一次擷取雜湊清單，這個欄位應留空。否則，用戶端應提供先前從伺服器收到的版本。用戶端「不得」操縱這些位元組。 用戶端不必按照對應清單名稱的順序傳送版本。用戶端在要求中傳送的版本數量可能少於或多於名稱數量。不過，用戶端不得傳送對應相同名稱的多個版本，否則會收到錯誤訊息。 歷史記錄：在 API V4 中，這稱為 states；現在為了清楚起見，已重新命名為 version。
size_constraints	SizeConstraints 各清單的大小限制。如果省略，則沒有限制。請注意，這裡顯示的是每個清單的大小，而非所有清單的總和。

BatchGetHashListsResponse

包含多個雜湊清單的回應。

欄位
hash_lists[]	HashList 雜湊清單的順序與要求中提供的順序相同。

FullHash

與一或多個相符項目相符的完整雜湊值。

欄位
full_hash	bytes 相符的完整雜湊值。這是 SHA256 雜湊。長度剛好是 32 個位元組。
full_hash_details[]	FullHashDetail 未排序的清單。重複欄位，用於識別與這個完整雜湊相關的詳細資料。

FullHashDetail

相符完整雜湊的詳細資料。

前向相容性重要注意事項：伺服器隨時可能新增威脅類型和威脅屬性，這些新增項目視為次要版本變更。根據 Google 政策，API 不會公開子版本號碼 (請參閱 https://cloud.google.com/apis/design/versioning 的版本控管政策)，因此用戶端必須準備好接收含有 ThreatType 列舉值或用戶端視為無效的 ThreatAttribute 列舉值的 FullHashDetail 訊息。因此，用戶端有責任檢查所有 ThreatType 和 ThreatAttribute 列舉值的有效性；如果任何值無效，用戶端「必須」忽略整個 FullHashDetail 訊息。

欄位
threat_type	ThreatType 威脅類型，這個欄位絕不會空白。
attributes[]	ThreatAttribute 未排序的清單。這些完整雜湊的其他屬性。這個值可能為空。

GetHashListRequest

取得雜湊清單的要求，可能是威脅清單或非威脅清單，例如全域快取。

第 5 版的新功能：為求清楚起見，第 4 版中原先稱為 states 的項目已重新命名為 version。清單現在會命名，並移除平台類型和威脅項目類型。現在多個清單可以有相同的威脅類型，單一清單也可以處理多種威脅類型。相較於 V4 的可變長度雜湊前置字串，這項功能在許多用戶端實作中造成問題，現在名單中的所有雜湊都具有單一長度，可大幅提升用戶端實作效率。簡化限制，並移除壓縮類型 (一律會套用壓縮)。

欄位
name	string 必填。這個特定雜湊清單的名稱。可能是威脅清單，也可能是全域快取。
version	bytes 用戶端已有的雜湊清單版本。如果這是用戶端第一次擷取雜湊清單，這個欄位「必須」留空。否則，用戶端「應」提供先前從伺服器收到的版本。用戶端「不得」操縱這些位元組。 第 5 版的新功能：在第 4 版 API 中，這項功能稱為 states，現在為求清楚起見，已重新命名為 version。
size_constraints	SizeConstraints 清單的大小限制。如果省略，則沒有限制。建議在處理能力、頻寬或儲存空間有限的所有裝置上使用限制。

HashList

以名稱識別的雜湊清單。

欄位
name	string 雜湊清單的名稱。請注意，全域快取也只是一個雜湊清單，可在此參照。
version	bytes 雜湊清單的版本。用戶端「不得」操縱這些位元組。
partial_update	bool 如果為 true，這就是部分差異，其中包含根據用戶端現有內容新增和移除的項目。如果為 false，則這是完整的雜湊清單。 如果為 false，用戶端「必須」刪除這個雜湊清單的所有本機儲存版本。這表示用戶端擁有的版本嚴重過時，或用戶端資料可能已損毀。「compressed_removals」欄位會空白。 如果為 true，用戶端「必須」先移除項目，再新增項目，以套用增量更新。
compressed_removals	RiceDeltaEncoded32Bit 移除索引的 Rice-delta 編碼版本。由於每個雜湊清單的項目絕對少於 2^32 個，因此索引會視為 32 位元整數並進行編碼。
minimum_wait_duration	Duration 用戶端應等待至少這麼長的時間，再重新取得雜湊清單。如果省略或為零，用戶端應立即擷取，因為這表示伺服器有額外更新要傳送至用戶端，但因用戶端指定的限制而無法傳送。
sha256_checksum	bytes 所有雜湊的排序清單，並再次以 SHA256 雜湊處理。這是指套用提供的更新後，資料庫中所有雜湊的排序清單檢查碼。如果沒有提供更新，伺服器會省略這個欄位，表示用戶端應使用現有的檢查碼。
metadata	HashListMetadata 雜湊清單的中繼資料。這不會由 GetHashList 方法填入，但會由 ListHashLists 方法填入。
聯集欄位 compressed_additions。新增內容的 Rice-delta 編碼版本。清單中所有新增項目的雜湊前置字串長度都相同。compressed_additions 只能是下列其中一項：
additions_four_bytes	RiceDeltaEncoded32Bit 新增的 4 個位元組。
additions_eight_bytes	RiceDeltaEncoded64Bit 新增的 8 個位元組。
additions_sixteen_bytes	RiceDeltaEncoded128Bit 新增的 16 個位元組。
additions_thirty_two_bytes	RiceDeltaEncoded256Bit 新增 32 個位元組。

HashListMetadata

特定雜湊清單的中繼資料。

欄位
threat_types[]	ThreatType 未排序的清單。如果不是空白，則表示雜湊清單是某種威脅清單，並列舉與這個雜湊清單中雜湊或雜湊前置字串相關聯的威脅類型。如果項目不代表威脅 (即代表可能是安全類型)，則可能為空白。
likely_safe_types[]	LikelySafeType 未排序的清單。如果不是空白，這表示雜湊清單代表可能安全的雜湊清單，並列舉這些雜湊被視為可能安全的方式。這個欄位與 threat_types 欄位互斥。
description	string 這份清單的使用者可理解說明。以英文撰寫。
hash_length	HashLength 這份雜湊清單支援的雜湊長度。每個雜湊清單只能支援一個長度。如果同一組威脅類型或安全類型採用不同的雜湊長度，系統會以獨立清單的形式推出，並設定不同的名稱和雜湊長度。

HashLength

雜湊清單中的雜湊長度。

列舉
HASH_LENGTH_UNSPECIFIED	長度不明。
FOUR_BYTES	每個雜湊都是四位元組的前置字元。
EIGHT_BYTES	每個雜湊都是八位元組的前置字元。
SIXTEEN_BYTES	每個雜湊都是十六位元組的前置字元。
THIRTY_TWO_BYTES	每個雜湊都是三十二位元組的完整雜湊。

LikelySafeType

可能安全的網站類型。

請注意，SearchHashesResponse 刻意不包含 LikelySafeType。

列舉
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 傳送的權杖，用於擷取後續網頁。如果省略這個欄位，就不會有後續頁面。

RiceDeltaEncoded128Bit

與 RiceDeltaEncoded32Bit 相同，但會編碼 128 位元數字。

欄位
first_value_hi	uint64 編碼資料 (雜湊) 中第一個項目的前 64 位元。如果該欄位為空白，則高位 64 位元全為零。
first_value_lo	fixed64 編碼資料 (雜湊) 中第一個項目的低位元 64 位元。如果該欄位為空白，則低 64 位元全為零。
rice_parameter	int32 Golomb-Rice 參數。這個參數保證介於 99 和 126 之間 (含首尾)。
entries_count	int32 編碼資料中經過差異編碼的項目數。如果只編碼一個整數，這個值會是零，而單一值會儲存在 first_value 中。
encoded_data	bytes 使用 Golomb-Rice 編碼器編碼的編碼差異。

RiceDeltaEncoded256Bit

與 RiceDeltaEncoded32Bit 相同，但會編碼 256 位元數字。

欄位
first_value_first_part	uint64 編碼資料 (雜湊) 中第一個項目的前 64 位元。如果該欄位為空白，則前 64 位元全為零。
first_value_second_part	fixed64 編碼資料 (雜湊) 中第一個項目的第 65 到 128 位元。如果該欄位為空白，第 65 到 128 個位元全為零。
first_value_third_part	fixed64 編碼資料 (雜湊) 中第一個項目的第 129 到 192 位元。如果該欄位為空白，第 129 到 192 位元全為零。
first_value_fourth_part	fixed64 編碼資料 (雜湊) 中第一個項目的最後 64 位元。如果該欄位為空白，最後 64 位元全為零。
rice_parameter	int32 Golomb-Rice 參數。此參數保證介於 227 到 254 之間 (含首尾)。
entries_count	int32 編碼資料中經過差異編碼的項目數。如果只編碼一個整數，這個值會是零，而單一值會儲存在 first_value 中。
encoded_data	bytes 使用 Golomb-Rice 編碼器編碼的編碼差異。

RiceDeltaEncoded32Bit

Rice-Golomb 編碼資料。用於雜湊或移除索引。保證這裡的每個雜湊或索引長度都相同，且長度正好是 32 位元。

一般來說，如果我們依字典順序排序所有項目，會發現高位元不像低位元那樣經常變更。也就是說，如果我們也採用相鄰項目的差異，高位元很可能為零。這項技術會選擇特定位元，藉此利用高機率的零值；所有比這更重要的位元都可能為零，因此我們使用一元編碼。請參閱 rice_parameter 欄位。

歷史記錄：Rice-delta 編碼最初是在這個 API 的第 4 版中使用。V5 版有兩項重大改良：首先，現在可使用長度超過 4 個位元組的雜湊前置字串進行 Rice-delta 編碼；其次，編碼資料現在會視為大端序，以避免耗費資源的排序步驟。

欄位
first_value	uint32 編碼資料 (雜湊或索引) 中的第一個項目，或如果只編碼單一雜湊前置字串或索引，則為該項目的值。如果欄位空白，則項目為零。
rice_parameter	int32 Golomb-Rice 參數。這個參數保證介於 3 到 30 之間 (含首尾)。
entries_count	int32 編碼資料中經過差異編碼的項目數。如果只編碼一個整數，這個值會是零，而單一值會儲存在 first_value 中。
encoded_data	bytes 使用 Golomb-Rice 編碼器編碼的編碼差異。

RiceDeltaEncoded64Bit

與 RiceDeltaEncoded32Bit 相同，但會編碼 64 位元數字。

欄位
first_value	uint64 編碼資料 (雜湊) 中的第一個項目，或如果只編碼單一雜湊前置字串，則為該項目的值。如果欄位空白，則項目為零。
rice_parameter	int32 Golomb-Rice 參數。這個參數保證介於 35 到 62 之間 (含首尾)。
entries_count	int32 編碼資料中經過差異編碼的項目數。如果只編碼一個整數，這個值會是零，而單一值會儲存在 first_value 中。
encoded_data	bytes 使用 Golomb-Rice 編碼器編碼的編碼差異。

SearchHashesRequest

用戶端發出的要求，用於搜尋特定雜湊前置字元。

這項功能只會搜尋威脅清單，不會搜尋非威脅清單，例如全域快取。

V5 的新功能：用戶端不必在本地資料庫中指定 ClientInfo 或雜湊清單的狀態。這是為了提升隱私權。此外，用戶端不必傳送感興趣的威脅類型。

欄位
hash_prefixes[]	bytes 必填。要查詢的雜湊前置字元。用戶端不得傳送超過 1000 個雜湊前置字元。不過，按照網址處理程序，用戶端「不應」需要傳送超過 30 個雜湊前置字元。 目前每個雜湊前置字串的長度必須剛好為 4 個位元組。這項限制日後可能會放寬。
filter	string (選用步驟) 如果用戶想進行篩選，例如只擷取特定類型的威脅，可以指定篩選條件。如果省略，系統會傳回所有相符的威脅。強烈建議您省略這項設定，以獲得安全瀏覽提供的最完整防護。 篩選器是使用 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)，則不必像 V4 一樣傳送兩次完整雜湊。此外，快取時間長度已簡化為單一 cache_duration 欄位。

欄位
full_hashes[]	FullHash 未排序的清單。找到的完整雜湊無序清單。
cache_duration	Duration 用戶端快取時間長度。用戶端「必須」將這段時間加到目前時間，以判斷到期時間。之後，無論回應中傳回多少完整雜湊，用戶端在要求中查詢的每個雜湊前置字串都會套用這個到期時間。即使伺服器未針對特定雜湊前置字串傳回任何完整雜湊，用戶端也「必須」快取這項事實。 只有在 full_hashes 欄位空白時，用戶端才可增加 cache_duration，以判斷晚於伺服器指定時間的新到期時間。無論如何，增加的快取時間不得超過 24 小時。 重要事項：用戶端「不得」假設伺服器會為所有回應傳回相同的快取時間長度。伺服器可視情況為不同回應選擇不同的快取時間長度。

SearchUrlsRequest

用戶端發出的要求，用於搜尋符合指定網址的威脅。

這項功能只會搜尋威脅清單，不會搜尋非威脅清單，例如全域快取。

欄位
urls[]	string 必填。要查詢的網址。用戶端不得傳送超過 50 個網址。

SearchUrlsResponse

搜尋與指定網址相符的威脅後，系統傳回的回應。

如果找不到任何內容，伺服器會傳回 OK 狀態 (HTTP 狀態碼 200)，且 threats 欄位為空白，而不是傳回 NOT_FOUND 狀態 (HTTP 狀態碼 404)。

欄位
threats[]	ThreatUrl 未排序的清單。找到的威脅比對結果 (無序清單)。每個項目都包含一個網址，以及與該網址相符的威脅類型。清單大小可能大於要求中的網址數量，因為系統會考量網址的所有運算式。
cache_duration	Duration 用戶端快取時間長度。用戶端「必須」將這段時間加到目前時間，以判斷到期時間。之後，無論回應中傳回多少網址，用戶端在要求中查詢的每個網址都會套用這個到期時間。即使伺服器未傳回特定網址的相符項目，用戶端也「必須」快取這項事實。 只有在 threats 欄位空白時，用戶端才可增加 cache_duration，以判斷晚於伺服器指定時間的新到期時間。無論如何，增加的快取時間不得超過 24 小時。 重要事項：用戶端「不得」假設伺服器會為所有回應傳回相同的快取時間長度。伺服器可視情況為不同回應選擇不同的快取時間長度。

SizeConstraints

雜湊清單大小的限制。

欄位
max_update_entries	int32 項目數量上限。更新內容的項目數量不會超過這個值，但可能少於這個值。這個值「必須」至少為 1024。如果省略或設為零，系統就不會設定更新大小限制。
max_database_entries	int32 設定用戶端願意在清單的本機資料庫中保留的項目數量上限。(伺服器可能會導致用戶端儲存的項目少於這個數字)。如果省略或設為零，就不會設定資料庫大小限制。

ThreatAttribute

威脅的屬性。這些屬性可能會為特定威脅賦予額外意義，但不會影響威脅類型。舉例來說，某個屬性可能指定較低的信賴度，而另一個屬性可能指定較高的信賴度。日後可能會新增更多屬性。

列舉
THREAT_ATTRIBUTE_UNSPECIFIED	不明屬性。如果伺服器傳回這個值，用戶端應完全忽略封閉的 FullHashDetail。
CANARY	表示不應使用 threat_type 進行強制執行。
FRAME_ONLY	指出 threat_type 僅適用於對影格強制執行。

ThreatType

威脅類型。

列舉
THREAT_TYPE_UNSPECIFIED	威脅類型不明。如果伺服器傳回這個值，用戶端應完全忽略封閉的 FullHashDetail。
MALWARE	惡意軟體威脅類型。只要軟體或行動應用程式會刻意危害電腦、行動裝置、這些裝置執行的軟體或其使用者，就屬於惡意軟體。惡意軟體的危害行為包括：未經使用者同意便擅自安裝軟體，以及安裝病毒等有害軟體。 詳情請參閱這篇文章。
SOCIAL_ENGINEERING	社交工程威脅類型。社交工程頁面會假冒第三方，意圖混淆觀眾，誘騙他們採取行動，而觀眾只會信任該第三方的真正代理人。網路釣魚是一種社交工程，會誘騙觀眾提供資訊 (例如登入憑證)。 詳情請參閱這篇文章。
UNWANTED_SOFTWARE	垃圾軟體威脅類型。垃圾軟體是指違反 Google 軟體規範，但並非惡意軟體的軟體。
POTENTIALLY_HARMFUL_APPLICATION	可能有害的應用程式威脅類型，Google Play 安全防護會用於 Play 商店。

ThreatUrl

網址符合一或多項威脅。

欄位
url	string 與一或多項威脅相符的要求網址。
threat_types[]	ThreatType 未排序的清單。網址分類為無序清單的威脅。