타게팅 문법
국가, 도시, ASN, 세션은 모두 프록시 사용자명에 파라미터로 적습니다. 이 문서에서 전체 문법을 설명합니다.
게이트웨이는 타게팅을 프록시 사용자명에서 읽습니다. 그래서 엔드포인트와 비밀번호는 하나로 두고 모든 네트워크와 도시를 쓸 수 있습니다. 파라미터는 프록시 유저 이름 뒤에 key-value 쌍으로 붙입니다. 순서는 상관없습니다. 키와 country·city 값은 대소문자를 구분하지 않지만, 세션 ID는 대소문자를 구분합니다. 알 수 없는 키는 무시하지 않고 407로 거부합니다.
현재 모든 IP는 대한민국에 있습니다. 게이트웨이가 받는 국가 값은 country-kr 하나이고, city와 asn으로 그 안에서 범위를 좁힙니다.
[res-|isp-|dc-]HANDLE-NAME[-parameter-value]...
res-|isp-|dc- 선택 접두어: 네트워크 지정
HANDLE 계정 식별자(영문 소문자·숫자 6자), 대시보드와
GET /api/v1/account 응답에서 확인
NAME 프록시 유저 이름
parameter 아래 표에 있는 키 중 하나, 대소문자 무관
value 영문자·숫자, 공백·문장부호 없음,
대소문자 무관(세션 ID만 구분)파라미터
| 파라미터 | 값 | 예시 | 설명 |
|---|---|---|---|
| country-XX | ISO 3166-1 alpha-2 코드 | country-kr | 모든 네트워크에서 쓸 수 있습니다. 네트워크의 IP가 전부 대한민국에 있으므로 지금 받는 코드는 kr 하나뿐이고, 다른 코드는 407로 거부됩니다. 생략해도 출구 IP는 한국이지만, 나중에 국가가 추가되어도 사용자명의 의미가 그대로 유지되도록 넣어 두는 것을 권합니다. |
| city-name | seoul, gyeonggi, busan, incheon, daegu, daejeon, gwangju, ulsan 중 하나(대소문자 무관) | city-seoul | country와 함께 써야 합니다. 업스트림 풀에 등록된 도시 태그와 대조하거나, 도시 타게팅을 지원하는 공급사에는 그대로 전달합니다. 맞는 업스트림이 없으면 502가 돌아옵니다. 대시보드에서 지정할 수 있는 도시를 모두 확인할 수 있습니다. |
| asn-NNNN | 자율 시스템 번호, 1~4294967295 | asn-64496 | 주거용 네트워크에서만 쓸 수 있으며, isp-·dc- 접두어와 함께 쓰거나 다른 네트워크의 프록시 유저로 보내면 407로 거부됩니다. 출구 IP를 특정 한국 ISP 망으로 고정합니다. 받은 IP의 ASN은 ipinfo.io 응답의 org 필드에서 확인할 수 있습니다. |
| session-ID | 영문자·숫자 최대 64자, 대소문자 구분 | session-a1b2 | 같은 ID를 쓰는 요청에 같은 IP를 유지합니다. 세션 문서를 참고하세요. |
| sessduration-MIN | 분 단위, 1~30 | sessduration-10 | 세션이 IP를 유지하는 시간입니다. session과 함께 쓸 때만 의미가 있고, 생략하면 프록시 유저의 기본값이 적용됩니다. |
| res- / isp- / dc- | 네트워크 접두어 | dc-k7f3q2-acme | 사용자명 맨 앞, 계정 식별자 앞에 붙여 프록시 유저를 만들 때 정한 네트워크 대신 다른 네트워크로 보냅니다. res- 트래픽은 주거용 잔액에서 차감되고, isp-·dc-는 해당 네트워크의 구독이 유효해야 하며 계정에 할당된 IP로만 나갑니다. |
알아 둘 규칙
- 파라미터는 후보 IP를 좁히는 조건입니다.
country-kr만 쓰면 네트워크의 모든 IP가 후보이지만,city와asn을 함께 쓰면 몇 개만 남을 수도 있습니다. 조건에 맞는 IP가 없으면 게이트웨이는 임의로 범위를 넓히지 않고 502를 돌려줍니다. city는country와 함께 써야 합니다. 지금은country-kr하나뿐이지만, 국가가 추가된 뒤에도 사용자명이 한 곳을 가리키도록 하기 위한 규칙입니다.- 도시와 ASN은 업스트림 풀에 등록된 태그와 대조하거나, 직접 타게팅을 지원하는 공급사에 그대로 전달합니다. 자체 지오로케이션 데이터베이스를 쓰는 사이트는 출구 IP를 이웃 도시로 판단할 수도 있습니다.
- 접두어와 파라미터를 포함한 사용자명 전체를 연결마다 보내야 합니다. 게이트웨이는 세션 외에는 연결 사이에 상태를 남기지 않습니다.
- 하이픈 사이의 각 부분은 비어 있으면 안 됩니다. 하이픈이 맨 앞이나 맨 끝에 오거나 두 번 연달아 오면 407로 거부됩니다.
- 407 응답이 어느 파라미터가 잘못됐는지까지 알려 주는 것은 요청이 인증을 통과한 뒤, 즉 비밀번호가 맞거나 프록시 유저의 화이트리스트 주소에서 보낸 경우뿐입니다. 그 전에는 사용자명에 어떤 문제가 있든
invalid credentials로만 응답하므로, 외부에서 사용자명을 떠볼 수 없습니다.
예시
아래는 모두 그대로 실행할 수 있는 요청입니다. 계정 식별자(k7f3q2)는 본인 것으로, acme는 사용 중인 프록시 유저로, PASSWORD는 그 비밀번호로 바꾸세요.
한국 IP, 연결마다 새로 선택
curl -x icn-01.gw.scalardata.ai:7777 -U "k7f3q2-acme-country-kr:PASSWORD" https://ipinfo.io/json서울만
curl -x icn-01.gw.scalardata.ai:7777 -U "k7f3q2-acme-country-kr-city-seoul:PASSWORD" https://ipinfo.io/json부산, IP 하나를 최대 30분 유지
curl -x icn-01.gw.scalardata.ai:7777 -U "k7f3q2-acme-country-kr-city-busan-session-b9x4m-sessduration-30:PASSWORD" https://ipinfo.io/json5분이 지나기 전에 같은 ID로 다시 연결하세요. 5분 동안 연결이 없는 세션은 일찍 해제됩니다.
ASN으로 ISP 하나 지정
curl -x icn-01.gw.scalardata.ai:7777 -U "k7f3q2-acme-country-kr-asn-64496:PASSWORD" https://ipinfo.io/json프록시 유저 기본값 대신 데이터센터 네트워크 사용
curl -x icn-01.gw.scalardata.ai:7777 -U "dc-k7f3q2-acme-country-kr:PASSWORD" https://ipinfo.io/json데이터센터 구독이 유효해야 하며, 트래픽은 계정에 할당된 IP로 나갑니다.