1. 本文介绍的韩国原生IP查询网站支持单次查询、批量CSV上传与REST API接入;提供同步与异步批量任务、结果导出(CSV/JSON)、和Webhook回调。
2. 适用场景:批量日志回溯、登录地址审计、区域屏蔽与流量归因。
2. 打开官网(示例:https://korea-ip.example),点击“注册”,填写邮箱+密码并验证邮箱;
3. 登录后进入“控制台→API密钥”,完成身份认证(企业需上传营业执照),选择试用或付费计划并开通。
3. 控制台→IP查询,输入单个IP或域名,选择查询字段(国家/城市/ISP/ASN/Geo坐标),点击“查询”。
4. 结果支持复制与导出JSON,若需要批量请用下一节说明。
4. 准备CSV:第一列必须为ip,示例:ip\n1.2.3.4\n5.6.7.8;
5. 控制台→批量查询→选择CSV上传,支持最大100,000行(示例站可能为10k-100k),单文件大小上限通常为50MB。上传后点击“提交”,系统返回job_id并显示进度条,完成后可下载结果CSV或JSON。
5. 在控制台生成API Key(建议使用两个Key:一个用于开发,一个用于生产),记录Secret并严格保管;
6. 可在密钥设置中白名单允许调用IP、设置权限(只读/写/批量),并设置速率上限。
6. 常用端点:单次查询POST https://api.korea-ip.example/v1/lookup,头部Authorization: Bearer {API_KEY},Body JSON {"ip":"1.2.3.4"};
7. 批量异步POST https://api.korea-ip.example/v1/batch,Body JSON {"ips":["1.2.3.4","5.6.7.8"]},返回{ "job_id":"abc123" },可GET /v1/batch/{job_id}/status或设置webhook回调。
7. Python示例(requests):
<code>import requests; headers={'Authorization':'Bearer YOUR_KEY'}; r=requests.post('https://api.korea-ip.example/v1/lookup',json={'ip':'1.2.3.4'},headers=headers); print(r.json())</code>。
8. Node.js示例(fetch):
<code>fetch(url,{method:'POST',headers:{'Authorization':'Bearer KEY','Content-Type':'application/json'},body:JSON.stringify({ips:['1.2.3.4']})})</code>。
8. 提交批量任务后记录job_id:poll方式:轮询GET /v1/batch/{job_id}/status直到status=completed,或在提交时填写callback_url,系统在任务完成后POST结果到该URL(含HMAC签名验签)。
9. 建议实现验签逻辑并存储job_id以便追踪。
9. 常见HTTP状态:400(参数错误),401(鉴权失败),429(限流),500(服务器错误)。
10. 建议:对429和5xx使用指数退避(初始1s,2s,4s),并实现本地缓存查询结果避免重复请求。
10. 存储用户IP需遵守当地法规(GDPR/韩国个人信息保护法),仅保留必要字段并设定删除策略。
11. 对接第三方时签署数据处理协议(DPA),对敏感字段加密存储。
11. 问:一次API批量能提交多少IP?
回答:通常API单次同步批量限制在1000条以内,异步批量可支持到5000-100000条(视服务等级),具体以控制台配额为准;超大任务建议拆分或使用异步job并开启Webhook回调。
12. 问:如果返回401该如何排查?
回答:检查API Key是否拼写错误、是否被删除或未激活,确认请求头Authorization格式为Bearer {KEY};如果启用IP白名单,确认调用服务器IP已加入白名单并检查时钟同步(签名类鉴权要求)。
13. 问:有什么最佳实践推荐用于生产环境?
回答:建议使用缓存层(按IP或CIDR缓存24-168小时)、限制并发请求、实现退避策略、监控失败率并报警、以及定期轮询更新IP库以降低实时查询压力。