Genel Bakış
Update API, istemci uygulamalarınızın Güvenli Tarama listelerinin karma oluşturma işlemi uygulanmış sürümlerini indirmesine olanak tanır. yerel veritabanında saklamanızı sağlar. Böylece URL'ler yerel olarak kontrol edilebilir. Yalnızca istemcinin, alan adının doğrulanması için Güvenli Tarama sunucularına bir istek göndermesi URL'nin Güvenli Tarama listelerine eklenip eklenmediğini kontrol eder.
Update API'yi kullanmadan önce yerel bir veritabanı oluşturmanız gerekir. Güvenli Tarama, Başlamak için kullanabileceğiniz Go paketi. Daha fazla ayrıntı için Yerel Veritabanları.
Yerel veritabanını güncelleme
İstemcilerin güncel kalabilmek için yerel veritabanlarındaki Güvenli Tarama listelerini düzenli olarak güncellemesi gerekir. Müşteriler, bant genişliğinden tasarruf etmek için ham URL'ler yerine URL'lerin karma ön eklerini indirir. Örneğin, "www.badurl.com/" Güvenli Tarama listesindeyse müşteriler URL'nin kendisini değil, SHA256 karma ön ekini indirir. Çoğu durumda karma önekler 4 bayt uzunluğundadır, yani tek bir listeyi indirmenin ortalama bant genişliği maliyeti giriş, sıkıştırmadan 4 bayt öncedir.
Yerel veritabanındaki Güvenli Tarama listelerini güncellemek için threatListUpdates.fetch yöntemine bir HTTP POST
isteği gönderin:
- HTTP
POST
isteği, çeşitli istemcilerle birlikte güncellenecek listelerin adlarını içerir. ve bant genişliği sınırlamalarını hesaba katar. - HTTP
POST
yanıtı tam güncelleme veya kısmi güncelleme döndürür. Yanıt minimum bekleme süresi da döndürebilir.
Örnek: tehditListUpdates.fetch
HTTP POST isteği
Aşağıdaki örnekte, tek bir Güvenli Tarama listesi için güncellemeler istenir.
İstek başlığı
İstek başlığı, istek URL'sini ve içerik türünü içerir. API'nizi değiştirmeyi unutmayın
API_KEY
tuşuna bası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ını, liste durumunu ve istemci kısıtlamalarını içerir). Daha fazla bilgi için threatListUpdates.fetch istek gövdesine ve kod örneğinin ardından gelen 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ı, bireysel bir kullanıcıyı değil, 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 istediğiniz adı seçebilirsiniz ancak istemcinin gerçek kimliğini temsil eden bir ad seçmenizi öneririz (ör. şirketinizin adı, tek bir kelime olarak ve tamamen küçük harflerle yazılmış şekilde).
Güvenli Tarama listeleri
threatType
, platformType
ve threatEntryType
alanları
Güvenli Tarama listelerini tanımlamak (adlandırmak) için birleştirilir. Ö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 bölümü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 (
(örneğin, 2048). maxDatabaseEntries
alanı, yerel
yönetebileceği bir kaynaktır (örnekte 4096). Müşteriler boyut kısıtlamaları ayarlamalıdır
belleğe ve bant genişliği sınırlamalarını korumak ve
bahsedeceğim. Daha fazla bilgi için Güncelleme Kısıtlamaları bölümüne bakın.
Desteklenen sıkıştırma işlemleri
supportedCompressions
alanında, istemcinin desteklediği sıkıştırma türleri listelenir.
Örneğin, istemci yalnızca ham ve 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, yanıtta istenen sıkıştırma türü kullanılarak Güvenli Tarama listesi için kısmi bir güncelleme döndürülür.
Yanıt başlığı
Yanıt üstbilgisi, HTTP durum kodunu içerir. ve içerik türü. HTTP/200 dışında bir durum kodu alan istemciler geri yükleme 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ü, eklemeleri ve kaldırmaları, yeni müşteri için bir denetim toplamı) içerir. Örnekteki yanıt, minimum bekleme süresi de içerir. Daha fazla daha fazla bilgi için threatListUpdates.fetch yanıt gövdesi ve kod örneğindeki açıklamaları izlemelisiniz.
{ "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 gösterir. Bu örnekte, kısmi güncelleme
hatası döndürülür, dolayısıyla yanıt hem ekleme hem de kaldırma işlemlerini içerir. Birden fazla ekleme grubu olabilir ancak yalnızca bir kaldırma grubu olabilir (Veritabanı Güncellemeleri bölümüne bakın).
Yeni istemci durumu
newClientState
alanı, yeni güncellenen Güvenli Tarama listesi için yeni istemci durumunu barındırır.
Müşteriler, sonraki güncelleme istekleri için yeni istemci durumunu (state
threatListUpdates.fetch isteği
veya clientStates
fullHashes.find isteği).
Denetim Toplamları
Sağlama, istemcilerin yerel veritabanında herhangi bir bozulma olmadığını doğrulamasını sağlar. Öğe
denetim toplamı eşleşmiyor, istemcinin veritabanını temizlemesi ve güncelleştirmeyi boş bir
state
alanı boş bırakılamaz. Ancak bu durumdaki müşteriler, güncellemeler için yine de zaman aralıklarını izlemelidir.
(bkz. İstek Sıklığı).
Minimum bekleme süreleri
minimumWaitDuration
alanı, istemcinin 593,44 saniye (9,89 dakika) beklemesi gerektiğini belirtir
. Bekleme süresinin,
yanıtı (İ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 müşterinin öncelikle karmayı ve karmayı hesaplaması gerekir. önekini kullanın (URL'ler ve Karma oluşturma bölümüne bakın). Ardından istemci, eşleşme olup olmadığını belirlemek için yerel veritabanı sorgular. Karma oluşturma ön eki yerel veritabanında bulunmuyorsa URL güvenli kabul edilir (Güvenli Tarama listelerinde yer almaz).
Yerel veritabanında karma ön eki varsa (karma öneki çakışması) istemci, karma önekini doğrulama için Güvenli Tarama sunucularına göndermelidir. Sunucular, belirtilen karma ön ekini 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 güvenli değil olarak kabul edilir. Tam uzunluktaki karma şifrelerden hiçbiri söz konusu URL'nin tam uzunluktaki karma şifresiyle eşleşmiyorsa bu URL güvenli kabul edilir.
Google, incelemekte olduğunuz URL'ler hakkında hiçbir noktada bilgi almaz. Google, karmayı ancak karma önekler gerçek URL'ler hakkında fazla bilgi vermez.
Bir URL'nin Güvenli Tarama listesinde olup olmadığını kontrol etmek için şuraya bir HTTP POST
isteği gönderin
fullHashes.find
yöntem:
- HTTP
POST
isteği en fazla 500 tehdit girişi içerebilir. - HTTP
POST
isteği, kontrol edilecek URL'lerin karma ön eklerinin içerir. Müşteriler Bu öneri, bant genişliği kullanımını azaltmak için birden fazla tehdit girişini tek bir istekte toplanmalıdır. - HTTP
POST
yanıtı, pozitif ve negatif önbellek süreleri. Yanıt da minimum bekleme süresi döndürebilir.
Örnek: fullHashes.find
HTTP POST isteği
Aşağıdaki örnekte, karşılaştırma ve doğrulama için iki Güvenli Tarama listesinin adları ve üç karma ön ek gönderilmektedir.
İstek başlığı
İstek başlığı, istek URL'sini ve içerik türünü içerir. Şunları değiştirmeyi unutmayın:
API_KEY
için API anahtarınız.
POST https://safebrowsing.googleapis.com/v4/fullHashes:find?key=API_KEY HTTP/1.1 Content-Type: application/json
İstek içeriği
İstek gövdesi; istemci bilgilerini (kimlik ve sürüm), istemci durumlarını ve tehdit bilgilerini (liste adları ve karma ön ekleri) içerir. JSON isteklerinde karma ön ekleri base64 kodlu biçimde gönderilmelidir. Daha fazla bilgi için fullHashes.find istek gövdesi ve kod örneğindeki açıklamaları izlemelisiniz.
{ "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ı,
bireysel kullanıcı. (İstemci bilgileri sunucu tarafında günlük kaydında kullanılır. Öğe kimliği için
Ancak, müşterinin gerçek kimliğini temsil eden bir ad seçmenizi öneririz, örneğin:
(hepsi küçük harflerle yazılmış, tümü tek bir kelime halinde sunulan şirket adınız).)
Tüm istemci durumları
clientStates
alanı, tüm Güvenli Tarama listelerinin istemci durumlarını
yerel veritabanını kullanır. (İstemci durumları, threatListUpdates.fetch yanıtının newClientState
alanında döndürülür.)
Güvenli Tarama listeleri
threatTypes
, platformTypes
ve threatEntryTypes
Güvenli Arama'yı tanımlamak (adını vermek) için
Listelere göz atma. Ö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 bölümüne bakın).
Tehdit karması ön ekleri
TehditEntries dizisi, kontrol etmek istediğiniz URL'lerin karma ön eklerini içerir.
hash
alanı, yerel veritabanında bulunan karma oluşturma ön ekini tam olarak içermelidir. Örneğin,
Örneğin, yerel karma öneki 4 bayt uzunluğundaysa tehdit girişi 4 bayt uzunluğunda olmalıdır. Yerel karma ön eki 7 bayta uzatıldıysa tehdit girişi 7 bayt uzunluğunda olmalıdır.
Örnekte istek üç karma ön ek içeriyor. Üç ön ek de karşılaştırılacaktır. karşılaştırabilirsiniz.
Not: Update API ve fullHashes.find yöntemi her zaman hash
alanını, hiçbir zaman URL
alanını kullanmamalıdır (ThreatEntry bölümüne bakın).
HTTP POST yanıtı
Aşağıdaki örnekte yanıt, eşleştirme verilerini Güvenli Tarama listesine göre düzenlenmiş olarak döndürür. önbellek ve bekleme süreleri gösterilir.
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 çekilmelidir (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 uzunluktaki karmalar, varsa meta verileri ve önbellek sürelerini içerir. Örnekte, yanıt metni minimum bekleme süresini de içerir. Daha fazla bilgi için fullHashes.find yanıt gövdesine ve kod örneğinin ardından gelen 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" }
Eşleşmeler
Eşleşmeler nesnesi, karma ön eklerinden ikisi için eşleşen tam uzunluktaki bir karma döndürür. Bu karma oluşturma işlemlerine karşılık gelen URL'ler güvenli değildir. Üçüncü karma ön ekiyle eşleşen bir sonuç bulunamadı. Bu nedenle, hiçbir şey döndürülmez. Bu karma ön ekiyle ilişkili URL güvenli kabul edilir.
Bu örneğin, tam uzunluktaki bir karmayı bir karma önekiyle eşleştirdiğini unutmayın. ancak aynı karma ön eki ile eşlenen birden çok tam karma oluşturmalıdır.
Meta veri
threatEntryMetadata
alanı isteğe bağlıdır ve tehdit eşleşmesi hakkında ek bilgiler sağlar. Şu anda meta veriler, Güvenli Tarama'daki MALWARE/WINDOWS/URL listesi için kullanılabilir (Meta Veriler bölümüne bakın).
Önbellek süreleri
cacheDuration
ve negativeCacheDuration
alanları, tutarı belirtir
karmaların
bu içeriklerin güvenli olmadığı kabul edilir (Önbelleğe alma bölümüne bakın).
Minimum bekleme süreleri
minimumWaitDuration
alanı, istemcinin önce 300 saniye (5 dakika) beklemesi gerektiğini belirtir
başka bir fullHashes isteği gönderiliyor. Yanıtta bekleme süresinin yer alıp almayabileceğini göz önünde bulundurun
(bkz. İstek Sıklığı).