REST Resource: hashList

資源：HashList

以名稱識別的雜湊清單。

JSON 表示法 
{
  "name": string,
  "version": string,
  "partialUpdate": boolean,
  "compressedRemovals": {
    object (RiceDeltaEncoded32Bit)
  },
  "minimumWaitDuration": string,
  "metadata": {
    object (HashListMetadata)
  },

  // Union field compressed_additions can be only one of the following:
  "additionsFourBytes": {
    object (RiceDeltaEncoded32Bit)
  },
  "additionsEightBytes": {
    object (RiceDeltaEncoded64Bit)
  },
  "additionsSixteenBytes": {
    object (RiceDeltaEncoded128Bit)
  },
  "additionsThirtyTwoBytes": {
    object (RiceDeltaEncoded256Bit)
  }
  // End of list of possible types for union field compressed_additions.

  // Union field checksum can be only one of the following:
  "sha256Checksum": string
  // End of list of possible types for union field checksum.
}
欄位
name

string

雜湊清單的名稱。請注意，全域快取也只是雜湊清單，可以參閱這裡。
version

string (bytes format)

雜湊清單版本。用戶端「不得」操縱這些位元組。

Base64 編碼字串。
partialUpdate

boolean

設為 true 時，僅代表根據用戶端已具備的功能進行新增和移除作業的部分差異。如果為 false，則此為完整的雜湊清單。

如果設為 False，用戶端「必須」刪除這份雜湊清單儲存在本機的任何版本。這表示用戶端擁有的版本非常過時，或是用戶端資料已毀損。compressedRemovals 欄位將留空。

設為 true 時，客戶「必須」先套用移除條件，然後再套用累加更新，以套用漸進式更新。
compressedRemovals

object (RiceDeltaEncoded32Bit)

移除索引的 Rice-delta 編碼版本。由於每個雜湊清單一定會有少於 2^32 個項目，因此索引會被視為 32 位元整數並進行編碼。
minimumWaitDuration

string (Duration format)

用戶端至少應等待這個時間，才能再次取得雜湊清單。如果省略或零，用戶端「必須」立即擷取，因為這表示伺服器還有要傳送至用戶端的額外更新，但由於用戶端指定的限製而無法更新。

持續時間以秒為單位，最多 9 個小數位數，結尾為「s」。範例："3.5s"。
metadata

object (HashListMetadata)

雜湊清單的中繼資料。這不會由 hashList.get 方法填入，但會由 ListHashLists 方法填入。
聯集欄位 compressed_additions。附加內容為 Rice-delta 編碼的版本。清單內所有新增項目的雜湊前置字元長度都相同。它是用戶端傳送的 desired_hash_length，或是用戶端省略該欄位時選擇的值。compressed_additions 只能採用下列其中一種設定：
additionsFourBytes

object (RiceDeltaEncoded32Bit)

額外 4 位元組。
additionsEightBytes

object (RiceDeltaEncoded64Bit)

超過 8 個位元組的新增項目。
additionsSixteenBytes

object (RiceDeltaEncoded128Bit)

額外增加的 16 個位元組。
additionsThirtyTwoBytes

object (RiceDeltaEncoded256Bit)

超過 32 個位元組的額外值。
聯集欄位 checksum。這是套用提供的更新後，資料庫中所有雜湊的排序清單的總和。此為「獨有」] 欄位允許多個雜湊演算法。伺服器也可以省略這個欄位 (如未提供更新)，指出用戶端應使用現有的總和檢查碼。checksum 只能是下列其中一項：
sha256Checksum

string (bytes format)

所有雜湊的排序清單，使用 SHA256 再次進行雜湊處理。

Base64 編碼字串。

RiceDeltaEncoded32Bit

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

一般而言，如果我們按照字母順序排列所有項目，會發現較高順序的位元往往不會與低階位元一樣頻繁發生。這表示若同時得出項目之間的相鄰差異，則較高順序位元的機率很高為零。此攻擊主要透過選擇特定位元數，來濫用這個高度可能為零的攻擊；剛好比 0 高一些，所以可能是零，所以我們要使用一元編碼。請參閱 riceParameter 欄位。

