短效代理-按量提取-提取IP接口
## 1. 接口描述
接口请求域名： share.proxy.qg.net。
本接口 (/get) 用于短效代理产品按量提取模式下提取IP的接口。
默认接口请求频率限制：60次/分钟。
推荐使用调试工具进行调试，[调试工具](https://www.qg.net/tools/IPdebug.html)。
## 2. 输入参数
| 参数名称 | 必选 | 类型 | 描述 |
| -------- | ---- | ------- | ------------------------------------------------------------ |
| key | 是 | String | 公共参数，产品唯一标识。 |
| area | 否 | String | 按地区提取。支持多地区筛选，逗号隔开。比如："350500,330700"。 |
| area_ex | 否 | String | 排除某些地区提取。支持多地区排除，用逗号隔开。比如："440100,450000"。 |
| isp | 否 | Integer | 按运营商提取。
0: 不筛选
1: 电信
2: 移动
3: 联通 |
| num | 否 | Integer | 提取个数，默认为1 |
| distinct | 否 | Bool | 去重提取，默认为false。如果为true则不会提取到已经在使用的IP资源。 |
## 3. 输出参数
| 参数名称 | 类型 | 描述 |
| ---------- | --------------------------------- | ------------------------------------------------------------ |
| code | String | 请求状态码。 |
| data | Array of [IP](https://www.qg.net) | IP资源列表。
**注：IP结构中的server才是代理地址，proxy_ip是代理的真实出口IP。** |
| request_id | String | 唯一请求ID，每次请求都会返回。定位问题时需要提供该次请求的 request_id。 |
## 4. 示例
#### 输入示例
```
GET https://share.proxy.qg.net/get?key=<您的key信息>&<其他输入参数>
```
#### 输出示例
```json
{
"code": "SUCCESS",
"data": [
{
"proxy_ip": "123.54.55.24",
"server": "123.54.55.24:59419",
"area": "河南省商丘市",
"isp": "电信",
"deadline": "2023-02-25 15:38:36"
}
],
"request_id": "83158ebe-be6c-40f7-a158-688741083edc"
}
```
## 5. 错误码
| 错误码 | 描述 |
| ---------------------- | -------------------------------------------------------- |
| INTERNAL_ERROR | 系统内部异常。 |
| INVALID_PARAMETER | 参数错误（包含参数格式、类型等错误）。 |
| INVALID_KEY | Key不存在或已过期。 |
| UNAVAILABLE_KEY | Key不可用，已过期或被封禁 |
| ACCESS_DENY | Key没有此接口的权限。 |
| API_AUTH_DENY | Api授权不通过，请检查[Api鉴权配置](https://www.qg.net/user/proxyIpManage)。 |
| KEY_BLOCK | Key被封禁。 |
| REQUEST_LIMIT_EXCEEDED | 请求频率超出限制。 |
| BALANCE_INSUFFICIENT | Key余额不足。 |
| NO_RESOURCE_FOUND | 资源不足。 |
| FAILED_OPERATION | 提取失败。 |
| EXTRACT_LIMIT_EXCEEDED | 超出提取配额。 |
短效代理（全球HTTP）-按量提取-提取IP资源接口
## 1. 接口描述
接口请求域名： overseas.proxy.qg.net。
本接口 (/get) 用于全球HTTP-短效代理产品 按量提取模式下提取IP的接口。
默认接口请求频率限制：60次/分钟。
推荐使用调试工具进行调试，[调试工具](https://www.qg.net/tools/IPdebug.html?type=5-2)。
需注意，如使用白名单IP，请在提取前添加白名单。
## 2. 输入参数
| 参数名称 | 必选 | 类型 | 描述 |
| -------- | ---- | ------- | ------------------------------------------------------------ |
| key | 是 | String | 公共参数，产品唯一标识。 |
| area | 否 | String | 国家筛选。支持国家编码和自定义编码，比如：US,EU，或者990100,990200。[国家编码](https://www.qg.net/doc/use/8_234_201/1975.html) |
| area_ex | 否 | String | 排除某些地区提取。使用方式同上 |
| num | 否 | Integer | 提取个数，默认为1 |
## 3. 输出参数
| 参数名称 | 类型 | 描述 |
| ---------- | ----------------------------------------------- | ------------------------------------------------------------ |
| code | String | 请求状态码。 |
| data | Array of [IP](https://www.qg.net/doc/1839.html) | IP资源列表。
**注：IP结构中的server才是代理地址，proxy_ip是代理的真实出口IP。** |
| request_id | String | 唯一请求ID，每次请求都会返回。定位问题时需要提供该次请求的 request_id。 |
## 4. 示例
#### 输入示例
```
GET https://overseas.proxy.qg.net/get?key=<您的key信息>&<其他输入参数>
```
#### 输出示例
```json
{
"code": "SUCCESS",
"data": [{
"proxy_ip": "129.150.42.240",
"server": "129.150.42.240:18080",
"area": "新加坡",
"deadline": "2023-02-25 15:38:36"
}],
"request_id": "83158ebe-be6c-40f7-a158-688741083edc"
}
```
## 5. 错误码
| 错误码 | 描述 |
| ---------------------- | ------------------------------------------------------------ |
| INTERNAL_ERROR | 系统内部异常。 |
| INVALID_PARAMETER | 参数错误（包含参数格式、类型等错误）。 |
| INVALID_KEY | Key不存在或已过期。 |
| UNAVAILABLE_KEY | Key不可用，已过期或被封禁 |
| ACCESS_DENY | Key没有此接口的权限。 |
| API_AUTH_DENY | Api授权不通过，请检查[Api鉴权配置](https://www.qg.net/user/proxyipResource)。 |
| KEY_BLOCK | Key被封禁。 |
| REQUEST_LIMIT_EXCEEDED | 请求频率超出限制。 |
| BALANCE_INSUFFICIENT | Key余额不足。 |
| NO_RESOURCE_FOUND | 资源不足。 |
| FAILED_OPERATION | 提取失败。 |
| EXTRACT_LIMIT_EXCEEDED | 超出提取配额。 |
短效代理-企业定制
## 一、介绍：
企业定制是青果全新推出的一种创新计费模式，基于峰值带宽进行收费。这种模式旨在为企业级用户提供更灵活的解决方案，以满足企业用户在日常运营中对大量IP资源的需求。
特别的，企业定制方案中，支持使用API提取时在1-5分钟内自定义IP存活时长。
**注：**IP的存活周期是从提取到IP的那一刻开始算起的，超过这个时长IP会自动失效释放。
**更多定制需求**，欢迎[**提交定制信息**](https://www.qg.net/product/customization.html)或与客服直接沟通哦。
## 二、计费方式：
企业定制套餐，带宽峰值的可选区间是100M-1000M。
IP存活时长为1-5分钟自定义选择，具体的产品套餐价格，请以购买页为准。
## 三、适用场景：
1. 每天都有大量IP使用需求，带宽峰值可控
2. 企业级特定需求
短效代理-隧道池
## 一、介绍
隧道池，是通过青果的独家隧道技术设计，将IP操作放到云端，实现了入口IP固定，出口IP**定时自动切换**的功能。用户使用隧道池代理IP产品，只需要authkey信息，即可进行代理连接和采集，省去了API代码接入和IP池管理两大块工作量。
并且，隧道池与中转池一样由大量的边缘节点汇聚而成，拥有资源IP段分散和高可用的优势。
目前隧道池仅支持按通道提取。
**示例**
购买了隧道池产品的用户，每个通道对应的入口ip将保持不变，接入使用后，出口ip将根据存活周期定时进行切换变更。
[提取和使用隧道池产品 ＞](https://www.qg.net/doc/product/6_255_254/2246.html)
## 二、资源池特点
相比与直连池/中转池，隧道池
- 云端自动切换IP，减少了提取的过程
- 减少IP池管理，IP存活时间管理的工作
**使用上的区别**
购买成功后，隧道池产品只需要进行首次提取，后续IP将在云端定时自动切换，
客户无需重新提取IP。而直连池/中转池产品时需要在IP失效后重新提取的。
只有在用户需要变更IP属性时，隧道池产品才需要重新提取IP哦。
## 三、适合客户群
- 追求调用简单，不想管理IP的客户
- 采集过程需要保持同一个IP的需求
短效代理各提取方式的区别
| |
**弹性提取** | **均匀提取** | **按量提取** | **通道提取 ** |
| ------------ | ------------------------------------------------ | -------------------------------------- | -------------------------------------------------------- | ---------------------------- |
| **定义**
| 按每天提取的IP数计费
| 按每分钟提取的IP数计费
| 按提取的IP数计费
| 按同时在线的IP数计费
|
| **资源池** | 直连+中转* | 直连+中转 | 直连+中转 | 直连池/中转池/隧道池 三选一 |
| **可选套餐范围** | 选择每天IP数 1000-200W个 | 选择每分钟IP数 5-2000个 | 选择IP包 1W-50W | 选择通道数 1-1000 |
| **IP存活时长** | 1分钟-30分钟 | 1分钟-30分钟 | 1分钟-30分钟 | 1分钟-30分钟 |
| **特点** | 自由度高，每天可任意选择时间段集中使用，不浪费IP | 每分钟有固定可提取量，开发比通道更平滑 | 自由度高，有效期内可自由安排使用IP，适合短时突发作为补充 | 同时在线的IP数明确，成本较低 |
| **适合用户场景** | 每天集中时间段使用IP，或不定时使用IP的客户 | 每小时都需要使用IP的客户 | 需短时间内集中大量使用IP的客户 | 每天业务不间断的客户 |
| | [了解详情＞](https://www.qg.net/doc/product/6_255_252/2250.html) | [了解详情＞](https://www.qg.net/doc/product/6_255_252/2252.html) | [了解详情＞](https://www.qg.net/doc/product/6_255_252/2251.html) | [了解详情＞](https://www.qg.net/doc/product/6_255_252/2253.html) |
*购买页中，仅通道提取保留多个资源池选项，其余提取方式将默认选中直连&中转的混合资源池。
##### 另外的，【企业定制】是青果特别推出针对企业客户的方案--基于峰值带宽进行收费，满足企业用户在日常运营中对大量IP资源的需求。
独享代理-释放IP资源接口
## 1. 接口描述
接口请求域名： exclusive.proxy.qg.net。
本接口 (/delete) 用于独享代理产品释放IP资源的接口。
默认接口请求频率限制：<通道数> * 2 / 分钟。
推荐使用调试工具进行调试，[调试工具](https://www.qg.net/tools/IPdebug.html)。
## 2. 输入参数
| 参数名称 | 必选 | 类型 | 描述 |
| -------- | ---- | ------ | ------------------------------------------------------------ |
| key | 是 | String | 公共参数，产品唯一标识。 |
| task | 否 | String | 按提取批次释放。支持批量释放，用逗号隔开。比如：Z5p2DKKCSyhocKEa,xsQGWfoaX99WcYnU。 |
| ip | 否 | String | 按IP释放。支持批量释放，用逗号隔开。比如：129.123.7.89,23.11.112.51。 |
**注意：
1、task和ip必选其一，如果两个参数都填写，以task为准。
2、如果需要释放全部IP，用task="\*"或者ip="\*"即可。
3、这里的释放参数ip为提取接口返回的proxy_ip值**
## 3. 输出参数
| 参数名称 | 类型 | 描述 |
| ---------- | ------ | ------------------------------------------------------------ |
| code | String | 请求状态码。 |
| request_id | String | 唯一请求ID，每次请求都会返回。定位问题时需要提供该次请求的 request_id。 |
## 4. 示例
#### 输入示例
```
GET https://exclusive.proxy.qg.net/delete?key=<您的key信息>&<其他输入参数>
```
#### 输出示例
```json
{
"code": "SUCCESS",
"request_id": "83158ebe-be6c-40f7-a158-688741083edc"
}
```
## 5. 错误码
| 错误码 | 描述 |
| ---------------------- | ------------------------------------------------------------ |
| INTERNAL_ERROR | 系统内部异常。 |
| INVALID_PARAMETER | 参数错误（包含参数格式、类型等错误）。 |
| INVALID_KEY | Key不存在或已过期。 |
| UNAVAILABLE_KEY | Key不可用，已过期或被封禁 |
| ACCESS_DENY | Key没有此接口的权限。 |
| API_AUTH_DENY | Api授权不通过，请检查[Api鉴权配置](https://www.qg.net/user/proxyIpManage)。 |
| KEY_BLOCK | Key被封禁。 |
| REQUEST_LIMIT_EXCEEDED | 请求频率超出限制。 |
| DELETE_LIMIT_EXCEEDED | 释放频率超出限制。 |
隧道代理 Python 语言接入指南
## 概述
本文档将指引你进行隧道代理的接入，在此文档中使用到的术语将会在下方进行列出。
| 术语 | 解释 |
| :------- | :----------------------------------------- |
| 隧道 | 自动更换代理 IP 的代理服务 |
| 固定时长 | 服务器将在固定时长后自动切换IP，例如1分钟 |
| 通道 | 使用多个通道同时发起请求，每个通道的IP不同 |
隧道代理有多种使用方式，具体行为取决于套餐及模式。
- 普通模式
每次请求都自动切换IP
- 普通模式指定地区
普通模式下，希望可以指定地区（仅适用于全球HTTP隧道代理），具体参考[海外区域编码](https://www.qg.net/doc/1975.html "海外区域编码")中的青果编码。
- 普通模式打标记
普通模式下，希望多个HTTP请求保证代理IP相同，可以给多个请求的代理协议打上相同的标记，并标记这个代理IP的存活时间（不主动设置存活时间则默认为10秒）
- 固定时长多通道模式
服务器定时切换IP，可同时使用多个通道发起请求，即可以同时使用多个IP
## 前置知识
在 Python 语言中，通常使用 requests 进行 http/s 代理的设定与请求的发送
### Proxy Url Scheme
由协议、用户名、密码、域名、端口几部分组成
例如 http 协议的代理 url
```
http://[user:password@]hostname:port
```
### pip
Python 的包管理工具，可以简单的进行依赖管理
## 使用 Python 接入
**以下内容假设读者具备基本的 Python 使用经验和对网络协议具有一定的了解。**
### 安装 requests
```shell
pip3 install requests
```
### 生成 url
普通模式
```python
proxyUrl = "http://%(user)s:%(password)s@%(server)s" % {
"user": authKey,
"password": password,
"server": proxyAddr,
}
```
普通模式指定地区（仅适用于全球HTTP隧道代理）
```python
proxyUrl = "http://%(user)s:%(password)s:A%(area)d@%(server)s" % {
"user": authKey,
"password": password,
"server": proxyAddr,
"area": area,
}
```
普通模式打标记
```python
proxyUrl = "http://%(user)s:%(password)s:%(channel)s:%(ttl)d@%(server)s" % {
"user": authKey,
"password": password,
"channel": "channel-1",
"ttl": 20,
"server": proxyAddr,
}
```
固定时长多通道模式（该模式仅适用于2024年5月17日前购买的隧道代理固定时长多通道产品）
```python
proxyUrl = "http://%(user)s:%(password)s:%(channel)s@%(server)s" % {
"user": authKey,
"password": password,
"channel": "channel-1",
"server": proxyAddr,
}
```
### 设置代理地址
http/s 均适用该地址
```
proxies = {
"http": proxyUrl,
"https": proxyUrl,
}
```
### 执行 HTTP/s 请求
以 https://api.ipify.org 为例
```python
resp = requests.get("https://ip.cn/api/index?ip=&type=0", proxies=proxies)
```
### 读取响应实体
resp.text 是字符串类型，可以直接打印
```python
print(resp.text)
```
## 示例代码
```python
import requests
proxyAddr = ""
authKey = ""
password = ""
proxyUrl = "http://%(user)s:%(password)s@%(server)s" % {
"user": authKey,
"password": password,
"server": proxyAddr,
}
proxies = {
"http": proxyUrl,
"https": proxyUrl,
}
resp = requests.get("https://api.ipify.org", proxies=proxies)
print(resp.text)
```
短效代理（全球HTTP）-通道提取-查询国家接口
## 1. 接口描述
接口请求域名： overseas.proxy.qg.net。
本接口 (/resources) 用于全球HTTP-短效代理产品通道提取模式下查询国家资源的接口。
默认接口请求频率限制：60次/分钟。
推荐使用调试工具进行调试，[调试工具](https://www.qg.net/tools/IPdebug.html?type=5-2)。
## 2. 输入参数
| 参数名称 | 必选 | 类型 | 描述 |
| -------- | ---- | ------ | ------------------------ |
| key | 是 | String | 公共参数，产品唯一标识。 |
## 3. 输出参数
| 参数名称 | 类型 | 描述 |
| ---------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| code | String | 请求状态码。 |
| data | Array of [ResourceAreaISP](https://www.qg.net/doc/1839.html) | [国家编码](https://www.qg.net/doc/use/8_234_201/1975.html) |
| request_id | String | 唯一请求ID，每次请求都会返回。定位问题时需要提供该次请求的 request_id。 |
## 4. 示例
#### 输入示例
```
GET https://overseas.proxy.qg.net/resources?key=<您的key信息>
```
#### 输出示例
```json
{
"code": "SUCCESS",
"data": [
{
"area": "美国",
"area_code": 990100,
"country": "US",
"available": true
}
],
"request_id": "51024a8b-a8a5-4e78-9301-cb500a8c083e"
}
```
## 5. 错误码
| 错误码 | 描述 |
| ---------------------- | ------------------------------------------------------------ |
| INTERNAL_ERROR | 系统内部异常。 |
| INVALID_PARAMETER | 参数错误（包含参数格式、类型等错误）。 |
| INVALID_KEY | Key不存在或已过期。 |
| UNAVAILABLE_KEY | Key不可用，已过期或被封禁 |
| ACCESS_DENY | Key没有此接口的权限。 |
| API_AUTH_DENY | Api授权不通过，请检查[Api鉴权配置](https://www.qg.net/user/proxyipResource)。 |
| KEY_BLOCK | Key被封禁。 |
| REQUEST_LIMIT_EXCEEDED | 请求频率超出限制。 |
短效代理（全球HTTP）-通道提取-查询通道数接口
## 1. 接口描述
接口请求域名： overseas.proxy.qg.net。
本接口 (/channels) 用于全球HTTP-短效代理产品通道提取模式下查询通道数的接口。
默认接口请求频率限制：60次/分钟。
推荐使用调试工具进行调试，[调试工具](https://www.qg.net/tools/IPdebug.html?type=2-2)。
## 2. 输入参数
| 参数名称 | 必选 | 类型 | 描述 |
| -------- | ---- | ------ | ------------------------ |
| key | 是 | String | 公共参数，产品唯一标识。 |
## 3. 输出参数
| 参数名称 | 类型 | 描述 |
| ---------- | ------- | ------------------------------------------------------------ |
| code | String | 请求状态码。 |
| data.toal | Integer | key的通道总数。 |
| data.idle | Integer | 空闲通道数。 |
| request_id | String | 唯一请求ID，每次请求都会返回。定位问题时需要提供该次请求的 request_id。 |
## 4. 示例
#### 输入示例
```
GET https://overseas.proxy.qg.net/channels?key=<您的key信息>
```
#### 输出示例
```json
{
"code": "SUCCESS",
"data": {
"total": 10,
"idle": 5
},
"request_id": "83158ebe-be6c-40f7-a158-688741083edc"
}
```
## 5. 错误码
| 错误码 | 描述 |
| ---------------------- | ------------------------------------------------------------ |
| INTERNAL_ERROR | 系统内部异常。 |
| INVALID_PARAMETER | 参数错误（包含参数格式、类型等错误）。 |
| INVALID_KEY | Key不存在或已过期。 |
| UNAVAILABLE_KEY | Key不可用，已过期或被封禁 |
| ACCESS_DENY | Key没有此接口的权限。 |
| API_AUTH_DENY | Api授权不通过，请检查[Api鉴权配置](https://www.qg.net/user/proxyIpManage)。 |
| KEY_BLOCK | Key被封禁。 |
| REQUEST_LIMIT_EXCEEDED | 请求频率超出限制。 |
短效代理（全球HTTP）-按量提取-查询国家接口
## 1. 接口描述
接口请求域名： overseas.proxy.qg.net。
本接口 (/resources) 用于全球HTTP-短效代理产品按量提取模式下查询国家资源的接口。
默认接口请求频率限制：60次/分钟。
推荐使用调试工具进行调试，[调试工具](https://www.qg.net/tools/IPdebug.html?type=5-2)。
## 2. 输入参数
| 参数名称 | 必选 | 类型 | 描述 |
| -------- | ---- | ------ | ------------------------ |
| key | 是 | String | 公共参数，产品唯一标识。 |
## 3. 输出参数
| 参数名称 | 类型 | 描述 |
| ---------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| code | String | 请求状态码。 |
| data | Array of [ResourceAreaISP](https://www.qg.net/doc/1839.html) | [国家编码](https://www.qg.net/doc/use/8_234_201/1975.html) |
| request_id | String | 唯一请求ID，每次请求都会返回。定位问题时需要提供该次请求的 request_id。 |
## 4. 示例
#### 输入示例
```
GET https://overseas.proxy.qg.net/resources?key=<您的key信息>
```
#### 输出示例
```json
{
"code": "SUCCESS",
"data": [
{
"area": "美国",
"area_code": 990100,
"country": "US",
"available": true
}
],
"request_id": "51024a8b-a8a5-4e78-9301-cb500a8c083e"
}
```
## 5. 错误码
| 错误码 | 描述 |
| ---------------------- | ------------------------------------------------------------ |
| INTERNAL_ERROR | 系统内部异常。 |
| INVALID_PARAMETER | 参数错误（包含参数格式、类型等错误）。 |
| INVALID_KEY | Key不存在或已过期。 |
| UNAVAILABLE_KEY | Key不可用，已过期或被封禁 |
| ACCESS_DENY | Key没有此接口的权限。 |
| API_AUTH_DENY | Api授权不通过，请检查[Api鉴权配置](https://www.qg.net/user/proxyipResource)。 |
| KEY_BLOCK | Key被封禁。 |
| REQUEST_LIMIT_EXCEEDED | 请求频率超出限制。 |
