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

Safe Browsing Update API (v4)

개요

Update API를 사용하면 클라이언트 애플리케이션이 로컬 데이터베이스에 저장할 Safe Browsing 목록의 해시 버전을 다운로드할 수 있습니다. 그런 다음 로컬에서 URL을 확인할 수 있습니다. 로컬 데이터베이스에 일치하는 항목이 있는 경우에만 클라이언트가 세이프 브라우징 서버에 요청을 보내 URL이 세이프 브라우징 목록에 포함되어 있는지 확인해야 합니다.

Update API를 사용하기 전에 로컬 데이터베이스를 설정해야 합니다. 세이프 브라우징에서는 시작하는 데 사용할 수 있는 Go 패키지를 제공합니다. 자세한 내용은 로컬 데이터베이스의 데이터베이스 설정 섹션을 참고하세요.

로컬 데이터베이스 업데이트

최신 상태를 유지하기 위해 클라이언트는 로컬 데이터베이스로 이동합니다 대역폭을 절약하기 위해 클라이언트는 원시 URL이 아닌 URL의 해시 접두사를 다운로드합니다. 예를 들어 'www.badurl.com/'이 안전한 탐색 목록에 있는 경우 클라이언트는 URL 자체가 아닌 해당 URL의 SHA256 해시 접두사를 다운로드합니다. 대부분의 경우 해시 프리픽스는 4바이트입니다. 즉, 단일 목록 항목을 다운로드하는데 필요한 평균 대역폭 비용은 압축 전 4바이트입니다.

로컬 데이터베이스에서 세이프 브라우징 목록을 업데이트하려면 POST threatListUpdates.fetch 메서드를 사용하여 축소하도록 요청합니다.

HTTP POST 요청에는 다양한 클라이언트와 함께 업데이트할 목록의 이름이 포함됩니다. 제약 조건을 조정하여 메모리 및 대역폭 제한을 감당할 수 있습니다.
HTTP POST 응답은 전체 업데이트 또는 부분 업데이트를 반환합니다. 응답 있습니다.

예: ThreatListUpdates.fetch

HTTP POST 요청

다음 예에서는 단일 세이프 브라우징 목록의 업데이트가 요청됩니다.

요청 헤더

요청 헤더에는 요청 URL과 콘텐츠 유형이 포함됩니다. API를 대체해야 함 URL에서 API_KEY에 대한 키를 사용하면 됩니다.

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

요청 본문

요청 본문에는 클라이언트 정보(ID 및 버전)와 업데이트 정보(목록 이름, 목록 상태, 클라이언트 제약조건)가 포함됩니다. 자세한 내용은 threatListUpdates.fetch 요청 본문 코드 예제 다음에 나오는 설명을 확인할 수 있습니다

{
  "client": {
    "clientId":       "yourcompanyname",
    "clientVersion":  "1.5.2"
  },
  "listUpdateRequests": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "state":           "Gg4IBBADIgYQgBAiAQEoAQ==",
    "constraints": {
      "maxUpdateEntries":      2048,
      "maxDatabaseEntries":    4096,
      "region":                "US",
      "supportedCompressions": ["RAW"]
    }
  }]
}

고객 정보

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

세이프 브라우징 목록

threatType, platformType, threatEntryType 필드는 결합되어 세이프 브라우징 목록을 식별합니다(이름 지정). 이 예에서는 하나의 목록이 식별됩니다. 악성코드/Windows/URL. 요청을 보내기 전에 지정하는 유형 조합이 유효한지 확인하세요. (세이프 브라우징 목록 참고).

클라이언트 상태

state 필드에는 세이프 브라우징 목록의 현재 클라이언트 상태가 포함됩니다. 클라이언트 상태는newClientState threatListUpdates.fetch response를 포함합니다. 초기 업데이트의 경우 state 필드를 비워둡니다.

크기 제한