歷史記錄：此 API 的 V4 首次使用 Rice-delta 編碼。V5 做了兩項重大改善：首先，Rice-delta 編碼可用超過 4 個位元組的雜湊前置字元；其次，編碼後的資料現在會視為大端序，以免排列步驟的成本高昂。

JSON 表示法 
{
  "firstValue": integer,
  "riceParameter": integer,
  "entriesCount": integer,
  "encodedData": string
}
欄位
firstValue

integer (uint32 format)

編碼資料的第一個項目 (斜線或索引)；如果只有一個雜湊前置字串或索引，則會傳回該項目的值。如果這個欄位空白，項目就會是 0。
riceParameter

integer

Golomb-Rice 參數。此參數保證介於 3 到 30 (含) 之間。
entriesCount

integer

編碼資料中經過差異編碼的項目數量。如果只編碼一個整數，該值將會是 0，而單一值將儲存在 firstValue 中。
encodedData

string (bytes format)

使用 Golomb-Rice 編碼器編碼的編碼差異值。

Base64 編碼字串。

RiceDeltaEncoded64Bit

與 RiceDeltaEncoded32Bit 相同，差別只在這個編碼會對 64 位元數字進行編碼。

JSON 表示法 
{
  "firstValue": string,
  "riceParameter": integer,
  "entriesCount": integer,
  "encodedData": string
}
欄位
firstValue

string

經過編碼的資料 (含雜湊碼) 中的第一個項目；如果只有單一雜湊前置字元經過編碼，則會改為該項目的值。如果這個欄位空白，項目就會是 0。
riceParameter

integer

Golomb-Rice 參數。此參數保證介於 35 到 62 (含) 之間。
entriesCount

integer

編碼資料中經過差異編碼的項目數量。如果只編碼一個整數，該值將會是 0，而單一值將儲存在 firstValue 中。
encodedData

string (bytes format)

使用 Golomb-Rice 編碼器編碼的編碼差異值。

Base64 編碼字串。

RiceDeltaEncoded128Bit

與 RiceDeltaEncoded32Bit 相同，差別只在這個編碼會編碼 128 位元數字。

JSON 表示法 
{
  "firstValueHi": string,
  "firstValueLo": string,
  "riceParameter": integer,
  "entriesCount": integer,
  "encodedData": string
}
欄位
firstValueHi

string

編碼資料中第一個項目的上方 64 位元 (雜湊)。如果這個欄位空白，則上方 64 位元全為 0。
firstValueLo

string (uint64 format)

編碼資料中第一個項目的 64 位元下限。如果這個欄位空白，則低於 64 位元的位元數均為 0。
riceParameter

integer

Golomb-Rice 參數。此參數保證介於 99 到 126 (含) 之間。
entriesCount

integer

編碼資料中經過差異編碼的項目數量。如果只編碼一個整數，該值將會是 0，而單一值將儲存在 firstValue 中。
encodedData

string (bytes format)

使用 Golomb-Rice 編碼器編碼的編碼差異值。

Base64 編碼字串。

RiceDeltaEncoded256Bit

與 RiceDeltaEncoded32Bit 相同，差別只在這個程式碼會編碼 256 位元數字。

JSON 表示法 
{
  "firstValueFirstPart": string,
  "firstValueSecondPart": string,
  "firstValueThirdPart": string,
  "firstValueFourthPart": string,
  "riceParameter": integer,
  "entriesCount": integer,
  "encodedData": string
}
欄位
firstValueFirstPart

string

編碼資料中第一個項目的前 64 位元 (雜湊)。如果這個欄位空白，前 64 位元全為 0。
firstValueSecondPart

string (uint64 format)

編碼資料中第一個項目的 65 到 128 位元 (雜湊)。如果這個欄位空白，65 到 128 位元全為 0。
firstValueThirdPart

string (uint64 format)

編碼資料中第一個項目的 129 到 192 位元 (雜湊)。如果這個欄位空白，則 129 到 192 位元全為 0。
firstValueFourthPart

string (uint64 format)

編碼資料中第一個項目的最後一個 64 位元 (雜湊)。如果這個欄位空白，最後 64 位元全為 0。
riceParameter

integer

