Descripción general
La API de Lookup permite que tus aplicaciones cliente envíen solicitudes a los servidores de Navegación segura para verificar si las URL se incluyen en alguna de sus listas de Navegación segura. Si se encuentra una URL en una o más listas, se muestra la información de coincidencia.
Verifica las URL
Para verificar si una URL está en una lista de Navegación segura, envía una solicitud HTTP POST al método threatMatches.find:
- La solicitud HTTP
POSTpuede incluir hasta 500 URL. Las URL deben ser válidas (consulta RFC 2396), pero no es necesario que se las canonicaliza ni se codifiquen. - La respuesta HTTP
POSTmuestra las URLs coincidentes junto con la duración de la caché.
Ejemplo: ThreatMatches.find
Solicitud HTTP POST
En el siguiente ejemplo, se envían dos listas de Navegación segura y tres URL al servidor para determinar si hay una coincidencia.
Encabezado de la solicitud
El encabezado de la solicitud incluye la URL de la solicitud y el tipo de contenido. Recuerda sustituir tu clave de API por API_KEY en la URL.
POST https://safebrowsing.googleapis.com/v4/threatMatches:find?key=API_KEY HTTP/1.1 Content-Type: application/json
Cuerpo de la solicitud
El cuerpo de la solicitud incluye la información del cliente (ID y versión) y la información sobre las amenazas (los nombres de las listas y las URLs). Para obtener más detalles, consulta el cuerpo de la solicitudthreatMatches.find y las explicaciones que siguen al ejemplo de código.
{
"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/"}
]
}
}
Información del cliente
Los campos clientID y clientVersion deben identificar de manera única una implementación cliente, no un usuario individual. (La información del cliente se usa para el registro y la contabilidad del servidor. Puedes elegir cualquier nombre para el ID de cliente, pero te sugerimos que elijas uno que represente la verdadera identidad del cliente, como el nombre de tu empresa, presentado como una sola palabra, en letras minúsculas.
Listas de Navegación segura
Los campos threatType, platformType y threatEntryType se combinan para identificar las listas de Navegación segura de (nombre). En el ejemplo, se identifican dos listas: MALWARE/WINDOWS/URL y SOCIAL_ENGINEERING/WINDOWS/URL. Antes de enviar una solicitud, asegúrate de que las combinaciones de tipo que especifiques sean válidas (consulta Listas de navegación segura).
URLs de amenazas
En el ejemplo, el array threatEntries contiene tres URLs (urltocheck1.org, urltocheck2.org y urltocheck3.org) que se compararán con las dos listas de Navegación segura.
Nota: La API de Lookup y el método threatMatches siempre deben usar el campo URL, nunca el campo hash (consulta ThreatEntry).
Respuesta HTTP POST
En el siguiente ejemplo, la respuesta muestra una coincidencia; dos de las tres URL especificadas en la solicitud se encuentran en una de las dos listas de Navegación segura especificadas en la solicitud.
Encabezado de respuesta
El encabezado de respuesta incluye el código de estado HTTP y el tipo de contenido.
HTTP/1.1 200 OK Content-Type: application/json
Cuerpo de la respuesta
El cuerpo de la respuesta incluye la información de coincidencia (los nombres de las listas y las URL que se encuentran en esas listas, los metadatos, si están disponibles, y las duraciones de la caché). Para obtener más detalles, consulta el cuerpo de la respuestathreatMatches.find y las explicaciones que siguen al ejemplo de código.
Nota: Si no hay coincidencias (es decir, si ninguna de las URL especificadas en la solicitud se encuentra en cualquiera de las listas especificadas en una solicitud), la respuesta HTTP POST simplemente muestra un objeto vacío en el cuerpo de la respuesta.
{
"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"
}]
}
Mostrar coincidencias
Si hay una coincidencia, el objeto matches enumera los nombres de las listas de Navegación segura y las URLs. En el ejemplo, se encontraron dos URLs (urltocheck1.org y urltocheck2.org) en una de las listas de Navegación segura (MALWARE/WINDOWS/URL), por lo que se muestra la información coincidente. La tercera URL (urltocheck3.org) no se encontró en ninguna de las listas, por lo que no se muestra información para esta URL.
Metadata
El campo threatEntryMetadata es opcional y proporciona información adicional sobre la coincidencia de la amenaza. Actualmente, los metadatos están disponibles para la lista de Navegación segura de MALWARE/WINDOWS/URL (consulta Metadatos).
Duraciones de la caché
El campo cacheDuration indica la cantidad de tiempo que la URL debe considerarse no segura (consulta Almacenamiento en caché).