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

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이 안전하지 않은 것으로 간주되어야 하는 시간을 나타냅니다. (캐싱 참조).