Method: hashes.search

Es wird nach vollständigen Hashes gesucht, die mit den angegebenen Präfixen übereinstimmen.

Dies ist eine benutzerdefinierte Methode gemäß https://google.aip.dev/136. Die benutzerdefinierte Methode bezieht sich auf diese Methode, die einen benutzerdefinierten Namen innerhalb der allgemeinen Nomenklatur für die API-Entwicklung von Google hat. Sie bezieht sich nicht auf die Verwendung einer benutzerdefinierten HTTP-Methode.

HTTP-Anfrage

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

Die URL verwendet die Syntax der gRPC-Transcodierung.

Abfrageparameter

Parameter
hashPrefixes[]

string (bytes format)

Erforderlich. Die zu suchenden Hash-Präfixe. Clients dürfen NICHT mehr als 1.000 Hash-Präfixe senden. Gemäß dem Verfahren zur URL-Verarbeitung sollten Clients jedoch NICHT mehr als 30 Hash-Präfixe senden.

Derzeit muss jedes Hash-Präfix genau 4 Byte lang sein. Diese Einschränkung kann in Zukunft aufgehoben werden.

Ein base64-codierter String.

Anfragetext

Der Anfragetext muss leer sein.

Antworttext

Die Antwort, die nach der Suche nach Bedrohungshaschen zurückgegeben wurde.

Wenn nichts gefunden wird, gibt der Server den Status „OK“ (HTTP-Statuscode 200) mit einem leeren Feld fullHashes zurück, anstatt den Status „NICHT GEFUNDEN“ (HTTP-Statuscode 404) zurückzugeben.

Neu in Version 5: Es gibt eine Trennung zwischen FullHash und FullHashDetail. Wenn ein Hash für eine Website mit mehreren Bedrohungen steht (z.B. MALWARE und SOCIAL_ENGINEERING), muss der vollständige Hash nicht wie in Version 4 zweimal gesendet werden. Außerdem wurde die Cachedauer in ein einzelnes cacheDuration-Feld vereinfacht.

Bei Erfolg enthält der Antworttext Daten mit der folgenden Struktur:

JSON-Darstellung 
{
  "fullHashes": [
    {
      object (FullHash)
    }
  ],
  "cacheDuration": string
}
Felder
fullHashes[]

object (FullHash)

Unsortierte Liste. Die unsortierte Liste der gefundenen vollständigen Hash-Werte.
cacheDuration

string (Duration format)

Die Dauer des clientseitigen Caches. Der Client MUSS diese Dauer zur aktuellen Zeit hinzufügen, um den Ablaufzeitpunkt zu ermitteln. Die Ablaufzeit gilt dann für jedes Hash-Präfix, das vom Client in der Anfrage abgefragt wird, unabhängig davon, wie viele vollständige Hashes in der Antwort zurückgegeben werden. Auch wenn der Server keine vollständigen Hashes für ein bestimmtes Hash-Präfix zurückgibt, MUSS diese Tatsache vom Client im Cache gespeichert werden.

Nur wenn das Feld fullHashes leer ist, DARF der Client cacheDuration erhöhen, um ein neues Ablaufdatum festzulegen, das später als das vom Server angegebene ist. Die erhöhte Cachedauer darf in jedem Fall nicht länger als 24 Stunden sein.

Wichtig: Der Client darf nicht davon ausgehen, dass der Server für alle Antworten dieselbe Cachedauer zurückgibt. Der Server KANN je nach Situation unterschiedliche Cachedauern für unterschiedliche Antworten auswählen.

Die Dauer in Sekunden mit bis zu neun Nachkommastellen und am Ende mit "s". Beispiel: "3.5s".

FullHash

Der vollständige Hashwert, der mit einer oder mehreren Übereinstimmungen identifiziert wurde.

JSON-Darstellung 
{
  "fullHash": string,
  "fullHashDetails": [
    {
      object (FullHashDetail)
    }
  ]
}
Felder
fullHash

string (bytes format)

Der übereinstimmende vollständige Hash. Das ist der SHA256-Hash. Die Länge beträgt genau 32 Byte.

Ein base64-codierter String.
fullHashDetails[]

object (FullHashDetail)

Unsortierte Liste. Ein wiederholtes Feld, das die für diesen vollständigen Hash relevanten Details angibt.

FullHashDetail

Details zu einem übereinstimmenden vollständigen Hash.

Wichtiger Hinweis zur Zukunftssicherheit: Neue Bedrohungstypen und Bedrohungsattribute können vom Server jederzeit hinzugefügt werden. Diese Ergänzungen gelten als Versionsänderungen der Nebenversion. Gemäß der Google-Richtlinie dürfen Nebenversionsnummern nicht in APIs freigegeben werden (siehe https://cloud.google.com/apis/design/versioning für die Versionierungsrichtlinie). Clients müssen also darauf vorbereitet sein, FullHashDetail-Nachrichten mit ThreatType- oder ThreatAttribute-Enum-Werten zu erhalten, die vom Client als ungültig betrachtet werden. Daher liegt es in der Verantwortung des Clients, die Gültigkeit aller ThreatType- und ThreatAttribute-Enum-Werte zu prüfen. Wenn ein Wert als ungültig eingestuft wird, MUSS der Client die gesamte FullHashDetail-Nachricht ignorieren.

JSON-Darstellung 
{
  "threatType": enum (ThreatType),
  "attributes": [
    enum (ThreatAttribute)
  ]
}
Felder
threatType

enum (ThreatType)

Die Art der Bedrohung. Dieses Feld ist immer ausgefüllt.
attributes[]

enum (ThreatAttribute)

Unsortierte Liste. Zusätzliche Attribute zu diesen vollständigen Hash-Werten. Dieses Feld kann leer sein.

ThreatAttribute

Attribute von Bedrohungen. Diese Attribute können einer bestimmten Bedrohung zusätzliche Bedeutung verleihen, haben aber keinen Einfluss auf den Bedrohungstyp. So kann ein Attribut beispielsweise eine niedrigere Zuverlässigkeit angeben, während ein anderes Attribut eine höhere Zuverlässigkeit angibt. In Zukunft werden möglicherweise weitere Attribute hinzugefügt.

Enums
THREAT_ATTRIBUTE_UNSPECIFIED Unbekanntes Attribut. Wenn dies vom Server zurückgegeben wird, muss der Client die umschließende FullHashDetail vollständig ignorieren.
CANARY Gibt an, dass der „threatType“ nicht für die Erzwingung verwendet werden soll.
FRAME_ONLY Gibt an, dass der „threatType“ nur für die Erzwingung von Frames verwendet werden sollte.