maxUpdateEntries 필드는 클라이언트가 관리할 수 있는 총 업데이트 수를 지정합니다(예: 2048). maxDatabaseEntries 필드는 로컬 데이터베이스가 관리할 수 있는 총 항목 수를 지정합니다(예: 4096). 클라이언트는 메모리 및 대역폭 제한을 보호하고 목록 증가를 방지하기 위해 크기 제한을 설정해야 합니다. 자세한 내용은 업데이트 제약조건을 참고하세요.

지원되는 압축

supportedCompressions 필드에는 클라이언트가 지원하는 압축 유형이 나열됩니다. 예를 들어 클라이언트는 압축되지 않은 원시 데이터만 지원합니다. 하지만 세이프 브라우징은 압축 유형 (압축 참고)

HTTP POST 응답

이 예시에서 응답은 요청된 압축 유형을 사용하여 세이프 브라우징 목록의 부분 업데이트를 반환합니다.

응답 헤더

응답 헤더에는 HTTP 상태 코드와 콘텐츠 유형이 포함됩니다. HTTP/200 이외의 상태 코드를 수신하는 클라이언트는 백오프 모드로 전환해야 합니다. 요청 빈도를 참조하세요.

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

응답 본문

응답 본문에는 업데이트 정보 (목록 이름, 응답 유형, 로컬 데이터베이스, 새 클라이언트에 적용할 추가 및 삭제 체크섬)을 나타냅니다. 이 예시에서는 최소 대기 시간도 응답에 포함됩니다. 자세한 내용은 threatListUpdates.fetch 응답 본문 및 코드 예시 뒤에 나오는 설명을 참고하세요.

{
  "listUpdateResponses": [{
    "threatType":      "MALWARE",
    "threatEntryType": "URL",
    "platformType":    "WINDOWS",
    "responseType" :   "PARTIAL_UPDATE",
    "additions": [{
      "compressionType": "RAW",
      "rawHashes": {
        "prefixSize": 4,
        "rawHashes":  "rnGLoQ=="
      }
    }],
    "removals": [{
      "compressionType": "RAW",
      "rawIndices": {
        "indices": [0, 2, 4]
      }
    }],
    "newClientState": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
    "checksum": {
      "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
    }
  }],
  "minimumWaitDuration": "593.440s"
}

데이터베이스 업데이트

responseType 필드는 부분 또는 전체 업데이트를 나타냅니다. 이 예시에서는 부분 업데이트가 반환되므로 응답에 추가와 삭제가 모두 포함됩니다. 여러 집합이 있을 수 있습니다. 하나의 삭제 집합만 포함 데이터베이스 업데이트를 참조하세요.

새 클라이언트 상태

newClientState 필드에는 새로 업데이트된 Safe Browsing 목록의 새 클라이언트 상태가 포함됩니다. 클라이언트는 후속 업데이트 요청을 위해 새 클라이언트 상태를 저장해야 합니다(threatListUpdates.fetch 요청의 state 필드 또는 fullHashes.find 요청의 clientStates 필드).

검사합

체크섬을 사용하면 클라이언트가 로컬 데이터베이스에서 손상이 발생하지 않았는지 확인할 수 있습니다. 체크섬이 일치하지 않으면 클라이언트는 데이터베이스를 지우고 빈 state 필드가 포함된 업데이트를 다시 실행해야 합니다. 하지만 이 상황에서 클라이언트는 여전히 업데이트 시간 간격을 따라야 합니다. 요청 빈도를 참조하세요.

최소 대기 시간

minimumWaitDuration 필드는 클라이언트가 593.44초 (9.89분) 동안 기다려야 함을 나타냅니다. 다른 업데이트 요청을 보내야 합니다. 참고로 (요청 빈도 참조)

URL 확인

