Method: hashes.search

지정된 접두사와 일치하는 전체 해시를 검색합니다.

https://google.aip.dev/136에 정의된 대로 맞춤 메서드입니다. 맞춤 메서드는 Google의 일반 API 개발 명명법 내에 맞춤 이름이 있는 이 메서드를 의미하며 맞춤 HTTP 메서드 사용을 의미하지는 않습니다.

HTTP 요청

GET https://safebrowsing.googleapis.com/v5/hashes:search

URL은 gRPC 트랜스코딩 구문을 사용합니다.

쿼리 매개변수

Parameters
hashPrefixes[]

string (bytes format)

필수 항목입니다. 조회할 해시 접두사입니다. 클라이언트는 1,000개가 넘는 해시 접두사를 전송해서는 안 됩니다. 그러나 URL 처리 절차에 따라 클라이언트는 30개가 넘는 해시 접두사를 전송해서는 안 됩니다(SHOULD NOT).

현재 각 해시 접두사는 정확히 4바이트여야 합니다. 향후 이 제한이 완화될 수 있습니다.

base64 인코딩 문자열입니다.

요청 본문

요청 본문은 비어 있어야 합니다.

응답 본문

위협 해시를 검색한 후 반환된 응답입니다.

아무것도 찾을 수 없는 경우 서버는 NOT_FOUND 상태 (HTTP 상태 코드 404)를 반환하는 대신 fullHashes 필드가 비어 있는 OK 상태 (HTTP 상태 코드 200)를 반환합니다.

V5의 새로운 기능: FullHash와 FullHashDetail가 분리됩니다. 해시가 여러 위협 (예: MALWARE 및 SOCIAL_ENGINEERING 모두)이 있는 사이트를 나타내는 경우 V4와 같이 전체 해시를 두 번 전송할 필요가 없습니다. 또한 캐시 기간이 단일 cacheDuration 필드로 단순화되었습니다.

성공한 경우 응답 본문은 다음과 같은 구조의 데이터를 포함합니다.

JSON 표현 
{
  "fullHashes": [
    {
      object (FullHash)
    }
  ],
  "cacheDuration": string
}
필드
fullHashes[]

object (FullHash)

순서가 지정되지 않은 목록 발견된 전체 해시의 순서가 지정되지 않은 목록입니다.
cacheDuration

string (Duration format)

클라이언트 측 캐시 기간입니다. 클라이언트는 만료 시간을 결정하기 위해 이 기간을 현재 시간에 더해야 합니다. 그러면 만료 시간은 응답에 반환되는 전체 해시 수와 관계없이 클라이언트가 요청에서 쿼리한 모든 해시 접두사에 적용됩니다. 서버가 특정 해시 접두어에 대한 전체 해시를 반환하지 않더라도 이 사실은 클라이언트에서 캐시해야 합니다.

fullHashes 필드가 비어 있는 경우에만 클라이언트는 cacheDuration를 늘려 서버에서 지정한 것보다 나중에 만료되는 새 만료를 결정할 수 있습니다. 어떠한 경우든 증가된 캐시 기간은 24시간 이하여야 합니다.

중요: 클라이언트는 서버가 모든 응답에 동일한 캐시 기간을 반환한다고 가정해서는 안 됩니다. 서버는 상황에 따라 응답마다 다른 캐시 기간을 선택할 수 있습니다.

소수점 아래가 최대 9자리까지이고 's'로 끝나는 초 단위 기간입니다. 예를 들면 "3.5s"입니다.

FullHash

하나 이상의 일치 항목으로 식별된 전체 해시입니다.

JSON 표현 
{
  "fullHash": string,
  "fullHashDetails": [
    {
      object (FullHashDetail)
    }
  ]
}
필드
fullHash

string (bytes format)

일치하는 전체 해시입니다. SHA256 해시입니다. 길이는 정확히 32바이트입니다.

base64 인코딩 문자열입니다.
fullHashDetails[]

object (FullHashDetail)

순서가 지정되지 않은 목록 이 전체 해시와 관련된 세부정보를 식별하는 반복된 필드입니다.

FullHashDetail

일치하는 전체 해시에 관한 세부정보입니다.

향후 호환성에 관한 중요 사항: 서버는 언제든지 새로운 위협 유형과 위협 속성을 추가할 수 있습니다. 이러한 추가는 마이너 버전 변경으로 간주됩니다. API에 마이너 버전 번호를 노출하지 않는 것이 Google의 정책이므로 (버전 관리 정책은 https://cloud.google.com/apis/design/versioning 참고) 클라이언트는 클라이언트가 잘못된 것으로 간주하는 ThreatType enum 값 또는 ThreatAttribute enum 값이 포함된 FullHashDetail 메시지를 수신할 준비가 되어 있어야 합니다. 따라서 모든 ThreatType 및 ThreatAttribute enum 값의 유효성을 확인하는 것은 클라이언트의 책임입니다. 값이 유효하지 않은 것으로 간주되면 클라이언트는 전체 FullHashDetail 메시지를 무시해야 합니다.

JSON 표현 
{
  "threatType": enum (ThreatType),
  "attributes": [
    enum (ThreatAttribute)
  ]
}
필드
threatType

enum (ThreatType)

위협 유형입니다. 이 필드는 비어 있지 않습니다.
attributes[]

enum (ThreatAttribute)

순서가 지정되지 않은 목록 전체 해시에 관한 추가 속성입니다. 이 필드는 비어 있을 수 있습니다.

ThreatAttribute

위협의 속성입니다. 이러한 속성은 특정 위협에 추가 의미를 부여할 수 있지만 위협 유형에는 영향을 미치지 않습니다. 예를 들어 한 속성은 낮은 신뢰도를 지정할 수 있고 다른 속성은 더 높은 신뢰도를 지정할 수 있습니다. 향후 더 많은 속성이 추가될 수 있습니다.

열거형
THREAT_ATTRIBUTE_UNSPECIFIED 알 수 없는 속성입니다. 서버에서 이를 반환하면 클라이언트는 괄호로 묶인 FullHashDetail를 완전히 무시해야 합니다.
CANARY 시정 조치에 threatType을 사용해서는 안 된다는 것을 나타냅니다.
FRAME_ONLY threatType이 프레임 시정 조치에만 사용되어야 함을 나타냅니다.