Method: hashes.search

지정된 프리픽스와 일치하는 전체 해시를 검색합니다.

이는 https://google.aip.dev/136에 정의된 커스텀 메서드입니다 (커스텀 메서드는 Google의 일반 API 개발 명명법 내에서 이 메서드를 참조하며 커스텀 HTTP 메서드 사용을 의미하지 않음).

HTTP 요청

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

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

쿼리 매개변수

매개변수
hashPrefixes[]

string (bytes format)

필수 항목입니다. 조회할 해시 프리픽스입니다. 클라이언트는 1,000개를 초과하는 해시 프리픽스를 전송하면 안 됩니다(MUST NOT). 하지만 URL 처리 절차에 따라 클라이언트는 30개를 초과하는 해시 프리픽스를 전송하면 안 됩니다(SHOULD NOT).

현재 각 해시 프리픽스의 길이는 정확히 4바이트여야 합니다. 이 문제는 향후 완화될 수 있습니다(MAY).

base64 인코딩 문자열입니다.
filter

string

선택사항입니다. 클라이언트가 특정 종류의 위협만 검색하는 등 필터링에 관심이 있는 경우 지정할 수 있습니다. 생략하면 일치하는 모든 위협이 반환됩니다. 세이프 브라우징이 제공할 수 있는 가장 완전한 보호 기능을 사용하려면 이 설정을 생략하는 것이 좋습니다.

필터는 https://github.com/google/cel-spec에서 일반적인 예와 함께 Google Common Expression Language를 사용하여 지정됩니다. 다음은 여기서 사용할 수 있는 몇 가지 구체적인 예입니다.

"threatType == ThreatType.SOCIAL_ENGINEERING" 필터를 사용하려면 FullHashDetail 내에 위협 유형이 SOCIAL_ENGINEERING여야 합니다. 식별자 "threatType"는 현재 위협 유형을 나타냅니다. 식별자 "ThreatType"는 가능한 모든 위협 유형의 모음을 나타냅니다.

"threatType in [ ThreatType.UNWANTED_SOFTWARE, ThreatType.MALWARE ]" 필터를 사용하려면 위협 유형이 UNWANTED_SOFTWARE 또는 MALWARE여야 합니다.

요청 본문

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

응답 본문

위협 해시 검색 후 반환된 응답

아무것도 발견되지 않은 경우 서버는 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)

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

fullHashes 필드가 비어 있는 경우에만 클라이언트는 cacheDuration를 늘려 서버에서 지정한 만료 시간 이후 새 만료를 결정할 수 있습니다(MAY). 어떤 경우든 증가된 캐시 기간이 24시간을 초과하면 안 됩니다.

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

소수점 아래가 최대 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 메시지를 수신할 준비가 되어 있어야 합니다(MUST). 따라서 모든 ThreatType 및 ThreatAttribute 열거형 값의 유효성을 확인하는 것은 클라이언트의 책임입니다. 값이 잘못된 것으로 간주되는 경우 클라이언트는 전체 FullHashDetail 메시지를 무시해야 합니다(MUST).

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

enum (ThreatType)

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

enum (ThreatAttribute)

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

ThreatAttribute

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

열거형
THREAT_ATTRIBUTE_UNSPECIFIED 알 수 없는 속성입니다. 서버에서 이를 반환하면 클라이언트는 둘러싸고 있는 FullHashDetail를 모두 무시합니다.
CANARY 위협 유형을 시행에 사용해서는 안 된다는 것을 나타냅니다.
FRAME_ONLY 위협 유형이 프레임에 적용하는 용도로만 사용되어야 함을 나타냅니다.