Genel bakış
Update API, istemci uygulamalarınızın Güvenli Tarama listelerinin karma sürümlerini yerel bir veritabanında depolamak amacıyla indirmesine olanak tanır. Daha sonra URL'ler yerel olarak kontrol edilebilir. Yalnızca yerel veritabanında bir eşleşme bulunursa istemcinin, URL'nin Güvenli Tarama listelerine eklenip eklenmediğini doğrulamak için Güvenli Tarama sunucularına istek göndermesi gerekir.
Update API'yi kullanmadan önce yerel bir veritabanı ayarlamanız gerekir. Güvenli Tarama, başlamak için kullanabileceğiniz bir Go paketi sağlar. Daha fazla bilgi için Yerel Veritabanları altındaki Veritabanı Kurulumu bölümüne bakın.
Yerel veritabanını güncelleme
Müşterilerin güncel kalmak için yerel veritabanlarındaki Güvenli Tarama listelerini düzenli olarak güncellemeleri gerekir. Bant genişliğinden tasarruf etmek için istemciler, ham URL'ler yerine URL'lerin karma ön eklerini indirir. Örneğin, "www.badurl.com/" bir Güvenli Tarama listesindeyse istemciler, URL'nin kendisi yerine bu URL'nin SHA256 karma ön ekini indirir. Çoğu durumda karma ön eklerin uzunluğu 4 bayttır. Diğer bir deyişle, tek bir liste girişini indirmenin ortalama bant genişliği maliyeti, sıkıştırmadan önce 4 bayttır.
Yerel veritabanındaki Güvenli Tarama listelerini güncellemek için threatListUpdates.fetch yöntemine HTTP POST
isteği gönderin:
- HTTP
POST
isteği, güncellenecek listelerin adlarını ve bellek ve bant genişliği sınırlamalarını hesaba katan çeşitli istemci kısıtlamalarını içerir. - HTTP
POST
yanıtı, tam güncelleme veya kısmi güncelleme döndürür. Yanıt minimum bekleme süresi de döndürebilir.
Örnek: ThreatListUpdates.fetch
HTTP POST isteği
Aşağıdaki örnekte, tek bir Güvenli Tarama listesi için güncellemeler istenmektedir.
İ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/threatListUpdates:fetch?key=API_KEY HTTP/1.1 Content-Type: application/json
İstek içeriği
İstek gövdesi, istemci bilgilerini (kimlik ve sürüm) ve güncelleme bilgilerini (liste adı, liste durumu ve istemci kısıtlamaları) içerir. Daha fazla ayrıntı için threatListUpdates.fetch istek gövdesine ve kod örneğinden sonraki açıklamalara bakın.
{ "client": { "clientId": "yourcompanyname", "clientVersion": "1.5.2" }, "listUpdateRequests": [{ "threatType": "MALWARE", "platformType": "WINDOWS", "threatEntryType": "URL", "state": "Gg4IBBADIgYQgBAiAQEoAQ==", "constraints": { "maxUpdateEntries": 2048, "maxDatabaseEntries": 4096, "region": "US", "supportedCompressions": ["RAW"] } }] }
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ında kullanılır. İstemci kimliği için herhangi bir adı seçebilirsiniz ancak müşterinin gerçek kimliğini temsil eden, örneğin 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 (adlandırmak) için birleştirilir. Bu örnekte bir liste tanımlanmıştır:
MALWARE/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).
İstemci durumu
state
alanı, Güvenli Tarama listesinin geçerli istemci durumunu içerir.
(İstemci durumları, threatListUpdates.fetch yanıtının newClientState
alanında döndürülür.)
İlk güncellemeler için state
alanını boş bırakın.
Boyut kısıtlamaları
maxUpdateEntries
alanı, istemcinin yönetebileceği toplam güncelleme sayısını belirtir (örnekte 2048). maxDatabaseEntries
alanı, yerel veritabanının yönetebileceği toplam giriş sayısını belirtir (örnekte 4096). İstemciler, bellek ve bant genişliği sınırlamalarını korumak ve liste büyümesine karşı koruma sağlamak için boyut kısıtlamaları belirlemelidir. Daha fazla bilgi için Güncelleme Kısıtlamaları bölümünü inceleyin.
Desteklenen sıkıştırma
supportedCompressions
alanında, istemcinin desteklediği sıkıştırma türleri listelenir. Bu örnekte, istemci yalnızca ham, sıkıştırılmamış verileri destekler. Ancak Güvenli Tarama ek sıkıştırma türlerini destekler (Sıkıştırma bölümüne bakın).
HTTP POST yanıtı
Bu örnekte verilen yanıt, istenen sıkıştırma türünü kullanarak Güvenli Tarama listesi için kısmi bir güncelleme döndürür.
Yanıt başlığı
Yanıt başlığı, HTTP durum kodunu ve içerik türünü içerir. HTTP/200 dışında bir durum kodu alan istemciler, geri çekilme moduna girmelidir (bkz. İstek Sıklığı).
HTTP/1.1 200 OK Content-Type: application/json
Yanıt gövdesi
Yanıt gövdesi, güncelleme bilgilerini (liste adı, yanıt türü, yerel veritabanına uygulanacak ekleme ve kaldırma işlemleri, yeni istemci durumu ve sağlama toplamı) içerir. Örnekteki yanıtta minimum bekleme süresi de yer alıyor. Daha fazla bilgi için threatListUpdates.fetch yanıt gövdesine ve kod örneğindeki açıklamalara bakın.
{ "listUpdateResponses": [{ "threatType": "MALWARE", "threatEntryType": "URL", "platformType": "WINDOWS", "responseType" : "PARTIAL_UPDATE", "additions": [{ "compressionType": "RAW", "rawHashes": { "prefixSize": 4, "rawHashes": "rnGLoQ==" } }], "removals": [{ "compressionType": "RAW", "rawIndices": { "indices": [0, 2, 4] } }], "newClientState": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd", "checksum": { "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM=" } }], "minimumWaitDuration": "593.440s" }
Veritabanı güncellemeleri
responseType
alanı, kısmi veya tam güncellemeyi belirtir. Örnekte, kısmi bir güncelleme döndürüldüğünden, yanıt hem ekleme hem de kaldırma işlemlerini içerir. Birden fazla ekleme grubu ancak tek bir kaldırma grubu olabilir (bkz. Veritabanı Güncellemeleri).
Yeni müşteri durumu
newClientState
alanı, yeni güncellenen Güvenli Tarama listesinin yeni istemci durumunu tutar.
İstemciler, sonraki güncelleme istekleri için yeni istemci durumunu kaydetmelidir (threatListUpdates.fetch isteğindeki state
alanı veya fullHashes.find isteğindeki clientStates
alanı).
Sağlamalar
Sağlama, istemcilerin yerel veritabanında herhangi bir bozulma olmadığını doğrulamasını sağlar. Sağlama toplamı eşleşmezse istemcinin veritabanını temizlemesi ve boş bir state
alanı ile yeniden güncelleme yayınlaması gerekir. Ancak bu durumdaki istemcilerin, güncellemeler için zaman aralıklarını takip etmesi gerekir (bkz. İstek Sıklığı).
Minimum bekleme süreleri
minimumWaitDuration
alanı, istemcinin başka bir güncelleme isteği göndermeden önce 593,44 saniye (9,89 dakika) beklemesi gerektiğini belirtir. Yanıta bekleme süresinin dahil edilip edilmeyeceğini unutmayın (İstek Sıklığı bölümüne bakın).
URL'ler kontrol ediliyor
Bir URL'nin Güvenli Tarama listesinde olup olmadığını kontrol etmek için istemcinin öncelikle URL'nin karma ve karma ön ekini hesaplaması gerekir (bkz. URL'ler ve Karma Oluşturma). Ardından istemci, eşleşme olup olmadığını belirlemek için yerel veritabanını sorgular. Karma ön eki yerel veritabanında yoksa URL, güvenli kabul edilir (Güvenli Tarama listelerinde yer almaz).
Yerel veritabanında karma ön eki varsa (karma ön eki çakışması) istemcinin, karma ön ekini doğrulama için Güvenli Tarama sunucularına göndermesi gerekir. Sunucular, belirtilen karma önekini içeren tüm tam uzunluktaki SHA 256 karmalarını döndürür. Bu tam uzunluktaki karmalardan biri, söz konusu URL'nin tam uzunluktaki karmasıyla eşleşirse URL'nin güvenli olmadığı kabul edilir. Tam uzunluktaki karmaların hiçbiri söz konusu URL'nin tam uzunluktaki karmasıyla eşleşmiyorsa bu URL güvenli kabul edilir.
Google, incelediğiniz URL'ler hakkında hiçbir zaman bilgi edinmez. Google, URL'lerin karma ön eklerini öğrenir, ancak karma ön ekler gerçek URL'ler hakkında çok fazla bilgi vermez.
Bir URL'nin Güvenli Tarama listesinde olup olmadığını kontrol etmek için fullHashes.find yöntemine HTTP POST
isteği gönderin:
- HTTP
POST
isteği en fazla 500 tehdit girişi içerebilir. - HTTP
POST
isteği, kontrol edilecek URL'lerin karma öneklerini içerir. Bant genişliği kullanımını azaltmak için istemcilerin, birden fazla tehdit girişini tek bir istekte gruplandırması önerilir. - HTTP
POST
yanıtı, pozitif ve negatif önbellek süreleriyle birlikte eşleşen tam uzunlukta karmaları döndürür. Yanıt için minimum bekleme süresi de dönebilir.
Örnek: fullHashes.find
HTTP POST isteği
Aşağıdaki örnekte, iki Güvenli Tarama listesinin ve üç karma ön ekin adı karşılaştırma ve doğrulama için 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/fullHashes:find?key=API_KEY HTTP/1.1 Content-Type: application/json
İstek içeriği
İstek gövdesinde istemci bilgileri (kimlik ve sürüm), istemci durumları ve tehdit bilgileri (liste adları ve karma önekler) yer alır. JSON istekleri için karma öneklerin base64 olarak kodlanmış biçimde gönderilmesi gerekir. Daha fazla bilgi için fullHashes.find istek gövdesi ve kod örneğinden sonraki açıklamalara bakın.
{ "client": { "clientId": "yourcompanyname", "clientVersion": "1.5.2" }, "clientStates": [ "ChAIARABGAEiAzAwMSiAEDABEAE=", "ChAIAhABGAEiAzAwMSiAEDABEOgH" ], "threatInfo": { "threatTypes": ["MALWARE", "SOCIAL_ENGINEERING"], "platformTypes": ["WINDOWS"], "threatEntryTypes": ["URL"], "threatEntries": [ {"hash": "WwuJdQ=="}, {"hash": "771MOg=="}, {"hash": "5eOrwQ=="} ] } }
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ında 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 kelimelik bir şekilde ve tamamı küçük harfle gösterilen bir ad seçmenizi öneririz.
Tüm istemci durumları
clientStates
alanı, istemcinin yerel veritabanındaki tüm Güvenli Tarama listeleri için istemci durumlarını tutar. (İstemci durumları, threatListUpdates.fetch yanıtının newClientState
alanında döndürülür.)
Güvenli Tarama listeleri
threatTypes
, platformTypes
ve threatEntryTypes
alanları, Güvenli Tarama listelerini tanımlamak (adlandırmak) 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 karması ön ekleri
ThreatEntries dizisi, kontrol etmek istediğiniz URL'lerin karma ön eklerini içerir.
hash
alanı, yerel veritabanında bulunan tam karma önekini içermelidir. Örneğin, yerel karma ön eki 4 bayt uzunluğundaysa tehdit girişi 4 bayt uzunluğunda olmalıdır. Yerel karma ön eki 7 bayta uzatılmışsa tehdit girişi 7 bayt uzunluğunda olmalıdır.
Örnekteki istek üç karma ön ek içeriyor. Üç ön ekin tümü, tam uzunlukta eşleşen karma olup olmadığını belirlemek için Güvenli Tarama listelerinin her biriyle karşılaştırılır.
Not: Update API ve fullHashes.find yöntemi, hiçbir zaman URL
alanını değil, her zaman hash
alanını kullanmalıdır (ThreatEntry bölümüne bakın).
HTTP POST yanıtı
Aşağıdaki örnekte yanıt, Güvenli Tarama listesine göre düzenlenen eşleşen verileri, önbellek ve bekleme süreleriyle birlikte döndürür.
Yanıt başlığı
Yanıt başlığı, HTTP durum kodunu ve içerik türünü içerir. HTTP/200 dışında bir durum kodu alan istemcilerin geri çekilmesi gerekir (bkz. İstek Sıklığı).
HTTP/1.1 200 OK Content-Type: application/json
Yanıt gövdesi
Yanıt gövdesi, eşleşme bilgilerini (liste adları ve tam uzunlukta karmalar, varsa meta veriler ve önbellek süreleri) içerir. Örnekteki yanıt gövdesi de minimum bekleme süresi içerir. Daha fazla bilgi için fullHashes.find yanıt gövdesi ve kod örneğinden sonraki açıklamalara bakın.
{ "matches": [{ "threatType": "MALWARE", "platformType": "WINDOWS", "threatEntryType": "URL", "threat": { "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4=" }, "threatEntryMetadata": { "entries": [{ "key": "bWFsd2FyZV90aHJlYXRfdHlwZQ==", // base64-encoded "malware_threat_type" "value": "TEFORElORw==" // base64-encoded "LANDING" }] }, "cacheDuration": "300.000s" }, { "threatType": "SOCIAL_ENGINEERING", "platformType": "WINDOWS", "threatEntryType": "URL", "threat": { "hash": "771MOrRPMn6xPKlCrXx_CrR-wmCk0LgFFoSgGy7zUiA=" }, "threatEntryMetadata": { "entries": [] }, "cacheDuration": "300.000s" }], "minimumWaitDuration": "300.000s", "negativeCacheDuration": "300.000s" }
Şununla eşleşiyor:
"Eşleşmeler" nesnesi, karma ön eklerinden ikisi için eşleşen tam uzunlukta bir karma döndürür. Bu karmalara karşılık gelen URL'ler güvenli olarak kabul edilir. Üçüncü karma ön eki için eşleşme bulunamadığından hiçbir şey döndürülmez. Bu karma ön ekine karşılık gelen URL güvenli kabul edilir.
Bu örneğin, bir tam uzunluktaki karmayı bir karma ön ekiyle eşleştirdiğini unutmayın. Bununla birlikte, aynı karma ön eki ile eşlenen birden çok tam karma olabilir.
Meta veri
threatEntryMetadata
alanı isteğe bağlıdır ve tehdit eşleştirme 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
ve negativeCacheDuration
alanları, karmaların güvenli veya güvenli olarak değerlendirilmesi gereken süreyi gösterir (Önbelleğe alma bölümüne bakın).
Minimum bekleme süreleri
minimumWaitDuration
alanı, istemcinin başka bir fullHashes isteği göndermeden önce 300 saniye (5 dakika) beklemesi gerektiğini belirtir. Yanıta bekleme süresinin dahil edilip edilmeyeceğini unutmayın (İstek Sıklığı bölümüne bakın).