Golomb-Rice 參數。此參數保證介於 227 到 254 (含) 之間。
entriesCount

integer

編碼資料中經過差異編碼的項目數量。如果只編碼一個整數，該值將會是 0，而單一值將儲存在 firstValue 中。
encodedData

string (bytes format)

使用 Golomb-Rice 編碼器編碼的編碼差異值。

Base64 編碼字串。

HashListMetadata

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

JSON 表示法 
{
  "threatTypes": [
    enum (ThreatType)
  ],
  "likelySafeTypes": [
    enum (LikelySafeType)
  ],
  "mobileOptimized": boolean,
  "description": string,
  "supportedHashLengths": [
    enum (HashLength)
  ]
}
欄位
threatTypes[]

enum (ThreatType)

未排序的清單。如果非空白，表示雜湊清單是威脅清單的種類，且會在這份雜湊清單中列舉與雜湊或雜湊前置字串相關的威脅類型。如果該項目不代表威脅 (也就是可能為安全類型)，則為空白。
likelySafeTypes[]

enum (LikelySafeType)

未排序的清單。如果非空白，表示雜湊清單代表可能安全的雜湊清單，列舉可能為安全的雜湊。此欄位與 ThreatTypes 欄位互斥。
mobileOptimized

boolean

這份清單是否已針對行動裝置 (Android 和 iOS) 進行最佳化。
description

string

使用者可理解的清單說明。英語
supportedHashLengths[]

enum (HashLength)

這份雜湊清單支援的雜湊長度。每份雜湊清單至少支援一種長度。因此，這個欄位不會空白。

ThreatType

威脅類型。

列舉
THREAT_TYPE_UNSPECIFIED 未知的威脅類型。如果伺服器傳回此方法，用戶端應完全忽略內含的 FullHashDetail。
MALWARE

惡意軟體威脅類型。只要軟體或行動應用程式會刻意危害電腦、行動裝置、這些裝置執行的軟體或其使用者，就屬於惡意軟體。惡意軟體會帶來各種形式的惡意行為，包括未經使用者同意便擅自安裝軟體，以及安裝病毒等有害軟體。

詳情請參閱這裡。
SOCIAL_ENGINEERING

社交工程威脅類型。謊稱有第三方身分的社交工程網頁，企圖讓觀眾誤以為執行某個動作，但觀眾只會信任該第三方的真實代理人。網路釣魚是一種社交工程，會誘騙觀眾執行特定動作，例如登入憑證。

詳情請參閱這裡。
UNWANTED_SOFTWARE 垃圾軟體威脅類型。垃圾軟體是指任何不符合 Google 軟體規範，但不是惡意軟體的軟體。
POTENTIALLY_HARMFUL_APPLICATION Google Play 安全防護使用 Play 商店時，可能有害的應用程式威脅類型。

LikelySafeType

可能有安全疑慮的網站類型。

請注意，我們刻意在 SearchHashesResponse 不包含 LikelySafeType。

列舉
LIKELY_SAFE_TYPE_UNSPECIFIED 未知。
GENERAL_BROWSING 這個網站可能適合一般瀏覽時使用。這項作業也稱為全域快取。
CSD 這個網站可能已足夠安全，因此不需要執行用戶端偵測模型或密碼保護檢查。
DOWNLOAD 這個網站本身可能安全無虞，因此網站不需要檢查下載。

HashLength

雜湊清單中的雜湊長度。

列舉
HASH_LENGTH_UNSPECIFIED 未指定長度。伺服器不會在給用戶端 (位於 supportedHashLengths 欄位) 的回應中傳回這個值，但用戶端可以將這個值 (位於 desiredHashLength 欄位) 傳送至伺服器；在此情況下，伺服器會自動挑選一個值。用戶端「必須」讓伺服器挑選值。
FOUR_BYTES 每個雜湊都是四位元組的前置字元。
EIGHT_BYTES 每個雜湊都是八位元組的前置字串。
SIXTEEN_BYTES 每個雜湊都是 16 個位元組的前置字元。
THIRTY_TWO_BYTES 每個雜湊都是三十二位元組完整雜湊。

方法

get

 取得雜湊清單的最新內容。