대량 IP 조회 API: 속도 제한 아키텍처
대량 IP 조회 API를 사용하면 주소마다 호출하는 대신 한 번의 요청으로 많은 주소를 조회할 수 있으며, 그 주변 아키텍처는 세 가지 제약으로 귀결됩니다. 최대 배치 크기, 사용할 수 있는 요청 예산, 같은 질문을 두 번 하지 않도록 얼마나 잘 피하느냐입니다. 이 글은 ipto의 대량 조회 엔드포인트의 구체적인 수치를 사용해 실용적인 설계를 단계별로 설명합니다.
대량 IP 조회 엔드포인트가 받는 입력
ipto의 대량 조회는 POST 방식으로 /v1/ip/bulk에 IP 문자열의 JSON 배열을 보내는 요청입니다. 요청 하나에 최대 100개의 주소를 담을 수 있고, 처리 전에 중복이 제거되며, 응답은 IP 주소를 키로 하는 객체입니다. 각 항목은 국가, 도시, ASN, 조직과 is_vpn, is_tor, is_abuser, is_datacenter, bogon 필드를 포함하는 단일 조회 결과와 같은 형태입니다. 대량 조회는 유료 요금제 기능으로 Pro와 Enterprise에서 사용할 수 있고, Free 요금제는 가입 없이 하루 1,000건의 단일 조회를 제공합니다. 현재 요청 형식은 API 문서를 확인하세요.
중요한 과금 세부 사항은 대량 조회가 항목 단위로 과금된다는 점입니다. 주소 100개짜리 배치는 개별 조회 100건과 똑같이 일일 예산에서 100으로 계산됩니다. 따라서 배치로 묶는다고 해서 할당량이 늘어나지는 않습니다. 절약되는 것은 왕복 횟수, 연결 설정, 클라이언트 측 오케스트레이션이며, 로그 파일이나 고객 목록을 보강할 때 실제 병목은 이쪽인 경우가 많습니다.
예산에 맞춰 파이프라인 설계하기
모든 주소가 예산을 소모하므로 가장 저렴한 요청은 아예 보내지 않는 요청입니다. 먼저 필터링부터 시작하세요. 사설 및 예약 주소는 의미 있는 지오로케이션이 나올 수 없으므로, 비용이 발생하기 전에 로컬에서 제외하거나 보곤 IP 검사기로 분류할 수 있습니다. 남은 집합은 중복을 제거하세요. 프로덕션 로그는 소수의 반복 방문자, 크롤러, NAT 게이트웨이가 대부분을 차지하기 때문입니다. 배처 앞에 해시 집합을 두는 것이 대체로 가장 효과가 큰 개선입니다.
그다음 주소를 키로 하는 캐시를 추가하되, TTL은 관심 있는 데이터가 바뀌는 속도에 맞추세요. 국가와 ASN 매핑은 오랫동안 안정적이므로 며칠 정도가 적당합니다. 평판 플래그는 더 빨리 바뀝니다. ipto의 위협 피드는 6시간마다, IP 및 ASN 데이터셋은 매일 갱신되므로, 판정을 몇 시간보다 오래 캐시하면 절약되는 것은 별로 없이 오래된 데이터만 늘어납니다. 가능하면 필드별로 TTL을 따로 두거나, 전체 결과를 더 짧은 TTL로 캐시하세요.
- 보곤 주소와 명백히 잘못된 입력은 로컬에서 걸러냅니다.
- 작업 내에서, 그리고 캐시와 대조해 중복을 제거합니다.
- 남은 주소를 최대 100개씩 묶어 청크로 나눕니다.
- 청크는 한꺼번에 보내지 말고 제한된 동시성으로 보냅니다.
- 결과를 주소를 키로 캐시와 대상 저장소에 기록합니다.
동시성, 백오프, 일일 윈도우
일일 예산은 고정된 윈도우이므로, 설계 시 대비해야 할 실패 모드는 작업 도중에 예산이 소진되는 것입니다. 시작하기 전에 비용을 추정하세요. 고유한 비보곤 주소의 수가 작업이 소모할 요청 수입니다. 이것이 오늘 남은 예산을 초과하면 작업을 여러 윈도우에 나누거나, 가치가 가장 높은 주소를 먼저 처리하거나, 위험도가 가장 높은 주소에만 단일 조회로 대체하세요. 진행 상황을 저장해 두면 재시작된 작업이 처음부터가 아니라 마지막으로 완료된 청크부터 이어갈 수 있습니다.
동시성은 적당히 유지하세요. 각 청크가 이미 100건의 조회를 담고 있으므로 병렬 청크 몇 개면 거의 항상 충분하며, 제한 없는 팬아웃은 실패의 원인을 파악하기만 어렵게 만듭니다. 일시적 오류나 예산 초과 응답이 오면 지수 백오프와 지터로 재시도하고, 예산 소진은 빡빡한 루프에서 재시도할 일이 아니라 중단했다가 나중에 재개하라는 신호로 취급하세요. 모든 쓰기를 멱등하게 만들어 재시도된 청크가 행을 중복 삽입하지 않게 하세요.
대량 조회와 단일 조회 중 선택하기
회원가입 양식이나 결제처럼 실시간 경로에서는 이벤트마다 단일 조회를 사용하세요. 지연 시간이 낮고, 캐시가 반복을 흡수하며, 실제로 들어오는 주소에 대해서만 예산을 쓰게 됩니다. 대량 조회는 오프라인 작업용입니다. 테이블 백필, 하루치 로그 점수화, 허용 목록 감사 등이 해당합니다. 목표가 단순 보강이 아니라 위험 점수 산정이라면 사기 점수 검사기가 IP, 이메일, 전화번호, User-Agent 신호를 하나의 0~100점 점수로 결합하며, 이는 여러 개의 개별 호출을 대체할 수 있습니다. 제공업체별 무료 요금제 제한에 대한 더 긴 비교는 무료 요금제 속도 제한 비교를 참고하세요.
마지막으로, 자신의 사용량을 기록하세요. 작업당 소모한 요청 수, 캐시 적중률, 보곤 또는 중복으로 제외된 주소의 비율을 추적하세요. 이 세 가지 수치는 예산 경보가 울리기 훨씬 전에 아키텍처가 제대로 동작하는지 알려 줍니다.
대규모 배치를 스크립트로 만들기 전에 주소 몇 개를 직접 시험해 보세요. ASN 조회는 로그에서 계속 보이는 대역을 어느 네트워크가 소유하는지 보여 주며, 그러면 수천 건의 단일 조회 대신 하나의 결정으로 네트워크 전체를 처리할 수 있는 경우가 많습니다.