URL이 세이프 브라우징 목록에 있는지 확인하려면 클라이언트가 먼저 URL의 해시 및 해시 프리픽스를 계산해야 합니다(URL 및 해싱 참고). 클라이언트 일치하는 항목이 있는지 확인하기 위해 로컬 데이터베이스를 쿼리합니다. 로컬 데이터베이스에 해시 접두사가 없는 경우 이 URL은 안전한 것으로 간주됩니다(세이프 브라우징 목록에 없음).

로컬 데이터베이스에 해시 접두사가 있는 경우 (해시 접두사 충돌) 클라이언트는 확인을 위해 세이프 브라우징 서버에 해시 접두사를 보내야 합니다. 서버는 주어진 해시 접두어를 포함하는 모든 전체 길이 SHA 256 해시를 반환합니다. 이러한 전체 길이 해시 중 하나가 문제의 URL의 전체 길이 해시와 일치하면 URL이 안전하지 않은 것으로 간주합니다. 전체 길이 해시가 전체 길이 해시와 일치하지 않는 경우 해당 URL이 안전한 경우 해당 URL은 안전한 것으로 간주됩니다.

Google은 검토 중인 URL에 대해 학습하지 않습니다. Google은 URL의 해시 접두사를 학습하지만 해시 접두사는 실제 URL에 대한 많은 정보를 제공하지 않습니다.

URL이 세이프 브라우징 목록에 있는지 확인하려면 fullHashes.find 메서드에 HTTP POST 요청을 보냅니다.

HTTP POST 요청에는 최대 500개의 위협 항목이 포함될 수 있습니다.
HTTP POST 요청에는 확인할 URL의 해시 프리픽스가 포함됩니다. 클라이언트는 대역폭 사용량을 낮추기 위해 여러 개의 위협 항목을 단일 요청으로 일괄 처리하는 것이 좋습니다.
HTTP POST 응답은 일치하는 전체 길이 해시를 양수 및 음수 캐시 기간과 함께 반환합니다. 응답은 최소 대기 기간을 반환할 수도 있습니다.

예: fullHashes.find

HTTP POST 요청

다음 예에서는 두 개의 세이프 브라우징 목록과 3개의 해시 접두사의 이름이 비교 및 검증에 사용합니다.

요청 헤더

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

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

요청 본문

요청 본문에는 클라이언트 정보 (ID 및 버전), 클라이언트 상태, 위협 정보 (목록 이름 및 해시 접두사) JSON 요청의 경우 해시 접두사는 base64 인코딩된 형식으로 전송되어야 합니다. 자세한 내용은 fullHashes.find 요청 본문 및 코드 예시 뒤에 나오는 설명을 참고하세요.

{
  "client": {
    "clientId":      "yourcompanyname",
    "clientVersion": "1.5.2"
  },
  "clientStates": [
    "ChAIARABGAEiAzAwMSiAEDABEAE=",
    "ChAIAhABGAEiAzAwMSiAEDABEOgH"
  ],
  "threatInfo": {
    "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
    "platformTypes":    ["WINDOWS"],
    "threatEntryTypes": ["URL"],
    "threatEntries": [
      {"hash": "WwuJdQ=="},
      {"hash": "771MOg=="},
      {"hash": "5eOrwQ=="}
    ]
  }
}

클라이언트 정보

clientID 및 clientVersion 필드는 확인할 수 있습니다 클라이언트 정보는 서버 측 로깅에 사용됩니다. 고객 ID의 이름은 무엇이든 지정할 수 있지만 고객의 실제 ID를 나타내는 이름(예: 회사 이름)을 선택하는 것이 좋습니다. 회사 이름은 단일 단어로 표시하고 모두 소문자로 작성합니다.

모든 클라이언트 상태

clientStates 필드에는 클라이언트의 로컬 데이터베이스에 있는 모든 세이프 브라우징 목록의 클라이언트 상태가 포함됩니다. 클라이언트 상태는newClientState threatListUpdates.fetch response를 포함합니다.

세이프 브라우징 목록

