Güvenli Tarama Lookup API'si (v4)

Genel bakış

Lookup API, istemci uygulamalarınızın, URL'lerin herhangi bir Güvenli Tarama listesinde olup olmadığını kontrol etmek için Güvenli Tarama sunucularına istek göndermesine olanak tanır. Bir URL bir veya daha fazla listede bulunursa eşleşen bilgiler döndürülür.

URL'ler kontrol ediliyor

Bir URL'nin Güvenli Tarama listesinde olup olmadığını kontrol etmek için threatMatches.find yöntemine HTTP POST isteği gönderin:

• HTTP POST isteği en fazla 500 URL içerebilir. URL'ler geçerli olmalıdır (bkz. RFC 2396) ancak standartlaştırılmaları veya kodlanması gerekmez.
• HTTP POST yanıtı, önbellek süresiyle birlikte eşleşen URL'leri döndürür.

Örnek: ThreatMatches.find

HTTP POST isteği

Aşağıdaki örnekte, eşleşme olup olmadığını belirlemek için sunucuya iki Güvenli Tarama listesi ve üç URL gönderilmiştir.

İstek başlığı

İstek başlığı, istek URL'sini ve içerik türünü içerir. URL'deki API_KEY API anahtarınızı değiştirmeyi unutmayın.

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

İstek içeriği

İstek metni, istemci bilgilerini (kimlik ve sürüm) ve tehdit bilgilerini (liste adları ve URL'ler) içerir. Daha ayrıntılı bilgi için threatMatches.find istek gövdesine ve kod örneğinden sonraki açıklamalara bakın.

  {
    "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/"}
      ]
    }
  }

Müşteri bilgileri

clientID ve clientVersion alanları, tekil bir kullanıcıyı değil, bir istemci uygulamasını benzersiz şekilde tanımlamalıdır. (İstemci bilgileri, sunucu tarafı günlük kaydı ve hesaplama için kullanılır. İstemci kimliği için herhangi bir ad seçebilirsiniz ancak müşterinin gerçek kimliğini temsil eden bir ad (ör. şirket adınız) tek kelimeden oluşan ve tamamı küçük harfle gösterilen bir ad seçmenizi öneririz.

Güvenli Tarama listeleri

threatType, platformType ve threatEntryType alanları, Güvenli Tarama listelerini tanımlamak (ad) için birleştirilir. Bu örnekte iki liste tanımlanmıştır: MALWARE/WINDOWS/URL ve SOCIAL_ENGINEERING/WINDOWS/URL. İstek göndermeden önce, belirttiğiniz tür kombinasyonlarının geçerli olduğundan emin olun (Güvenli Tarama Listeleri'ne bakın).

Tehdit URL'leri

Örnekteki threatEntries dizisi, iki Güvenli Tarama listesine göre kontrol edilecek üç URL (urltocheck1.org, urltocheck2.org ve urltocheck3.org) içerir.

Not: Lookup API ve threatMatches yöntemi her zaman hash alanını değil, her zaman URL alanını kullanmalıdır (ThreatEntry bölümüne bakın).

HTTP POST yanıtı

Aşağıdaki örnekte, yanıt bir eşleşme döndürür. İstekte belirtilen üç URL'den ikisi, istekte belirtilen iki Güvenli Tarama listesinden birinde bulunur.

Yanıt başlığı

Yanıt başlığı, HTTP durum kodunu ve içerik türünü içerir.

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

Yanıt gövdesi

Yanıt gövdesi, eşleşme bilgilerini (bu listelerde bulunan liste adları ve URL'ler, varsa meta veriler ve önbellek süreleri) içerir. Daha ayrıntılı bilgi için threatMatches.find yanıt gövdesi ve kod örneğinden sonraki açıklamalara bakın.

Not: Eşleşme yoksa (yani istekte belirtilen URL'lerin hiçbiri, bir istekte belirtilen listelerin herhangi birinde bulunuyorsa) HTTP POST yanıtı, yanıt gövdesinde boş bir nesne döndürür.

{
  "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"
  }]
}

Eşleşmeler

matches nesnesi, Güvenli Tarama listelerinin adları ve varsa URL'leri listeler. Bu örnekte, Güvenli Tarama listelerinin (MALWARE/WINDOWS/URL) birinde iki URL (urltocheck1.org ve urltocheck2.org) bulunmuştur. Dolayısıyla eşleşen bilgiler döndürülür. Üçüncü URL (urltocheck3.org) her iki listede de bulunamadığından, bu URL için herhangi bir bilgi döndürülmez.

Meta veri

threatEntryMetadata alanı isteğe bağlıdır ve tehdit eşleştirmesi hakkında ek bilgi sağlar. Şu anda meta veri, KÖTÜ AMAÇLI YAZILIM/WINDOWS/URL Güvenli Tarama listesi için kullanılabilir (bkz. Meta Veriler).

Önbellek süreleri

cacheDuration alanı, URL'nin güvenli olmadığı kabul edilmesi gereken süreyi belirtir (Önbelleğe alma bölümüne bakın).