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