캐시

이 문서는 다음 메서드에 적용됩니다.

• Lookup API (v4): threatMatches.find
• 업데이트 API (v4): fullHashes.find

캐싱 정보

클라이언트 대역폭 사용량을 줄이고 트래픽 급증으로부터 Google을 보호하기 위해 Lookup API 및 Update API의 클라이언트는 위협 데이터의 로컬 캐시를 만들고 유지해야 합니다. Lookup API의 경우 캐시는 클라이언트가 Google에 보내는 threatMatches 요청 수를 줄이는 데 사용됩니다. Update API의 경우 캐시를 사용하여 클라이언트가 Google에 보내는 fullHashes 요청 수를 줄입니다. 각 API의 캐싱 프로토콜은 아래에 요약되어 있습니다.

Lookup API

Lookup API의 클라이언트는 cacheDuration 필드로 정의된 기간 동안 반환된 각 ThreatMatch 항목을 캐시해야 합니다. 그러면 클라이언트는 서버에 후속 threatMatches 요청을 하기 전에 캐시를 확인해야 합니다. 이전에 반환된 ThreatMatch의 캐시 기간이 아직 만료되지 않았다면 클라이언트는 이 항목이 여전히 안전하지 않다고 가정해야 합니다. ThreatMatch 항목을 캐시하면 클라이언트의 API 요청 수가 줄어들 수 있습니다.

예: threatMatch.find

전체 예를 보려면 표 헤더에서 요청 및 응답 링크를 클릭하세요.

URL 확인 threatMatch Request	URL 일치 threatMatch Response	캐싱 동작
"threatEntries": [ {"url": "http://www.urltocheck.org/"} ]	"matches": [{ "threat": {"url": "http://www.urltocheck.org/"}, "cacheDuration": "300.000s" }]	일치 클라이언트는 5분을 기다린 후에 URL http://www.urltocheck.org/가 포함된 새 threatMatches 요청을 보내야 합니다.

Update API

Update API를 사용하여 Google에 전송되는 전체 fullHashes 요청 수를 줄이려면 클라이언트가 로컬 캐시를 유지해야 합니다. API는 포지티브 및 네거티브라는 두 가지 유형의 캐싱을 설정합니다.

양성 캐싱

클라이언트가 특정 안전하지 않은 전체 해시 상태에 관해 반복적으로 질문하지 않도록 하기 위해, 반환된 각 ThreatMatch에는 전체 해시가 안전하지 않은 것으로 간주되는 기간을 나타내는 양의 캐시 기간 (cacheDuration 필드에서 정의됨)이 포함됩니다.

음성 캐싱

클라이언트가 특정 안전한 전체 해시의 상태에 관해 반복적으로 질문하지 않도록 각 fullHashes 응답은 요청된 프리픽스 (negativeCacheDuration 필드에 의해 정의됨)에 음수 캐시 기간을 정의합니다. 이 기간은 요청된 프리픽스가 있는 모든 전체 해시가 요청된 목록에서 안전한 것으로 간주되기 위한 시간을 나타냅니다(서버에서 안전하지 않은 것으로 반환한 해시는 제외). 이러한 캐싱은 많은 트래픽을 수신하는 안전한 URL과 해시 프리픽스의 충돌로 인해 발생할 수 있는 트래픽 과부하를 방지하기 때문에 특히 중요합니다.

캐시 참조

클라이언트는 URL의 상태를 확인하려는 경우 먼저 전체 해시를 계산합니다. 전체 해시 접두사가 로컬 데이터베이스에 있는 경우 클라이언트는 서버에 fullHashes 요청을 하기 전에 캐시를 참조해야 합니다.

먼저 클라이언트는 캐시 적중을 확인해야 합니다. 원하는 전체 해시에 만료되지 않은 포지티브 캐시 항목이 있는 경우 안전하지 않은 것으로 간주해야 합니다. 양수 캐시 항목이 만료된 경우 클라이언트는 연결된 로컬 프리픽스에 fullHashes 요청을 보내야 합니다. 프로토콜에 따라 서버가 전체 해시를 반환하면 안전하지 않은 것으로 간주되고, 그렇지 않으면 안전한 것으로 간주됩니다.

전체 해시에 양수 캐시 항목이 없으면 클라이언트는 음수 캐시 적중이 있는지 확인해야 합니다. 연결된 로컬 프리픽스에 만료되지 않은 네거티브 캐시 항목이 있는 경우 전체 해시가 안전한 것으로 간주됩니다. 음수 캐시 항목이 만료되었거나 존재하지 않는 경우 클라이언트는 연결된 로컬 프리픽스에 fullHashes 요청을 전송하고 응답을 정상적으로 해석해야 합니다.

캐시 업데이트

fullHashes 응답이 수신될 때마다 클라이언트 캐시를 업데이트해야 합니다. cacheDuration 필드별로 전체 해시에 양수 캐시 항목이 생성되거나 업데이트되어야 합니다. 해시 접두사의 음수 캐시 기간도 응답의 negativeCacheDuration 필드별로 생성되거나 업데이트되어야 합니다.

후속 fullHashes 요청이 현재 포지티브로 캐시된 전체 해시를 반환하지 않으면 클라이언트는 포지티브 캐시 항목을 삭제할 필요가 없습니다. 포지티브 캐시 기간은 일반적으로 거짓양성을 빠르게 수정할 수 있도록 몇 분 정도로 짧기 때문에 실제로는 문제가 되지 않습니다.