threatTypes, platformTypes, threatEntryTypes 필드를 조합하여 세이프 브라우징 목록을 식별(이름 지정)합니다. 이 예에서는 두 개의 목록(MALWARE/WINDOWS/URL 및 SOCIAL_ENGINEERING/WINDOWS/URL을 사용합니다. 요청을 보내기 전에 사용하려는 유형 조합이 유효한지 확인하세요 (세이프 브라우징 목록 참고).

위협 해시 프리픽스

위협 항목 배열에는 확인하려는 URL의 해시 접두사가 포함되어 있습니다. hash 필드에는 로컬 데이터베이스에 있는 정확한 해시 접두사가 포함되어야 합니다. 대상 예를 들어, 로컬 해시 접두사의 길이가 4바이트라면 위협 엔트리의 길이가 4바이트여야 합니다. 로컬 해시 접두사가 7바이트로 늘어난 경우 위협 항목은 7바이트여야 합니다.

이 예에서는 요청에 해시 프리픽스 3개가 포함되어 있습니다. 3개의 프리픽스가 모두 비교됩니다. 를 사용하여 일치하는 전체 길이 해시가 있는지 확인합니다.

참고: Update API 및 fullHashes.find 메서드는 항상 hash 필드를 사용해야 하며 URL 필드는 사용하면 안 됩니다(ThreatEntry 참고).

HTTP POST 응답

다음 예시에서는 응답이 캐시 및 대기 시간과 함께 세이프 브라우징 목록별로 정리된 일치 데이터를 반환합니다.

응답 헤더

응답 헤더에는 HTTP 상태 코드가 포함됩니다. 지정할 수 있습니다. HTTP/200 이외의 상태 코드를 수신하는 클라이언트는 백오프해야 합니다( 요청 빈도).

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

응답 본문

응답 본문에는 일치 정보(목록 이름, 전체 길이 해시, 메타데이터(있는 경우), 캐시 기간)가 포함됩니다. 이 예에서 응답 본문에는 최소 대기 시간이 짧습니다 자세한 내용은 fullHashes.find 응답 본문 및 코드 예시 뒤에 나오는 설명을 참고하세요.

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4="
    },
    "threatEntryMetadata": {
      "entries": [{
        "key": "bWFsd2FyZV90aHJlYXRfdHlwZQ==",  // base64-encoded "malware_threat_type"
        "value": "TEFORElORw=="  // base64-encoded "LANDING"
       }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "SOCIAL_ENGINEERING",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "771MOrRPMn6xPKlCrXx_CrR-wmCk0LgFFoSgGy7zUiA="
    },
    "threatEntryMetadata": {
      "entries": []
    },
    "cacheDuration": "300.000s"
  }],
  "minimumWaitDuration": "300.000s",
  "negativeCacheDuration": "300.000s"
}

매치

일치 객체는 두 해시 접두사에 대해 일치하는 전체 길이의 해시를 반환합니다. URL 안전하지 않은 것으로 간주됩니다 세 번째 해시 접두사에 일치하는 항목이 없으므로 아무것도 반환되지 않습니다. 이 해시 접두사에 해당하는 URL은 안전한 것으로 간주됩니다.

이 예에서는 하나의 전체 길이 해시를 하나의 해시 접두사로 일치시킵니다. 그러나 동일한 해시 접두사로 매핑되는 전체 해시가 여러 개 있을 수 있습니다.

메타데이터

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

캐시 기간

cacheDuration 및 negativeCacheDuration 필드는 해시를 안전하지 않거나 안전하다고 간주해야 하는 시간을 나타냅니다(캐싱 참고).

최소 대기 시간

minimumWaitDuration 필드는 클라이언트가 300초 (5분) 동안 대기해야 함을 나타냅니다. 또 다른 fullHashes 요청을 보내는 중. 응답에 대기 시간이 포함될 수도 있고 포함되지 않을 수도 있습니다. 요청 빈도를 참조하세요.