이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Safe Browsing Lookup API (v4)

개요

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

URL 확인

URL이 세이프 브라우징 목록에 있는지 확인하려면 다음과 같이 HTTP POST 요청을 threatMatches.find 메서드에 전송합니다.

HTTP POST 요청에는 최대 500개의 URL이 포함될 수 있습니다. URL은 유효해야 하지만(RFC 2396 참조) 표준화되거나 인코딩될 필요는 없습니다.
HTTP POST 응답은 캐시 기간과 함께 일치하는 URL을 반환합니다.

예: threatMatch.find

HTTP POST 요청

다음 예에서는 일치하는지 확인하기 위해 2개의 세이프 브라우징 목록과 3개의 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 메서드는 항상 hash 필드가 아닌 URL 필드를 사용해야 합니다 (ThreatEntry 참고).

HTTP POST 응답

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

응답 헤더

응답 헤더에는 HTTP 상태 코드와 콘텐츠 유형이 포함됩니다.

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

응답 본문

응답 본문에는 일치 정보 (목록 이름 및 목록에서 발견된 URL, 메타데이터, 사용 가능한 경우, 캐시 기간)가 포함됩니다. 자세한 내용은 threatMatch.find 응답 본문과 코드 예시 이후의 설명을 참고하세요.

참고: 일치하는 항목이 없는 경우 (즉, 요청에 지정된 목록 하나에서 없음이 발견되는 경우) 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(일치하는 경우)을 나열합니다. 이 예에서는 세이프 브라우징 목록 (멀웨어/WINDOWS/URL) 중 하나에서 URL 2개 (urltocheck1.org 및 urltocheck2.org)가 발견되었으므로 일치하는 정보가 반환됩니다. 세 번째 URL(urltocheck3.org)은 어느 목록에서도 찾을 수 없으므로 이 URL에 관한 정보가 반환되지 않습니다.

메타데이터

threatEntryMetadata 필드는 선택사항이며 위협 일치에 대한 추가 정보를 제공합니다. 현재 메타데이터는 멀웨어/WINDOWS/URL 세이프 브라우징 목록에 사용할 수 있습니다(메타데이터 참고).

캐시 기간

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