Safe Browsing Lookup API (v4)

개요

Lookup API를 사용하면 클라이언트 애플리케이션에서 세이프 브라우징에 요청을 보낼 수 있습니다. 를 사용하여 URL이 세이프 브라우징 목록에 포함되어 있는지 확인합니다. 하나 이상의 일치하는 정보가 반환됩니다.

URL 확인

URL이 세이프 브라우징 목록에 있는지 확인하려면 HTTP POST 요청을 threatMatches.find 메서드를 사용하여 축소하도록 요청합니다.

  • HTTP POST 요청은 URL을 최대 500개까지 포함할 수 있습니다. 유효한 URL이어야 합니다. (RFC 2396 참조) 정규화하거나 인코딩할 필요는 없습니다.
  • HTTP POST 응답은 캐시 기간과 함께 일치하는 URL을 반환합니다.

예: ThreatMatch.find

HTTP POST 요청

다음 예에서는 두 개의 세이프 브라우징 목록과 세 개의 URL이 서버로 전송되어 일치하는 항목이 있는지 확인합니다.

요청 헤더

요청 헤더에는 요청 URL과 콘텐츠 유형이 포함됩니다. 잊지 말고 URL에 있는 API_KEY에 대한 API 키입니다.

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

요청 본문

요청 본문에는 클라이언트 정보 (ID 및 버전)와 위협 정보가 포함됩니다. (목록 이름 및 URL) 자세한 내용은 threatmatch.find 요청 본문 코드 예제 다음에 나오는 설명을 확인할 수 있습니다

  {
    "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/"}
      ]
    }
  }
클라이언트 정보

clientID 및 clientVersion 필드는 확인할 수 있습니다 클라이언트 정보는 서버 측 로깅 및 회계에 사용됩니다. 선택할 수 있는 옵션은 다음과 같습니다. 사용할 수 있지만 클라이언트 ID의 실제 ID를 나타내는 이름을 선택하는 것이 좋습니다. 클라이언트(예: 회사 이름)는 모두 한 단어로 모두 소문자로 표기해야 합니다.

세이프 브라우징 목록

threatType, platformType, threatEntryType 필드 를 결합해 세이프 브라우징 목록을 식별합니다. 이 예에서는 두 개의 목록이 식별됩니다. MALWARE/WINDOWS/URL 및 SOCIAL_ENGINEERING/WINDOWS/URL. 요청을 보내기 전에 유형이 유효한지 확인합니다 (세이프 브라우징 목록 참고).

위협 URL

이 예에서는 threatEntries 배열에 세 개의 URL (urltocheck1.org, urltocheck2.org, 및 urltocheck3.org)을 각각 두 개의 세이프 브라우징 목록과 대조하여 확인합니다.

참고: Lookup API 및 threatMatches 메서드는 항상 URL 필드를 사용해야 합니다. 절대 hash 필드가 아닙니다 (ThreatEntry 참고).

HTTP POST 응답

다음 예에서 응답은 일치 항목을 반환합니다. 두 개의 URL 중 두 개의 URL이 요청이 지정된 두 세이프 브라우징 목록 중 하나에서 발견되는지 확인합니다.

응답 헤더

응답 헤더에는 HTTP 상태 코드가 포함됩니다. 지정할 수 있습니다.

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

응답 본문

응답 본문에는 일치 정보 (목록 이름 및 메타데이터(사용 가능한 경우), 캐시 기간 등의 정보가 포함됩니다. 자세한 내용은 threatmatched.find 응답 본문 코드 예제 다음에 나오는 설명을 확인할 수 있습니다

참고: 일치하는 항목이 없는 경우 (즉, 지정된 URL이 없는 경우) 요청에 지정된 하나의 목록에서 발견되는 경우), HTTP POST 응답 단순히 응답 본문에 빈 객체를 반환합니다.

{
  "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"
  }]
}
일치 동영상

matches 객체는 세이프 브라우징 목록의 이름과 URL을 나열합니다. 일치하는 것입니다. 이 예에서는 두 개의 URL (urltocheck1.org 및 urltocheck2.org)이 일치하는 정보가 반환되도록 세이프 브라우징 목록 (멀웨어/WINDOWS/URL)을 포함시킵니다. 세 번째 URL (urltocheck3.org)가 두 목록에서도 발견되지 않았으므로 이 URL에 대한 정보가 반환되지 않습니다.

메타데이터

threatEntryMetadata 필드는 선택사항이며 다음과 같은 추가 정보를 제공합니다. 있습니다. 현재 메타데이터는 멀웨어/WINDOWS/URL 세이프 브라우징 목록에 사용할 수 있습니다. 메타데이터를 참고하세요.

캐시 기간

cacheDuration 필드는 URL이 안전하지 않은 것으로 간주되어야 하는 시간을 나타냅니다. (캐싱 참조).