시나리오 예

다음 예에서는 h(url)이 URL의 해시 프리픽스이고 H(url)는 URL의 전체 길이 해시라고 가정합니다. 즉, h(url) = SHA256(url).substr(4), H(url) = SHA256(url)입니다.

이제 클라이언트 (캐시가 비어 있음)가 example.com/ 을 방문하고 h(example.com/)가 로컬 데이터베이스에 있음을 확인한다고 가정해 보겠습니다. 클라이언트는 해시 프리픽스 h(example.com/)의 전체 길이 해시를 요청하고 전체 길이 해시 H(example.com/)를 양의 캐시 기간 5분, 음수 캐시 기간 1시간과 함께 수신합니다.

포지티브 캐시 기간 5분은 다른 fullHashes 요청을 전송하지 않고 전체 길이 해시 H(example.com/)를 안전하지 않은 것으로 간주해야 하는 기간을 클라이언트에 알려줍니다. 5분 후에 클라이언트가 example.com/을 다시 방문하면 해당 프리픽스 h(example.com/)에 대해 또 다른 fullHashes 요청을 실행해야 합니다. 클라이언트는 새 응답마다 해시 접두사의 음수 캐시 기간을 재설정해야 합니다.

음수 캐시 기간 1시간은 동일한 접두사 h(example.com/)를 공유하는 H(example.com/)를 제외한 다른 모든 전체 길이 해시가 안전한 것으로 간주되어야 하는 시간을 클라이언트에 알려줍니다. 1시간 동안 h(URL) = h(example.com/)인 모든 URL은 안전한 것으로 간주되어야 하므로 H(URL) != H(example.com/)라고 가정하면 fullHashes 요청이 발생하지 않습니다.

fullHashes 응답에 일치하는 항목이 0개 있고 음수 캐시 기간이 설정된 경우 클라이언트는 지정된 음수 캐시 기간 동안 요청된 프리픽스에 fullHashes 요청을 실행하면 안 됩니다.

fullHashes 응답에 일치하는 항목이 하나 이상 포함되어 있으면 전체 응답에 여전히 음수 캐시 기간이 설정됩니다. 이 경우 단일 전체 해시의 캐시 기간은 특정 전체 길이 해시가 클라이언트에서 안전하지 않은 것으로 간주해야 하는 기간을 나타냅니다. ThreatMatch 캐시 기간이 경과한 후 요청된 URL이 캐시의 기존 전체 길이 해시와 일치하는 경우 클라이언트는 해당 해시 프리픽스에 fullHashes 요청을 실행하여 전체 길이 해시를 새로고침해야 합니다. 이 경우 음수 캐시 기간이 적용되지 않습니다. 응답의 음수 캐시 기간은 fullHashes 응답에 없는 전체 길이 해시에만 적용됩니다. 응답에 없는 전체 길이 해시의 경우 클라이언트는 음수 캐시 기간이 경과할 때까지 fullHashes 요청을 실행하지 않아야 합니다.

예: fullHashes.find

전체 예를 보려면 표 헤더에서 요청 및 응답 링크를 클릭하세요.

해시 프리픽스 fullHashes 요청	전체 길이 해시가 일치함 fullHashes 응답	캐싱 동작
"threatEntries": [ {"hash": "0xaaaaaaaa"} ]	"matches": [], "negativeCacheDuration": "3600.000s"	일치하는 항목 없음 클라이언트가 최소 1시간 동안 해시 프리픽스 0xaaaaaaaa에 대한 fullHashes 요청을 전송하면 안 됩니다. 프리픽스가 0xaaaaaaaa인 모든 해시는 1시간 동안 안전한 것으로 간주됩니다.
"threatEntries": [ {"hash": "0xbbbbbbbb"} ]	"matches": [ "threat": {"hash": "0xbbbbbbbb0000..."} "cacheDuration": "600.000s", ], "negativeCacheDuration": "300.000s"	일치하는 항목이 있습니다. 클라이언트는 전체 해시가 0xbbbbbb0000...인 URL을 10분 동안 안전하지 않은 것으로 간주해야 합니다. 클라이언트는 해시 프리픽스가 0xbbbbbbbb인 다른 모든 URL은 5분 동안 안전한 것으로 간주해야 합니다. 5분 후에는 해시 접두사 음수 캐시 항목이 만료됩니다. 0xbbbbbb0000...의 양수 캐시 항목이 아직 만료되지 않았으므로 클라이언트는 해당 해시를 제외한 모든 해시에 fullHashes 요청을 전송해야 합니다.
"threatEntries": [ {"hash": "0xcccccccc"} ]	"matches": [ "threat": {"hash": "0xccccccccdddd..."}, "cacheDuration": "600.000s" ], "negativeCacheDuration": "3600.000s"	일치하는 항목이 있습니다. 클라이언트는 최소 1시간 동안 해시 프리픽스 0xcccccccc에 대한 fullHashes 요청을 보내서는 안 되며, 이 접두어가 안전하다고 가정해서는 안 됩니다. 단, URL의 전체 해시가 캐시된 전체 해시 0xccccccccdddd... 이 경우 클라이언트는 해당 URL을 10분 동안 안전하지 않은 것으로 간주해야 합니다. 10분이 지나면 전체 길이 해시가 만료됩니다. 이후 이 전체 해시를 조회할 때는 새 fullHashes 요청이 트리거됩니다.