动态独享代理接口相关
## 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 | 未知错误 |
查询可用通道数
## 1 接口描述
接口地址： https://proxy.qg.net/info/quota
本接口用于查询IP提取余量。
该接口单个Key的请求频率限制为：60次/分钟；
方法：HTTP、GET，需要注意不能混合使用；
编码：参数和返回内容均采用utf-8编码。
## 2 输入参数说明
|参数名|是否必选|类型|描述|
|:---- |:---|:----- |----- |
|Key |是 |String |查询的Key值 |
## 3 返回值
接口可返回文本格式、json格式、xml格式，字段说明如下：
|参数名|类型|描述|
|:---- |:----- |----- |
|Code |Integer |结果编码|
|Total |Integer |总数量|
|Available|Integer |可用数量|
|Used |Integer |已使用数量|
## 4 示例
请求接口示例：
```
curl "https://proxy.qg.net/info/quota?Key=请改成您的Key"
```
返回示例：
```
{
"Code": 0,
"Total": 5,
"Available": 3,
"Used": 2
}
```
## 5 接口返回错误码
| 错误码 | 描述 |
| ------------ | ------------ |
| -1 | 未知错误 |
| -10 | 参数不合法 |
| -11 | 请求过于频繁 |
| -12 | AuthKey被封禁 |
| -100 | 计划不存在或已过期 |
代理IP API概览
## 1 接口简介
青果代理IP提供了功能丰富的API接口，满足开发者在各种场景下的调用需求。
所有接口支持 HTTP 或者 HTTPS 请求，部分接口采用 GET 方法，部分接口采用 POST 方法；接口返回数据的格式支持文本、json、xml。
具体请参见接口文档。
## 2 API列表
- [动态共享代理](https://www.qg.net/doc/1564.html "动态共享代理")
- [动态独享代理](https://www.qg.net/doc/1565.html "动态独享代理")
- [动态独占代理](https://www.qg.net/doc/1570.html "动态独占代理")
- [隧道共享代理](https://www.qg.net/doc/1567.html "隧道共享代理")
- [静态独享代理](https://www.qg.net/doc/1568.html "静态独享代理")
## 3 测试代理可用性
### 3.1 生成API链接
对于代理提取API，您可以到提取工具在线生成API链接，内置到您的程序中：
[提取代理API链接生成 ＞](https://www.qg.net/tools/IPget.html "提取代理API链接生成 ＞＞")
其他接口请查看API文档，获取接口url和参数说明，自己生成API链接。
### 3.2 测试API链接
**浏览器测试**
您可以把生成的API链接直接在浏览器里打开，查看返回结果。例如，您直接点击如下api链接
https://proxy.qg.net/query?Key=0B***607
**命令行测试**
如果您在linux系统下，可以通过curl命令请求API链接查看结果：
`curl "https://proxy.qg.net/allocate?Key=请改成您的Key"`
## 4 接口返回错误码
公共接口返回错误码
| 错误码 | 描述 |
| ------ | ------------------------- |
| -1 | 未知错误 |
| -10 | 参数不合法 |
| -11 | 请求过于频繁 |
| -12 | Authkey被封禁 |
| -13 | 当前客户端IP不在授权名单中 |
| -14 | Pwd不合法 |
| -15 | Authkey对应的业务无此权限 |
| -100 | 计划不存在或已过期 |
| -103 | 资源不足 |
| -104 | 申请资源失败 |
| -105 | 释放的IP数超过允许释放的IP数 |
## 5 代码样例
查看API调用的[代码样例 ＞](https://www.qg.net/doc/172.html)
查询套餐购买询价
**简要描述：**
- 本接口用于查询套餐购买询价。接口请求地址
|参数名|必选|类型|说明|
|:---- |:---|:----- |----- |
|package_no|是|string|套餐编号|
|system_no|是|string|操作系统编号
|duration|是|string|购买时长。单位：
- s: 小时 例：2s（2小时）
- d: 天 例：1d（1天）
- w: 周 例：1w（1周）
- m: 月 例：1m（1个月）
取值范围：
- 腾讯云：1m,2m,3m,4m,5m,6m,7m,8m,9m,12m,24m,36m
- 阿里云：1m,2m,3m,4m,5m,6m,7m,8m,9m,12m,24m,36m
- 青果云：请参考查询可用区关联价格信息
- 华为云：1m,2m,3m,4m,5m,6m,7m,8m,9m,12m,24m,36m
- 前海云：1m,2m,3m,4m,5m,6m,7m,8m,9m,12m,24m,36m
- 电信云：1m,2m,3m,4m,5m,6m,7m,8m,9m,12m,24m,36m
- 云电脑：请参考查询可用区关联价格信息
- 其他（类别为固定云、拨号VPS）：请参考查询可用区关联规格信息|
**输入示例**
https://qg.net/api/cloud-business/packageOrderPrice&package_no=1&system_no=1&duration=1m
**返回示例**
JSON格式
```
{
"RequestId":'423369C7-AD6F-3GT6-NMJ7-E2RG5N6HG7D3',
"Code": 0,
"Message" : "返回内容"
"Data": {
"OriginalPrice": "60",
"TotalPrice": "50"
}
}
```
**返回参数说明**
|参数名|类型|说明|
|:----- |:-----|----- |
|RequestId |string |请求编号 |
|Code |integer |状态码 |
|Message |string |返回内容 |
|OriginalPrice |float |原价 |
|TotalPrice |float |应付价格 |
**错误码：**
|错误码|说明|
|:----- |:-----
|- |- |
**备注**
- 更多返回错误代码请看公共API栏目下的[公共错误代码][001]文档描述
[001]: https://www.qg.net/doc/251.html "公共错误代码"
获取账户余额
**简要描述：**
- 本接口用于查询账户余额。接口请求地址
**输入示例**
https://www.qg.net/api/merchant/getBalance
**返回示例**
JSON格式
```
{
"result":true,
"data":"1.00",
"msg":null
}
```
**返回参数说明**
|参数名|类型|说明|
|:----- |:-----|----- |
|result |bool |请求结果 |
|data |string |账户余额 |
|msg |string |错误信息 |
**备注**
- 此接口不需要额外的参数，公共参数请参考[公共参数][001]
[001]: https://www.qg.net/doc/250.html "公共参数"
查询线路列表
**简要描述：**
- 本接口用于查询线路列表
**输入参数：**
|参数名|必选|类型|说明|
|:---- |:---|:----- |----- |
| productId | 是 | integer | 品牌编号 |
**输入示例：**
- https://qg.net/api/physical-product/lineList?productId=value
**返回参数：**
| 参数名 | 类型 | 说明 |
|:----- |:-----|----- |
| RequestId | string | 请求编号 |
| Code | integer | 返回编号 |
| Message | string | 返回内容 |
| Data[].id | string | - |
| Data[].name | string | 线路名 |
| Data[].code | string | 线路代号 |
| Data[].description | string | 线路描述 |
| Data[].address | string | 寄送地址 |
| Data[].introurl | string | 简介URL |
| Data[].sortid | string | 排序 |
| Data[].buystatus | string | 购买状态 |
| Data[].renewstatus | string | 续费状态 |
| Data[].upgradestatus | string | 升级状态 |
| Data[].defensestatus | string | 防御状态 |
| Data[].brandid | string | 品牌ID |
| Data[].enabled | string | 可用性 |
| Data[].createdat | string | 创建时间 |
| Data[].updatedat | string | 更新时间 |
| Data[].deletedat | string | 删除时间 |
| Data[].bindspecs | string | 绑定的规格ID |
**返回示例：**
JSON格式
```
{
"RequestId": "7E6F1508-B9FB-C3E5-21B2-95E7535E7D47",
"Code" : "200"
"Message":"xxxxxxx"
"Data": [
{
"id": 14,
"superid": 0,
"name": "\u5c71\u4e1c\u67a3\u5e84\u7ebf\u8def",
"code": "sdzz",
"autoid": 6,
"description": "\u5c71\u4e1c\u67a3\u5e84",
"address": "\u5929\u5bab\u5929\u548c\u53f7",
"introurl": null,
"sortid": 0,
"buystatus": 1,
"renewstatus": 1,
"upgradestatus": 1,
"defensestatus": 1,
"brandid": 115,
"enabled": 6,
"createdat": "2021-07-01 17:00:45",
"updatedat": "2021-08-13 23:30:55",
"deletedat": null,
"bondSpecs": [
11,
12,
15,
16,
17
]
}
]
}
```
**错误码：**
|错误码|说明|
|:----- |:-----|:-----|
| - | - |
**备注**
- 更多返回错误代码请看首页的错误代码描述
查询业务详情
**简要描述：**
- 本接口用于查询业务详情。接口请求地址
**参数：**
\- **注：如果不传suid（业务标识），则查询用户名下指定品牌的所有业务信息**
| 参数名 | 必选 | 类型 | 说明 |
| :----- | :--- | :----- | ------------------------------ |
| suid | 否 | string | 业务标识 |
| offset | 否 | int | 偏移量，默认为0 |
| limit | 否 | int | 限制数目，默认值和最大值均为50 |
**输入示例**
https://qg.net/api/cloud-business/getDetail?suid=1
**返回示例**
JSON格式
```
{
"RequestId":'423369C7-AD6F-3GT6-NMJ7-E2RG5N6HG7D3',
"Code": 0,
"Message" : "返回内容"
"Data": {
"1":{
"Suid": "12154545",
"line_no":"ap-shanghai",
"area_no":"ap-shanghai-1",
"spec_no":"s1.samll",
"spec_name":"标准型",
"Host_id": "1",
"Host_name":"1",
"Ip": "192.168.1.1",
"Local_ip": "192.168.1.1",
"Run_status": "1",
"Order_status": "1",
"System_type":"",
"Systemdisks": "40",
"Harddisks_type":""
"Harddiks": "20",
"Bandwidth": "1",
"Defense": "",
"System_no": "sdffsdret",
"System_name": "windows 2012",
"Buy_time": "2020-03-05 16:00:00",
"End_time": "2020-04-05 16:00:00",
"Business_password": "sdsadsa",
"Login_password": "sdfsfdf",
}
}
}
```
**返回参数说明**
| 参数名 | 类型 | 说明 |
| :---------------- | :------ | ------------------------------------------------------------ |
| RequestId | string | 请求编号 |
| Code | integer | 状态码 |
| Message | string | 返回内容 |
| Suid | string | 业务标识 |
| Line_no | string | 线路编号 |
| Area_no | string | 可用区编号 |
| Spec_no | string | 规格编号 |
| Spec_name | string | 规格名称 |
| Host_id | integer | 宿主机ID，没有值 返回空 |
| Host_name | string | 宿主机名称，没有值 返回空 |
| Ip | string | 外网ip |
| Local_ip | string | 内网ip，没有值 返回空 |
| Run_status | integer | 运行状态 。 取值范围： -4：已停止 -1：已关机 0：开通中 1：运行中 2：开机中 3：关机中 4：重启中 5：重装中 6：重置密码中 |
| Order_status | integer | 业务状态。 取值范围： -4：已锁定 -3：失败 0：开通中 1：正常 2：过户中 3：已过期 |
| System_type | string | 系统盘类型， 没有值 返回空 |
| Systemdisks | string | 系统盘 |
| Harddisks_type | string | 数据盘类型， 没有值 返回空 |
| Harddiks | integer | 数据盘 |
| Bandwidth | integer | 带宽 |
| Defense | integer | 防御值， 没有值 返回空 |
| System_no | string | 镜像编号 |
| System_name | string | 镜像名称 |
| Adsl_name | string | 宽带账号， 没有值 返回空 |
| Adsl_password | string | 宽带密码， 没有值 返回空 |
| Buy_time | date | 购买时间 |
| End_time | date | 过期时间 |
| Business_password | string | 面板密码 |
| Login_password | string | 系统密码 |
**备注**
- 更多返回错误代码请看首页的错误代码描述
查询套餐列表
**简要描述：**
- 本接口用于查询可用区关联规格信息。接口请求地址
**注：**
- 当请求参数 line_no 和 area_no 同时存在，area_no 必须为 line_no 所属线路下的 可用区编号。
**参数：**
|参数名|必选|类型|说明|
|:---- |:---|:----- |----- |
|productId |是 |integer | 品牌编号 |
|line_no |否 |string | 线路编号|
|area_no |否 |string | 可用区编号 |
|load_rate|否|integer|是否加载费率（星外格式）
1：是；0：否，默认值：0|
**输入示例**
https://qg.net/api/cloud-product/packageList?productId=104
**返回示例**
JSON格式
```
{
"RequestId":'423369C7-AD6F-3GT6-NMJ7-E2RG5N6HG7D3',
"Code": 0,
"Message" : "返回内容"
"Data": {
"1":{
"Line_no":"ap-beijing",
"Area_id": 342,
"Area_no":"ap-beijing-1",
"Group_name":"标准型S1",
"Group_id":"S1",
"Area_name":"xxx",
"Line_name":"xxx",
"Spec_name":"标准型S1",
"Spec_no":"S1.SMALL2",
"Cpu" : "1",
"Memory": "2",
"Systemdisk":"40",
"Datadisk":"20",
"Bandwidth":"1",
"Ip":"1",
"Defense":"0",
"Trial_time":"",
"Buy_status":1,
"Status":1,
"Upgrade_status":"",
"Package_no": "1111",
"Basic_price": "2079.65",
"User_price": "2079.65",
"Day_rate": "0.01",
"Week_rate": "0.02",
"Month_rate": "0.1",
"Quarter_rate": "0.301",
"Halfyear_rate": "0.53",
"Year_rate": "1"
},
"2":{
"Line_no":"ap-beijing",
"Area_id": 343,
"Area_no":"ap-beijing-1",
"Group_name":"标准型S1",
"Group_id":"S1",
"Area_name":"xxx",
"Line_name":"xxx",
"Spec_name":"标准型S1",
"Spec_no":"S1.MEDIUM2",
"Cpu" : "2",
"Memory": "2",
"Systemdisk":"40",
"Datadisk":"20",
"Bandwidth":"1",
"Ip":"1",
"Defense":"0",
"Trial_time":"",
"Buy_status":1,
"Status":1,
"Upgrade_status":"",
"Package_no": "2222",
"Basic_price": "2079.65",
"User_price": "2079.65",
"Day_rate": "0.01",
"Week_rate": "0.02",
"Month_rate": "0.1",
"Quarter_rate": "0.301",
"Halfyear_rate": "0.53",
"Year_rate": "1"
}
}
}
```
**返回参数说明**
|参数名|类型|说明|
|:----- |:-----|----- |
|RequestId |string |请求编号 |
|Code |integer |状态码 |
|Message |string |返回内容 |
|Line_no |string |线路编号 |
|Area_id |string |可用区ID |
|Area_no |string |可用区编号 |
|Group_name |string |规格组名称 |
|Group_id |string |规格组编号 |
|Spec_name |string |规格名称 |
|Area_name |string |可用区名称 |
|Line_name |string |线路名称 |
|Spec_no |string |规格编号 |
|Cpu |integer |cpu |
|Memory |decimal |内存 |
|Systemdisk |integer |系统盘，单位：G |
|Datadisk |integer |数据盘，单位：G |
|Bandwidth |integer |带宽，单位：M |
|Ip |integer |ip数，单位：个 |
|Defense |integer |防御值，单位：G |
|Trial_time |string |试用时间 |
|Buy_status |integer |购买状态 1:开启 0:关闭 |
|Upgrade_status |integer |升级状态 1:开启 0:关闭|
|Status |integer |规格状态 1:开启 0:关闭|
|package_no |string |套餐编号|
|Basic_price |string |基础价格 |
|User_price |string |会员价格 |
|Day_rate |string |日费率 |
|Week_rate |string |周费率 |
|Month_rate |string |月费率 |
|Quarter_rate |string |季度费率 |
|Halfyear_rate |string |半年费率 |
**备注**
- 更多返回错误代码请看首页的错误代码描述
