Interfejs API Bezpiecznego przeglądania Lookup (wersja 4)

Omówienie

Interfejs lookup API umożliwia aplikacjom klienckim wysyłanie żądań do usługi Bezpieczne przeglądanie , czy adresy URL znajdują się na listach Bezpiecznego przeglądania. Jeśli adres URL zostanie znaleziony w jednej z nich lub więcej list, zostaną zwrócone pasujące informacje.

Sprawdzam adresy URL

Aby sprawdzić, czy adres URL znajduje się na liście Bezpiecznego przeglądania, wyślij żądanie HTTP POST do threatMatches.find :

• Żądanie HTTP POST może zawierać do 500 adresów URL. Adresy URL muszą być prawidłowe (patrz RFC 2396). ale nie muszą być kanoniczne ani zakodowane.
• Odpowiedź HTTP POST zwraca pasujące adresy URL i czas trwania pamięci podręcznej.

Przykład: threatMatch.find

Żądanie HTTP POST

W poniższym przykładzie do serwera wysyłane są dwie listy Bezpiecznego przeglądania i trzy adresy URL czy znajdziemy dopasowanie.

Nagłówek żądania

Nagłówek żądania zawiera adres URL żądania i typ treści. Pamiętaj, aby zastąpić klucz interfejsu API usługi API_KEY w adresie URL.

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

Treść żądania

Treść żądania zawiera informacje o kliencie (identyfikator i wersja) oraz informacje o zagrożeniu (nazwy list i adresy URL). Więcej informacji: threatMatch.find treść żądania i wyjaśnienia dostępne na podstawie przykładowego kodu.

  {
    "client": {
      "clientId":      "yourcompanyname",
      "clientVersion": "1.5.2"
    },
    "threatInfo": {
      "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
      "platformTypes":    ["WINDOWS"],
      "threatEntryTypes": ["URL"],
      "threatEntries": [
        {"url": "http://www.urltocheck1.org/"},
        {"url": "http://www.urltocheck2.org/"},
        {"url": "http://www.urltocheck3.com/"}
      ]
    }
  }

Informacje o kliencie

Pola clientID i clientVersion powinny jednoznacznie określać implementację klienta, a nie pojedynczego użytkownika. (Informacje o kliencie służą do logowania i księgowania po stronie serwera. Możesz wybrać, dowolnej nazwy. Zalecamy jednak wybranie takiej nazwy, która odzwierciedla rzeczywistą tożsamość takie jak nazwa firmy zapisana jako jedno słowo małymi literami).

Listy Bezpiecznego przeglądania

Pola threatType, platformType i threatEntryType są łączone w celu identyfikacji (nazwy) list Bezpiecznego przeglądania. W tym przykładzie zidentyfikowaliśmy 2 listy: ZŁOŚLIWE/WINDOWS/URL i SOCIAL_ENGINEERING/WINDOWS/URL. Przed wysłaniem prośby upewnij się, że typ określone kombinacje są prawidłowe (patrz Listy Bezpiecznego przeglądania).

Zagrożone adresy URL

W przykładzie tablica threatEntries zawiera 3 adresy URL (urltocheck1.org, urltocheck2.org, i urltocheck3.org), która zostanie sprawdzona pod kątem dwóch list Bezpiecznego przeglądania.

Uwaga: interfejs lookup API i metoda threatMatches powinny zawsze używać pola URL, nigdy nie używaj pola hash (patrz ThreatEntry).

Odpowiedź HTTP POST

W tym przykładzie odpowiedź zwraca dopasowanie. dwóch z trzech adresów URL podanych w parametrze znajduje się na jednej z dwóch podanych w żądaniu list Bezpiecznego przeglądania.

Nagłówek odpowiedzi

Nagłówek odpowiedzi zawiera kod stanu HTTP. oraz typu treści.

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

Treść odpowiedzi

Treść odpowiedzi zawiera informacje o dopasowaniu (nazwy list i adresy URL znalezione w zapytaniu, te listy, metadane, jeśli są dostępne, oraz czasy przechowywania w pamięci podręcznej). Więcej informacji: threatMatch.find content (Treść odpowiedzi) i wyjaśnienia dostępne na podstawie przykładowego kodu.

Uwaga: jeśli nie ma dopasowań (czyli jeśli brak określonych adresów URL znajdują się na dowolnej z list określonych w żądaniu), w odpowiedzi HTTP POST po prostu zwraca pusty obiekt w treści odpowiedzi.

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat":          {"url": "http://www.urltocheck1.org/"},
    "threatEntryMetadata": {
      "entries": [{
        "key": "malware_threat_type",
        "value": "landing"
     }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat":          {"url": "http://www.urltocheck2.org/"},
    "threatEntryMetadata": {
      "entries": [{
        "key":   "malware_threat_type",
        "value": "landing"
     }]
    },
    "cacheDuration": "300.000s"
  }]
}

Odpowiada

Obiekt matches zawiera nazwy list Bezpiecznego przeglądania oraz adresy URL, jeśli mamy do czynienia z pewnym dopasowaniem. W tym przykładzie znaleźliśmy 2 adresy URL (urltocheck1.org i urltocheck2.org) na jednej z tych stron list Bezpiecznego przeglądania (MALWARE/WINDOWS/URL), aby pasujące informacje były zwracane. Trzeci adres URL (urltocheck3.org) nie znaleziono na żadnej liście, więc dla tego adresu URL nie są zwracane żadne informacje.

Metadane

Pole threatEntryMetadata jest opcjonalne i zawiera dodatkowe informacje o: w odpowiednim miejscu. Obecnie dostępne są metadane z listy Bezpiecznego przeglądania MALWARE/WINDOWS/URL (zobacz Metadane).

Czasy trwania buforowania

Pole cacheDuration wskazuje, przez ile czasu adres URL musi być uznawany za niebezpieczny. (patrz Pamięć podręczna).