Method: hashes.search

Sucht nach vollständigen Hashes, die mit den angegebenen Präfixen übereinstimmen.

Dies ist eine benutzerdefinierte Methode, wie unter https://google.aip.dev/136 definiert. Die benutzerdefinierte Methode bezieht sich darauf, dass diese Methode einen benutzerdefinierten Namen in der allgemeinen API-Entwicklungsnomenklatur 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 Hash-Präfixe, die nachgeschlagen werden sollen. 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 müssen.

Derzeit muss jedes Hash-Präfix genau 4 Byte lang sein. Diese Einschränkung wird möglicherweise in Zukunft gelockert.

Ein base64-codierter String.

Anfragetext

Der Anfragetext muss leer sein.

Antworttext

Die Antwort, die nach der Suche nach Threat-Hashes zurückgegeben wird.

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

Das ist neu in Version 5: FullHash und FullHashDetail sind jetzt getrennt. Wenn ein Hash eine Website mit mehreren Bedrohungen (z.B. sowohl MALWARE als auch SOCIAL_ENGINEERING) darstellt, muss der vollständige Hash nicht wie in V4 zweimal gesendet werden. Außerdem wurde die Cache-Dauer in einem einzigen 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 ungeordnete Liste der gefundenen vollständigen Hashes.
cacheDuration

string (Duration format)

Die Dauer des clientseitigen Cache. Der Client MUSS diese Dauer zur aktuellen Zeit addieren, um die Ablaufzeit 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. In jedem Fall darf die verlängerte Cache-Dauer nicht länger als 24 Stunden sein.

Wichtig: Der Client darf NICHT davon ausgehen, dass der Server für alle Antworten dieselbe Cache-Dauer zurückgibt. Der Server KANN je nach Situation unterschiedliche Cache-Dauern für verschiedene Antworten auswählen.

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

FullHash

Der vollständige Hash, 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 Details für diesen vollständigen Hash angibt.

FullHashDetail

Details zu einem übereinstimmenden vollständigen Hash.

Wichtiger Hinweis zur Vorwärtskompatibilität: Der Server kann jederzeit neue Bedrohungstypen und ‑attribute hinzufügen. Diese Ergänzungen gelten als Änderungen der Nebenversion. Gemäß der Google-Richtlinie werden Nebenversionsnummern nicht in APIs offengelegt (siehe https://cloud.google.com/apis/design/versioning für die Versionierungsrichtlinie). Clients MÜSSEN daher darauf vorbereitet sein, FullHashDetail-Nachrichten mit ThreatType-Enum-Werten oder ThreatAttribute-Enum-Werten zu empfangen, die vom Client als ungültig betrachtet werden. Daher ist es die Aufgabe des Clients, die Gültigkeit aller ThreatType- und ThreatAttribute-Enum-Werte zu prüfen. Wenn ein Wert als ungültig betrachtet 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 nie leer.
attributes[]

enum (ThreatAttribute)

Unsortierte Liste. Zusätzliche Attribute zu diesen vollständigen Hashes. Diese Liste kann leer sein.

ThreatAttribute

Attribute von Bedrohungen. Diese Attribute können einer bestimmten Bedrohung eine zusätzliche Bedeutung verleihen, haben aber keinen Einfluss auf den Bedrohungstyp. Ein Attribut kann beispielsweise ein geringeres Vertrauen angeben, während ein anderes Attribut ein höheres Vertrauen 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 das umschließende FullHashDetail ignorieren.
CANARY Gibt an, dass der threatType nicht für die Durchsetzung verwendet werden sollte.
FRAME_ONLY Gibt an, dass der threatType nur für die Durchsetzung bei Frames verwendet werden sollte.