שימוש ב-Lookup API

סקירה כללית

באמצעות Lookup API, אפליקציות לקוח יכולות לבדוק אם כתובת URL כלולה באחת מהרשימות של Web Risk.

בדיקת כתובות URL

כדי לבדוק אם כתובת URL מופיעה ברשימת Web Risk, שולחים בקשת HTTP GET לשיטה uris.search:

• ה-API של כלי החיפוש תומך בכתובת URL אחת לכל בקשה. כדי לבדוק כמה כתובות URL, צריך לשלוח בקשה נפרדת לכל כתובת URL.

• אפשר לציין כמה סוגי איומים בבקשה אחת על ידי חזרה על השדה threatTypes. לדוגמה:

  &threatTypes=SOCIAL_ENGINEERING&threatTypes=MALWARE
  

• כתובת ה-URL צריכה להיות תקינה (ראו RFC 2396), אבל לא צריך לבצע קנוניזציה.

• אם משתמשים ב-API בארכיטקטורת REST, צריך לקודד פרמטרים של GET, כמו ה-URI.

• תגובת ה-HTTP GET מחזירה את סוגי האיומים התואמים, אם יש כאלה, יחד עם תפוגת המטמון.

דוגמה: uris.search

ה-method של ה-HTTP וכתובת ה-URL:

GET https://webrisk.googleapis.com/v1/uris:search?threatTypes=MALWARE&uri=http%3A%2F%2Ftestsafebrowsing.appspot.com%2Fs%2Fmalware.html&key=API_KEY

כדי לשלוח את הבקשה אתם צריכים לבחור אחת מהאפשרויות הבאות:

curl

מריצים את הפקודה הבאה:

curl -X GET \
     "https://webrisk.googleapis.com/v1/uris:search?threatTypes=MALWARE&uri=http%3A%2F%2Ftestsafebrowsing.appspot.com%2Fs%2Fmalware.html&key=API_KEY"

PowerShell

מריצים את הפקודה הבאה:

$headers = @{  }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://webrisk.googleapis.com/v1/uris:search?threatTypes=MALWARE&uri=http%3A%2F%2Ftestsafebrowsing.appspot.com%2Fs%2Fmalware.html&key=API_KEY" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "threat": {
    "threatTypes": [
      "MALWARE"
    ],
    "expireTime": "2019-07-17T15:01:23.045123456Z"
  }
}

Java

import com.google.cloud.webrisk.v1.WebRiskServiceClient;
import com.google.webrisk.v1.SearchUrisRequest;
import com.google.webrisk.v1.SearchUrisResponse;
import com.google.webrisk.v1.ThreatType;
import java.io.IOException;

public class SearchUri {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    // The URI to be checked for matches.
    String uri = "http://testsafebrowsing.appspot.com/s/malware.html";

    // The ThreatLists to search in. Multiple ThreatLists may be specified.
    ThreatType threatType = ThreatType.MALWARE;

    searchUri(uri, threatType);
  }

  // This method is used to check whether a URI is on a given threatList. Multiple threatLists may
  // be searched in a single query.
  // The response will list all requested threatLists the URI was found to match. If the URI is not
  // found on any of the requested ThreatList an empty response will be returned.
  public static void searchUri(String uri, ThreatType threatType) throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the `webRiskServiceClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (WebRiskServiceClient webRiskServiceClient = WebRiskServiceClient.create()) {

      SearchUrisRequest searchUrisRequest =
          SearchUrisRequest.newBuilder()
              .addThreatTypes(threatType)
              .setUri(uri)
              .build();

      SearchUrisResponse searchUrisResponse = webRiskServiceClient.searchUris(searchUrisRequest);

      if (!searchUrisResponse.getThreat().getThreatTypesList().isEmpty()) {
        System.out.println("The URL has the following threat: ");
        System.out.println(searchUrisResponse);
      } else {
        System.out.println("The URL is safe!");
      }
    }
  }
}

Python

from google.cloud import webrisk_v1
from google.cloud.webrisk_v1 import SearchUrisResponse


def search_uri(
    uri: str, threat_type: webrisk_v1.ThreatType.MALWARE
) -> SearchUrisResponse:
    """Checks whether a URI is on a given threatList.

    Multiple threatLists may be searched in a single query. The response will list all
    requested threatLists the URI was found to match. If the URI is not
    found on any of the requested ThreatList an empty response will be returned.

    Args:
        uri: The URI to be checked for matches
            Example: "http://testsafebrowsing.appspot.com/s/malware.html"
        threat_type: The ThreatLists to search in. Multiple ThreatLists may be specified.
            Example: threat_type = webrisk_v1.ThreatType.MALWARE

    Returns:
        SearchUrisResponse that contains a threat_type if the URI is present in the threatList.
    """
    webrisk_client = webrisk_v1.WebRiskServiceClient()

    request = webrisk_v1.SearchUrisRequest()
    request.threat_types = [threat_type]
    request.uri = uri

    response = webrisk_client.search_uris(request)
    if response.threat.threat_types:
        print(f"The URI has the following threat: {response}")
    else:
        print("The URL is safe!")
    return response

אם אין תוצאות שתואמות לבקשה, תקבלו תגובת JSON ריקה של {}. המשמעות היא שכתובת ה-URL שסיפקת לא מופיעה באף רשימת איומים.

משכי זמן של מטמון

בשדה expireTime מציינים את חותמת הזמן שבה ההתאמה אמורה להיחשב כהתאמה שתוקפה פג. פרטים נוספים מופיעים במאמר בנושא שמירה במטמון.

מה השלב הבא?

מידע נוסף על שימוש ב-Update API