删除白名单IP
## 1 接口描述
本接口用于删除IP的白名单。接口请求地址https://proxy.qg.net/whitelist/del ；
**注：**该接口单个Key的请求频率限制为：20 次/分钟。
## 2 输入参数说明
以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见公共请求参数。
|参数名|是否必选|类型|描述|
|:---- |:---|:----- |----- |
|Key |是 |String |删除白名单的Key值|
|IP |是 |String|白名单IP，多个以逗号", "分隔|
## 3 返回值
|参数名|类型|描述|
|:---- |:----- |----- |
|Code |Integer |结果编码|
|Data |Array|删除成功的白名单数组|
|Num |Integer |删除成功的白名单个数|
## 4 示例
请求参数：
```
curl "https://proxy.qg.net/whitelist/del?Key=请改成您的Key&IP=1.1.1.1,2.2.2.2"
```
返回参数，JSON格式，详情如下：
```
{
"Code": 0,
"Data": [
"1.1.1.1",
"2.2.2.2"
],
"Num": 2
}
```
## 5 接口返回错误码
|错误码|描述|
|:---- |:----- |
| -1 | 未知错误 |
| -10 | 参数不合法 |
| -11 | 请求过于频繁 |
| -100 | 计划不存在或已过期 |
重拨独占资源
## 1 接口描述
接口地址： https://proxy.qg.net/monopolies/ips ；
本接口是用于请求重拨独占资源；
请求频率限制：按时业务是（通道数*5＋10）次/分钟；
方法：PUT；
编码：参数和返回内容均采用utf-8编码。
## 2 输入参数说明
| 参数名 | 是否必选 | 类型 | 描述 |
| :----- | :------- | :----- | :----------------------------: |
| Key | 是 | String | 重拨独占资源的Key值； |
| UUIDs | 是 | String | 独占资源编号，多个用","隔开 |
## 3 返回值
接口可返回文本格式、json格式、xml格式，字段说明如下：
| 返回字段 | 类型 | 描述 |
| :------- | :----- | :--------------------------: |
| data | Array | 重拨成功的独占资源编号数组 |
| error | String | 错误信息 |
## 4 示例
请求接口示例：
```
curl -X PUT -d "Key=请改成您的Key&UUIDs=XXX,XXX" "https://proxy.qg.net/monopolies/ips"
```
返回示例：
```
{
"data": ["fj_qzdx1-2:ppp1"] //重拨成功的资源uuids
}
```
## 5 接口返回错误码
| 错误码 | 描述 |
| :----: | :------------------------------: |
| 200 | 重拨成功 |
| 400 | 重拨时间间隔限制或资源还在分配中 |
释放独占资源
##1 接口描述
接口地址： https://proxy.qg.net/monopolies
本接口是用于释放申请到的独占IP，以便于再次进行独占IP申请。
请求限制：独占资源在申请后12小时才可释放，如果资源故障，可提交工单我们会强制释放；
方法：DELETE；
编码：参数和返回内容均采用utf-8编码。
## 2 输入参数说明
| 参数名 | 是否必选 | 类型 | 描述 |
| :----- | :------- | :----- | :----------------------------: |
| Key | 是 | String | 释放独占资源的Key值； |
| UUIDs | 是 | String | 独占资源编号，多个用","隔开。 |
## 3 返回值
接口可返回文本格式、json格式、xml格式，字段说明如下：
| 返回字段 | 类型 | 描述 |
| :------- | :----- | :--------------------------: |
| data | Array | 释放成功的独占资源编号数组； |
| error | String | 错误信息 |
## 4 示例
请求接口示例：
```
curl -X DELETE "https://proxy.qg.net/monopolies?Key=请改成您的Key&UUIDs=XX,XXXX"
```
返回示例：
```
{
"data": ["fj_xmdx2-1:ppp10"] //删除成功的资源
}
```
## 5 接口返回错误码
| 错误码 | 描述 |
| :----: | :------------------------------: |
| 200 | 删除成功 |
| 400 | 释放时间限制，申请后12小时可释放 |
静态独享代理接口相关
## 1说明
通过编码使用静态独享代理主要有以下三步骤：
（1）先在[会员中心](https://www.qg.net/user/ "会员中心")上查看购买的静态独享代理，进行本地调试和验证；[查看测试步骤＞＞](https://www.qg.net/doc/1574.html "查看测试步骤＞＞")
（2）参考[代码样例](https://www.qg.net/list/192.html)请求静态独享代理；
（3）在程序中通过调用API接口获取代理，然后请求目标网站。
## 2 API接口
静态独享代理API接口一览
| 接口类型 | API | 描述 |
| ------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| 资源相关 | - [allocate](https://www.qg.net/doc/174.html "资源申请")
- [query](https://www.qg.net/doc/1504.html "获取IP资源池")
- [release](https://www.qg.net/doc/176.html "释放资源")
| - 调用 allocate申请代理IP资源
- 调用query查询IP资源池全部可用的IP信息
- 调用release释放申请到的IP，以便于再次进行IP申请。 |
| 白名单相关 | - [whitelist/query](https://www.qg.net/doc/180.html "whitelist/query")
- [whitelist/add](https://www.qg.net/doc/178.html "whitelist/add")
- [whitelist/del](https://www.qg.net/doc/179.html "删除白名单")
| - 调用 whitelist/query用于查询IP的白名单
- 调用whitelist/add用于添加IP的白名单
- 调用whitelist/del用于删除IP的白名单 |
| 资源信息查询 | - [info/quota](https://www.qg.net/doc/181.html "info/quota")
- [resources](https://www.qg.net/doc/177.html "查询区域资源") | - 调用 info/quota查询IP提取余量
- 调用extract查询平台可用的代理IP资源列表 |
查询空闲独占资源
## 1 接口描述
接口地址： https://proxy.qg.net/monopolies/idle
本接口是用于查询空闲可申请的独占资源。
请求频率限制：60次/分钟；
方法：GET；
编码：参数和返回内容均采用utf-8编码。
## 2 输入参数说明
| 参数名 | 是否必选 | 类型 | 描述 |
| :----- | :------- | :----- | :-------------------: |
| Key | 是 | String | 查询独占资源的Key值 |
## 3 返回值
接口可返回文本格式、json格式、xml格式，字段说明如下：
| 返回字段 | 类型 | 描述 |
| :------- | :----- | :------------: |
| data | Array | 独占资源列表 |
| error | String | 错误信息 |
## 4 示例
请求接口示例：
```
curl "https://proxy.qg.net/monopolize_resources/idle?Key=请改成您的Key"
```
返回示例：
```
{
"data": [{
"area": "福建省泉州市",
"area_code": 350500,
"operator": "电信",
"operator_code": 1,
"idle": 30
},{
...
}]
}
```
## 5 接口返回错误码
| 错误码 | 描述 |
| :----: | :------: |
| 200 | 查询成功 |
| 500 | 未知错误 |
动态独占代理接口相关
## 1 说明
通过编码使用动态独占代理主要有以下三步骤：
（1）先在[会员中心](https://www.qg.net/user/ "会员中心")上查看购买的动态独占代理，在“IP管理”中添加IP城市，获取的独占资源进行本地调试和验证；[查看测试步骤＞＞](https://www.qg.net/doc/1574.html "查看测试步骤")
（2）参考[代码样例](https://www.qg.net/list/192.html)请求动态独占代理；
（3）在程序中通过调用API接口获取独占代理，然后请求目标网站。
## 2 API接口
动态独占代理API接口一览
| 接口类型 | API | 描述 |
| ------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| 资源相关 | - [monopolize_resources](https://www.qg.net/doc/1559.html )
- [monopolize_resources](https://www.qg.net/doc/1560.html)
- [monopolize_resources](https://www.qg.net/doc/1562.html)
- [monopolize_resources/newest_ips](https://www.qg.net/doc/1561.html )
| - 用POST调用接口申请独占资源
-用GET调用接口查询可用的独占资源
- 用DELETE调用接口释放独占资源
- 用PUT调用接口请求重拨独占资源 |
| 白名单相关 | - [whitelist/query](https://www.qg.net/doc/180.html "whitelist/query")
- [whitelist/add](https://www.qg.net/doc/178.html "whitelist/add")
- [whitelist/del](https://www.qg.net/doc/179.html "whitelist/del") | - 调用接口用于查询IP的白名单
- 调用接口用于添加IP的白名单
- 调用接口用于删除IP的白名单 |
| 资源信息查询 | - [monopolize_resources/idle](https://www.qg.net/doc/1563.html) | - 用GET调用接口查询空闲的独占资源 |
**重点：**动态独占代理相对动态独享代理，除了可以独享宽带和IP，还可以指定城市，重拨的IP保持地区不变。
申请独占资源
## 1 接口描述
接口地址： https://proxy.qg.net/monopolies
本接口是用于请求申请独占代理IP资源。
方法：POST；
编码：参数和返回内容均采用utf-8编码。
## 2 输入参数说明
| 参数名 | 是否必选 | 类型 | 描述 |
| :------- | :------- | :------ | :-------------------: |
| Key | 是 | String | 申请独占资源的Key值 |
| AreaCode | 否 | Integer | 地区编码，默认随机 |
| Operator | 否 | Integer | 运营商，默认随机 |
| Num | 否 | Integer | 数量，默认为1 |
## 3 返回值
接口可返回文本格式、json格式、xml格式，字段说明如下：
| 返回字段 | 类型 | 描述 |
| :------- | :----- | :------------: |
| data | Array | 独占资源列表 |
| error | String | 错误信息 |
## 4 示例
请求接口示例：
```
curl -X POST -d 'Key=请改成您的Key&AreaCode=XX&Operator=XXX&Num=1' 'https://proxy.qg.net/monopolies'
```
返回示例：
```
{
"data": [{
"uuid": "fj_qzdx9-1:ppp10",
"area": “福建省泉州市”,
"operator": "电信",
"state": "排队(123)", //分成在线、离线、重拨中、排队中(等待秒数X)
"monopolize_time": "2022-02-17 14:01:05", //独占时间
},{
...
}]
}
```
## 5 接口返回错误码
| 错误码 | 描述 |
| :----: | :------------: |
| 201 | 创建成功 |
| 400 | 独占资源不足 |
| 400 | 通道数不足 |
| 500 | 下放白名单失败 |
动态独享代理接口相关
## 1 说明
通过编码使用动态独享代理主要有以下三步骤：
1.先在[会员中心](https://www.qg.net/user/ "会员中心")上查看购买的动态独享代理，进行本地调试和验证；[查看测试步骤＞＞](https://www.qg.net/doc/1574.html "查看测试步骤")
2.参考[代码样例](https://www.qg.net/list/192.html)请求动态独享代理；
3.在程序中通过调用API接口获取代理，然后请求目标网站。
## 2 API接口
动态独享代理API接口一览
| 接口类型 | API | 描述 |
| ------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| 资源相关 | - [allocate](https://www.qg.net/doc/174.html "资源申请")
- [replace](https://www.qg.net/doc/297.html "更换IP资源")
- [release](https://www.qg.net/doc/176.html "释放资源")
- [query](https://www.qg.net/doc/175.html "资源查询")
| - 调用 allocate提取代理IP资源
- 调用replace用于释放并申请新的代理IP，更换IP资源
- 调用release释放申请到的IP，以便于再次进行IP申请
- 调用query查询用户可用的代理IP资源列表 |
| 白名单相关 | - [whitelist/query](https://www.qg.net/doc/180.html "whitelist/query")
- [whitelist/add](https://www.qg.net/doc/178.html "whitelist/add")
- [whitelist/del](https://www.qg.net/doc/179.html "whitelist/del") | - 调用 whitelist/query用于查询IP的白名单
- 调用whitelist/add用于添加IP的白名单
- 调用whitelist/del用于删除IP的白名单 |
| 资源信息查询 | - [info/quota](https://www.qg.net/doc/181.html "info/quota")
- [resources](https://www.qg.net/doc/177.html "查询区域资源") | - 调用 info/quota用于查询IP提取余量
- 调用resources查询平台可用的代理IP资源列表 |
**重点：**动态独享代理只提供给单个客户使用，独享带宽和IP资源，IP可自主释放申请，因此新增接口更换IP资源/replace、释放IP资源/release。
授权方式与调用限制
## 1 请求结构
服务地址：目前支持的域名列表为:
|接口域名|域名|
|:---- |:---|
|请求域名 |proxy.qg.net|
## 2 公共参数
公共参数是用于标识用户和接口的参数，如非必要，在每个接口单独的接口文档中不再对这些参数进行说明，但每次请求均需要携带这些参数，才能正常发起请求。
|参数名|是否必选|类型|描述|
|:---- |:---|:----- |----- |
|Method |是 |String|具体操作的指令接口名称，例如想要调用查询代理IP列表接口，则Method参数即为query。
|Key |是 |String |在 https://www.qg.net 上购买代理IP后得到的标识身份的密钥Key。
|Num |否 |Integer|数量
|KeepAlive |否 |Integer|生存周期(单位分钟) |
|AreaId |否 | Integer|区域编号(参考区域编号数据表) |
|detail |否 |Integer|是否查看详情(可查看到具体的省市县信息) |
|IP |否 | String| 节点IP，多个用"，"分割；全部以"* "表示
|Isp |否 | String| 运营商，默认随机，1:电信；2:移动；3:联通；4:BGP
|TaskID |否 |String|任务ID，多个用"，"分割；全部以"* "表示
假设用户想要查询已申请的代理IP列表(其中Method为query)，则其请求链接的形式可能如下:
https://proxy.qg.net/query?Key=密钥
## 3 接口请求频率
接口频率限制时间均为一分钟内，从触发某个接口的时间开始计时的一分钟。具体详情如下：
| 接口类型 | 频率限制 |
| :------------ | :------------ |
| /allocate 提取IP资源 | 按时：通道数*5+10，按量：60 |
| /replace 更换IP资源 | 按时：通道数*5+10 |
| /extract 获取IP资源池 | 动态共享按时：45 |
| /release 释放IP资源 | 动态独享按时：通道数*5 |
| /query 查询IP资源 | 按时：通道数*5+10 |
| /whitelist/add 添加白名单 | 20 |
| /whitelist/del 删除白名单 | 20 |
| /whitelist/query 查询白名单 | 60 |
| /info/quota 通道配额| 60 |
| /resources 区域查询 | 60 |
## 4 释放次数限制
| 套餐类型 | 释放次数限制说明 |
| ------------ | ------------ |
| 动态独享 | 每分钟的释放限制次数为通道数*2 |
| 动态共享 | 不能自主释放，套餐时长到期后自动释放 |
| 静态独享 | 超过一天后能释放，一周不超过2次 |
| 动态独占 | 添加的资源要12小时后才能更换 |
## 5 通信协议
青果云代理IP-API的所有接口均支持HTTP、HTTPS进行通信，提供高安全性的通信通道。
## 6 请求方法
同时支持 POST 和 GET 请求，需要注意不能混合使用。即如果使用 GET 方式，则参数均从 Querystring 取得；如果使用 POST 方式，则参数均从 Request Body 中取得，Querystring 中的参数将忽略。两种方式参数格式规则相同，一般使用GET，当参数字符串过长时使用POST，请见各接口详细描述。
## 7 字符编码
均使用UTF-8编码。
根据key查询当前独占列表
## 1 接口描述
接口地址： https://proxy.qg.net/monopolies
本接口是根据key查询用户已占用到且可用的独占资源列表。
请求频率限制：60次/分钟；
方法：GET；
编码：参数和返回内容均采用utf-8编码。
## 2 输入参数说明
| 参数名 | 是否必选 | 类型 | 描述 |
| :----- | :------- | :----- | :----------------------------: |
| Key | 是 | String | 查询独占资源的Key值； |
| UUIDs | 否 | String | 独占资源编号，多个用逗号隔开。 |
## 3 返回值
接口可返回文本格式、json格式、xml格式，字段说明如下：
| 返回字段 | 类型 | 描述 |
| :------- | :----- | :----------: |
| data | Array | 独占资源列表 |
| error | String | 错误信息 |
## 4 示例
请求接口示例：
```
curl "https://proxy.qg.net/monopolies?Key=请改成您的Key&UUIDs=XXX,XXX"
```
返回示例：
```
{
"data": [{
"uuid": "fj_qzdx9-1:ppp10",
"area": "福建省泉州市",
"isp": "电信",
"state": "在线", //分成在线、离线、重拨中、排队中(等待秒数X)
"monopolize_time": "2022-02-17 14:01:05", //独占时间
"last_dial_time": "2022-02-17 14:01:05", //最近一次拨号时间
"ip": "127.0.0.1:10800", //当前IP，状态为在线时才有此数据
"heartbeat": "2022-02-17 14:01:05", //最后一次心跳，状态为在线时才有此数据
},{
...
}]
}
```
## 5 接口返回错误码
| 错误码 | 描述 |
| :----: | :------: |
| 200 | 查询成功 |
| 500 | 未知错误 |
