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이 안전하지 않은 것으로 간주되어야 하는 시간을 나타냅니다.
(캐싱 참조).
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-07-25(UTC)
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-07-25(UTC)"],[[["\u003cp\u003eThe Lookup API allows client applications to send requests to Safe Browsing servers to check if URLs are on any Safe Browsing lists, returning matching information if found.\u003c/p\u003e\n"],["\u003cp\u003eTo check URLs, send an HTTP \u003ccode\u003ePOST\u003c/code\u003e request to the \u003ccode\u003ethreatMatches.find\u003c/code\u003e method, including up to 500 URLs in the request body with desired threat types and platform types.\u003c/p\u003e\n"],["\u003cp\u003eThe API response returns an empty object if no matches are found, or a \u003ccode\u003ematches\u003c/code\u003e object containing matching URLs, list names, metadata (if available), and cache durations.\u003c/p\u003e\n"],["\u003cp\u003eClient applications should uniquely identify themselves using \u003ccode\u003eclientId\u003c/code\u003e and \u003ccode\u003eclientVersion\u003c/code\u003e fields in the request body for server-side logging and accounting.\u003c/p\u003e\n"],["\u003cp\u003eThe API uses the \u003ccode\u003eURL\u003c/code\u003e field for threat entries and currently provides metadata for the MALWARE/WINDOWS/URL Safe Browsing list.\u003c/p\u003e\n"]]],["The Lookup API checks URLs against Safe Browsing lists via HTTP `POST` requests to the `threatMatches.find` method, which can include up to 500 URLs. Requests specify client and threat information, including threat types, platform types, and URLs. The response indicates matches, providing the list names, matching URLs, optional metadata, and cache duration. If no matches are found, the response returns an empty object. Client information must uniquely identify client implementations.\n"],null,["# Safe Browsing Lookup API (v4)\n\nOverview\n--------\n\nThe Lookup API lets your client applications send requests to the Safe Browsing\nservers to check if URLs are included on any of the Safe Browsing lists. If a URL is found on one or\nmore lists, the matching information is returned.\n\nChecking URLs\n-------------\n\nTo check if a URL is on a Safe Browsing list, send an HTTP `POST` request to the\n[threatMatches.find](/safe-browsing/reference/rest/v4/threatMatches/find)\nmethod:\n\n- The HTTP `POST` request can include up to 500 URLs. The URLs must be valid (see [RFC 2396](http://www.ietf.org/rfc/rfc2396.txt)) but they do not need to be canonicalized or encoded.\n- The HTTP `POST` response returns the matching URLs along with the cache duration.\n\nExample: threatMatches.find\n---------------------------\n\n### HTTP POST request\n\nIn the following example, two Safe Browsing lists and three URLs are sent to the server to\ndetermine if there is a match.\n\n#### Request header\n\nThe request header includes the request URL and the content type. Remember to substitute\nyour API key for `API_KEY` in the URL. \n\n```scdoc\n POST https://safebrowsing.googleapis.com/v4/threatMatches:find?key=API_KEY HTTP/1.1\n Content-Type: application/json\n \n```\n\n#### Request body\n\nThe request body includes the client information (ID and version) and the threat information\n(the list names and the URLs). For more details, see the\n[threatMatches.find request body](/safe-browsing/reference/rest/v4/threatMatches/find#request-body)\nand the explanations that follow the code example. \n\n```scdoc\n {\n \"client\": {\n \"clientId\": \"yourcompanyname\",\n \"clientVersion\": \"1.5.2\"\n },\n \"threatInfo\": {\n \"threatTypes\": [\"MALWARE\", \"SOCIAL_ENGINEERING\"],\n \"platformTypes\": [\"WINDOWS\"],\n \"threatEntryTypes\": [\"URL\"],\n \"threatEntries\": [\n {\"url\": \"http://www.urltocheck1.org/\"},\n {\"url\": \"http://www.urltocheck2.org/\"},\n {\"url\": \"http://www.urltocheck3.com/\"}\n ]\n }\n }\n```\n\n###### Client information\n\nThe `clientID` and `clientVersion` fields should uniquely identify a client implementation, not an\nindividual user. (Client information is used for server-side logging and accounting. You can choose\nany name for the client ID, but we suggest you choose a name that represents the true identity of the\nclient, such as your company name, presented as all one word, in all-lowercase letters.)\n\n###### Safe Browsing lists\n\nThe `threatType`, `platformType`, and `threatEntryType` fields\nare combined to identify (name) Safe Browsing lists. In the example, two lists are identified:\nMALWARE/WINDOWS/URL and SOCIAL_ENGINEERING/WINDOWS/URL. Before sending a request, make sure the type\ncombinations you specify are valid (see [Safe Browsing Lists](/safe-browsing/v4/lists)).\n\n###### Threat URLs\n\nIn the example, the `threatEntries` array contains three URLs (urltocheck1.org, urltocheck2.org,\nand urltocheck3.org) that will be checked against the two Safe Browsing lists.\n\n**Note:** The Lookup API and the `threatMatches` method should always use the `URL` field,\nnever the `hash` field (see [ThreatEntry](/safe-browsing/reference/rest/v4/ThreatEntry)).\n\n### HTTP POST response\n\nIn the following example, the response returns a match; two of the three URLs specified in the\nrequest are found on one of the two Safe Browsing lists specified in the request.\n\n#### Response header\n\nThe response header includes the [HTTP status code](/safe-browsing/v4/status-codes)\nand the content type. \n\n```http\nHTTP/1.1 200 OK\nContent-Type: application/json\n```\n\n#### Response body\n\nThe response body includes the match information (the list names and the URLs found on\nthose lists, the metadata, if available, and the cache durations). For more details, see the\n[threatMatches.find response body](/safe-browsing/reference/rest/v4/threatMatches/find#response-body)\nand the explanations that follow the code example.\n\n**Note:** If there are no matches (that is, if *none* of the URLs specified\nin the request are found on *any* of the lists specified in a request), the HTTP `POST` response\nsimply returns an empty object in the response body. \n\n```carbon\n{\n \"matches\": [{\n \"threatType\": \"MALWARE\",\n \"platformType\": \"WINDOWS\",\n \"threatEntryType\": \"URL\",\n \"threat\": {\"url\": \"http://www.urltocheck1.org/\"},\n \"threatEntryMetadata\": {\n \"entries\": [{\n \"key\": \"malware_threat_type\",\n \"value\": \"landing\"\n }]\n },\n \"cacheDuration\": \"300.000s\"\n }, {\n \"threatType\": \"MALWARE\",\n \"platformType\": \"WINDOWS\",\n \"threatEntryType\": \"URL\",\n \"threat\": {\"url\": \"http://www.urltocheck2.org/\"},\n \"threatEntryMetadata\": {\n \"entries\": [{\n \"key\": \"malware_threat_type\",\n \"value\": \"landing\"\n }]\n },\n \"cacheDuration\": \"300.000s\"\n }]\n}\n```\n\n###### Matches\n\nThe `matches` object lists the names of the Safe Browsing lists and the URLs---if\nthere is match. In the example, two URLs (urltocheck1.org and urltocheck2.org) were found on one of\nthe Safe Browsing lists (MALWARE/WINDOWS/URL) so the matching information is returned. The third URL\n(urltocheck3.org) was not found on either list, so no information is returned for this URL.\n\n###### Metadata\n\nThe `threatEntryMetadata` field is optional and provides additional information about\nthe threat match. Currently, metadata is available for the MALWARE/WINDOWS/URL Safe Browsing list\n(see [Metadata](/safe-browsing/v4/metadata)).\n\n###### Cache durations\n\nThe `cacheDuration` field indicates the amount of time the URL must be considered unsafe\n(see [Caching](/safe-browsing/v4/caching))."]]
