pyGoEdge-UserPanel/reference/goedge 文档/IPItemService.md

# IPItemService
> IP条目管理

---

## checkIPItemStatus
> 检查IP状态

- 角色：`admin`
- HTTP：`POST https://backend.dooki.cloud/IPItemService/checkIPItemStatus`
- RPC：`rpc checkIPItemStatus (CheckIPItemStatusRequest) returns (CheckIPItemStatusResponse);`

**请求对象 (`CheckIPItemStatusRequest`)**

```json
{
  "ipListId": "int64",
  "ip": "string"
}
```

**响应对象 (`CheckIPItemStatusResponse`)**

```json
{
  "isOk": "bool // 是否查询成功",
  "error": "string",
  "isFound": "bool // 是否找到",
  "isAllowed": "bool // 是否允许",
  "ipItem": "IPItem // 匹配的IPItem"
}
```

**调用示例**

```bash
curl -X POST "https://backend.dooki.cloud/IPItemService/checkIPItemStatus" \
  -H "Content-Type: application/json" \
  -H "X-Edge-Access-Token: <YOUR_TOKEN>" \
  -d '{
    ...
  }'
```

---

## countAllEnabledIPItems
> 计算所有IP数量

- 角色：`admin`, `user`
- HTTP：`POST https://backend.dooki.cloud/IPItemService/countAllEnabledIPItems`
- RPC：`rpc countAllEnabledIPItems(CountAllEnabledIPItemsRequest) returns (RPCCountResponse);`

**请求对象 (`CountAllEnabledIPItemsRequest`)**

```json
{
  "keyword": "string // 关键词",
  "ip": "string // 单个IP，搜索单个IP时需要",
  "globalOnly": "bool // 是否为自动添加的IP",
  "unread": "bool // 是否未读",
  "eventLevel": "string // 事件级别",
  "listType": "string // 列表类型：black|white",
  "userId": "int64 // 用户ID，只有管理员才有权限指定用户ID"
}
```

**响应对象 (`RPCCountResponse`)**

```json
{
  "count": "int64 // 数量"
}
```

**调用示例**

```bash
curl -X POST "https://backend.dooki.cloud/IPItemService/countAllEnabledIPItems" \
  -H "Content-Type: application/json" \
  -H "X-Edge-Access-Token: <YOUR_TOKEN>" \
  -d '{
    ...
  }'
```

---

## countIPItemsWithListId
> 计算IP数量

- 角色：`admin`, `user`
- HTTP：`POST https://backend.dooki.cloud/IPItemService/countIPItemsWithListId`
- RPC：`rpc countIPItemsWithListId (CountIPItemsWithListIdRequest) returns (RPCCountResponse);`

**请求对象 (`CountIPItemsWithListIdRequest`)**

```json
{
  "ipListId": "int64",
  "keyword": "string // 关键词",
  "ipFrom": "string",
  "ipTo": "string",
  "eventLevel": "string"
}
```

**响应对象 (`RPCCountResponse`)**

```json
{
  "count": "int64 // 数量"
}
```

**调用示例**

```bash
curl -X POST "https://backend.dooki.cloud/IPItemService/countIPItemsWithListId" \
  -H "Content-Type: application/json" \
  -H "X-Edge-Access-Token: <YOUR_TOKEN>" \
  -d '{
    ...
  }'
```

---

## createIPItem
> 创建IP

- 角色：`dns`, `user`, `node`, `admin`
- HTTP：`POST https://backend.dooki.cloud/IPItemService/createIPItem`
- RPC：`rpc createIPItem (CreateIPItemRequest) returns (CreateIPItemResponse);`

**请求对象 (`CreateIPItemRequest`)**

```json
{
  "ipListId": "int64 // 所属IP列表ID",
  "value": "string // IP原始值，比如单个IP、IP范围或者CIDR，指定了原始值后，无需设置ipFrom和ipTo两个参数",
  "ipFrom": "string // 开始IP",
  "ipTo": "string // 结束IP（可选）",
  "expiredAt": "int64 // 过期时间戳（可选）",
  "reason": "string // 加入理由（可选）",
  "type": "string // IP类型，值为ipv4或ipv6",
  "eventLevel": "string // 级别：debug, notice, warning, error, critical, fatal",
  "nodeId": "int64 // 可选项，所属节点ID",
  "serverId": "int64 // 可选项，所属网站ID",
  "sourceNodeId": "int64 // 可选项，来源节点",
  "sourceServerId": "int64 // 可选项，来源网站ID",
  "sourceHTTPFirewallPolicyId": "int64 // 可选项，来源WAF策略ID",
  "sourceHTTPFirewallRuleGroupId": "int64 // 可选项，来源WAF规则分组ID",
  "sourceHTTPFirewallRuleSetId": "int64 // 可选项，来源WAF规则集ID"
}
```

**响应对象 (`CreateIPItemResponse`)**

```json
{
  "ipItemId": "int64"
}
```

**调用示例**

```bash
curl -X POST "https://backend.dooki.cloud/IPItemService/createIPItem" \
  -H "Content-Type: application/json" \
  -H "X-Edge-Access-Token: <YOUR_TOKEN>" \
  -d '{
    ...
  }'
```

---

## createIPItems
> 创建一组IP

- 角色：`dns`, `user`, `node`, `admin`
- HTTP：`POST https://backend.dooki.cloud/IPItemService/createIPItems`
- RPC：`rpc createIPItems(CreateIPItemsRequest) returns (CreateIPItemsResponse);`

**请求对象 (`CreateIPItemsRequest`)**

```json
{
  "ipItems": "[]IPItem // 要创建的IP列表",
  "ipListId": "int64 // IP列表ID",
  "value": "string // IP原始值，比如单个IP、IP范围或者CIDR，指定了原始值后，无需设置ipFrom和ipTo两个参数",
  "ipFrom": "string // 开始IP",
  "ipTo": "string // 结束IP（可选）",
  "expiredAt": "int64 // 过期时间戳（可选）",
  "reason": "string // 加入理由（可选）",
  "type": "string // 类型",
  "eventLevel": "string // 级别",
  "nodeId": "int64 // 所属节点ID",
  "serverId": "int64 // 所属服务ID",
  "sourceNodeId": "int64",
  "sourceServerId": "int64",
  "sourceHTTPFirewallPolicyId": "int64",
  "sourceHTTPFirewallRuleGroupId": "int64",
  "sourceHTTPFirewallRuleSetId": "int64"
}
```

**响应对象 (`CreateIPItemsResponse`)**

```json
{
  "ipItemIds": "[]int64 // 创建后的IP ID列表"
}
```

**调用示例**

```bash
curl -X POST "https://backend.dooki.cloud/IPItemService/createIPItems" \
  -H "Content-Type: application/json" \
  -H "X-Edge-Access-Token: <YOUR_TOKEN>" \
  -d '{
    ...
  }'
```

---

## deleteIPItem
> 删除IP

- 角色：`admin`, `user`
- HTTP：`POST https://backend.dooki.cloud/IPItemService/deleteIPItem`
- RPC：`rpc deleteIPItem (DeleteIPItemRequest) returns (RPCSuccess);`

**请求对象 (`DeleteIPItemRequest`)**

```json
{
  "ipItemId": "int64 // IP条目的ID",
  "value": "string // IP原始值，比如单个IP、IP范围或者CIDR，指定了原始值后，无需设置ipFrom和ipTo两个参数",
  "ipFrom": "string // v0.4.8新增，开始IP，和ipItemId二选一",
  "ipTo": "string // v0.4.8新增，结束IP，和ipItemId二选一",
  "ipListId": "int64 // v0.4.8新增，IP列表，IP所在的IP列表，如果不指定，则会删除所有IP列表中的相关IP信息"
}
```

**响应对象 (`RPCSuccess`)**

```json
{}
```

**调用示例**

```bash
curl -X POST "https://backend.dooki.cloud/IPItemService/deleteIPItem" \
  -H "Content-Type: application/json" \
  -H "X-Edge-Access-Token: <YOUR_TOKEN>" \
  -d '{
    ...
  }'
```

---

## deleteIPItems
> 批量删除IP

- 角色：`admin`, `user`
- HTTP：`POST https://backend.dooki.cloud/IPItemService/deleteIPItems`
- RPC：`rpc deleteIPItems(DeleteIPItemsRequest) returns (RPCSuccess);`

**请求对象 (`DeleteIPItemsRequest`)**

```json
{
  "ipItemIds": "[]int64"
}
```

**响应对象 (`RPCSuccess`)**

```json
{}
```

**调用示例**

```bash
curl -X POST "https://backend.dooki.cloud/IPItemService/deleteIPItems" \
  -H "Content-Type: application/json" \
  -H "X-Edge-Access-Token: <YOUR_TOKEN>" \
  -d '{
    ...
  }'
```

---

## existsEnabledIPItem
> 检查IP是否存在

- 角色：`admin`
- HTTP：`POST https://backend.dooki.cloud/IPItemService/existsEnabledIPItem`
- RPC：`rpc existsEnabledIPItem (ExistsEnabledIPItemRequest) returns (ExistsEnabledIPItemResponse);`

**请求对象 (`ExistsEnabledIPItemRequest`)**

```json
{
  "ipItemId": "int64"
}
```

**响应对象 (`ExistsEnabledIPItemResponse`)**

```json
{
  "exists": "bool"
}
```

**调用示例**

```bash
curl -X POST "https://backend.dooki.cloud/IPItemService/existsEnabledIPItem" \
  -H "Content-Type: application/json" \
  -H "X-Edge-Access-Token: <YOUR_TOKEN>" \
  -d '{
    ...
  }'
```

---

## findEnabledIPItem
> 查找单个IP

- 角色：`admin`, `user`
- HTTP：`POST https://backend.dooki.cloud/IPItemService/findEnabledIPItem`
- RPC：`rpc findEnabledIPItem (FindEnabledIPItemRequest) returns (FindEnabledIPItemResponse);`

**请求对象 (`FindEnabledIPItemRequest`)**

```json
{
  "ipItemId": "int64"
}
```

**响应对象 (`FindEnabledIPItemResponse`)**

```json
{
  "ipItem": "IPItem"
}
```

**调用示例**

```bash
curl -X POST "https://backend.dooki.cloud/IPItemService/findEnabledIPItem" \
  -H "Content-Type: application/json" \
  -H "X-Edge-Access-Token: <YOUR_TOKEN>" \
  -d '{
    ...
  }'
```

---

## findServerIdWithIPItemId
> 查找IP对应的名单所属网站ID

- 角色：`admin`, `user`
- HTTP：`POST https://backend.dooki.cloud/IPItemService/findServerIdWithIPItemId`
- RPC：`rpc findServerIdWithIPItemId(FindServerIdWithIPItemIdRequest) returns (FindServerIdWithIPItemIdResponse);`

**请求对象 (`FindServerIdWithIPItemIdRequest`)**

```json
{
  "ipItemId": "int64 // IP ID"
}
```

**响应对象 (`FindServerIdWithIPItemIdResponse`)**

```json
{
  "serverId": "int64 // 网站ID"
}
```

**调用示例**

```bash
curl -X POST "https://backend.dooki.cloud/IPItemService/findServerIdWithIPItemId" \
  -H "Content-Type: application/json" \
  -H "X-Edge-Access-Token: <YOUR_TOKEN>" \
  -d '{
    ...
  }'
```

---

## listAllEnabledIPItems
> 列出所有名单中的IP

- 角色：`admin`, `user`
- HTTP：`POST https://backend.dooki.cloud/IPItemService/listAllEnabledIPItems`
- RPC：`rpc listAllEnabledIPItems(ListAllEnabledIPItemsRequest) returns (ListAllEnabledIPItemsResponse);`

**请求对象 (`ListAllEnabledIPItemsRequest`)**

```json
{
  "keyword": "string // 关键词",
  "ip": "string // 单个IP，搜索单个IP时需要",
  "globalOnly": "bool // 是否为自动添加的IP",
  "unread": "bool // 是否未读",
  "eventLevel": "string // 事件级别",
  "listType": "string // 列表类型：black|white",
  "userId": "int64 // 用户ID，只有管理员才有权限指定用户ID",
  "offset": "int64 // 读取位置，从0开始",
  "size": "int64 // 每次读取数量"
}
```

**响应对象 (`ListAllEnabledIPItemsResponse`)**

```json
{
  "results": "[]Result",
  "ipList": "IPList // 所属名单",
  "ipItem": "IPItem // IP信息",
  "server": "Server // 所属服务",
  "httpFirewallPolicy": "HTTPFirewallPolicy // 所属WAF策略"
}
```

**调用示例**

```bash
curl -X POST "https://backend.dooki.cloud/IPItemService/listAllEnabledIPItems" \
  -H "Content-Type: application/json" \
  -H "X-Edge-Access-Token: <YOUR_TOKEN>" \
  -d '{
    ...
  }'
```

---

## listAllIPItemIds
> 列出所有名单中的IP ID

- 角色：`admin`, `user`
- HTTP：`POST https://backend.dooki.cloud/IPItemService/listAllIPItemIds`
- RPC：`rpc listAllIPItemIds(ListAllIPItemIdsRequest) returns (ListAllIPItemIdsResponse);`

**请求对象 (`ListAllIPItemIdsRequest`)**

```json
{
  "keyword": "string // 关键词",
  "ip": "string // 单个IP，搜索单个IP时需要",
  "globalOnly": "bool // 是否为自动添加的IP",
  "unread": "bool // 是否未读",
  "eventLevel": "string // 事件级别",
  "listType": "string // 列表类型：black|white",
  "userId": "int64 // 用户ID，只有管理员才有权限指定用户ID",
  "offset": "int64 // 读取位置，从0开始",
  "size": "int64 // 每次读取数量"
}
```

**响应对象 (`ListAllIPItemIdsResponse`)**

```json
{
  "ipItemIds": "[]int64 // IP ID列表"
}
```

**调用示例**

```bash
curl -X POST "https://backend.dooki.cloud/IPItemService/listAllIPItemIds" \
  -H "Content-Type: application/json" \
  -H "X-Edge-Access-Token: <YOUR_TOKEN>" \
  -d '{
    ...
  }'
```

---

## listIPItemsAfterVersion
> 根据版本列出一组IP

- 角色：`node`, `admin`
- HTTP：`POST https://backend.dooki.cloud/IPItemService/listIPItemsAfterVersion`
- RPC：`rpc listIPItemsAfterVersion (ListIPItemsAfterVersionRequest) returns (ListIPItemsAfterVersionResponse);`

**请求对象 (`ListIPItemsAfterVersionRequest`)**

```json
{
  "version": "int64 // 版本号",
  "size": "int64 // 数量"
}
```

**响应对象 (`ListIPItemsAfterVersionResponse`)**

```json
{
  "ipItems": "[]IPItem",
  "version": "int64 // 新的版本号"
}
```

**调用示例**

```bash
curl -X POST "https://backend.dooki.cloud/IPItemService/listIPItemsAfterVersion" \
  -H "Content-Type: application/json" \
  -H "X-Edge-Access-Token: <YOUR_TOKEN>" \
  -d '{
    ...
  }'
```

---

## listIPItemsWithListId
> 列出单页的IP

- 角色：`admin`, `user`
- HTTP：`POST https://backend.dooki.cloud/IPItemService/listIPItemsWithListId`
- RPC：`rpc listIPItemsWithListId (ListIPItemsWithListIdRequest) returns (ListIPItemsWithListIdResponse);`

**请求对象 (`ListIPItemsWithListIdRequest`)**

```json
{
  "ipListId": "int64",
  "keyword": "string // 关键词",
  "ipFrom": "string",
  "ipTo": "string",
  "eventLevel": "string",
  "offset": "int64 // 读取位置",
  "size": "int64 // 数量，通常不能小于0"
}
```

**响应对象 (`ListIPItemsWithListIdResponse`)**

```json
{
  "ipItems": "[]IPItem"
}
```

**调用示例**

```bash
curl -X POST "https://backend.dooki.cloud/IPItemService/listIPItemsWithListId" \
  -H "Content-Type: application/json" \
  -H "X-Edge-Access-Token: <YOUR_TOKEN>" \
  -d '{
    ...
  }'
```

---

## updateIPItem
> 修改IP

- 角色：`admin`, `user`
- HTTP：`POST https://backend.dooki.cloud/IPItemService/updateIPItem`
- RPC：`rpc updateIPItem (UpdateIPItemRequest) returns (RPCSuccess);`

**请求对象 (`UpdateIPItemRequest`)**

```json
{
  "ipItemId": "int64",
  "value": "string // IP原始值，比如单个IP、IP范围或者CIDR，指定了原始值后，无需设置ipFrom和ipTo两个参数",
  "ipFrom": "string // 开始IP",
  "ipTo": "string // 结束IP（可选）",
  "expiredAt": "int64",
  "reason": "string",
  "type": "string // 类型",
  "eventLevel": "string // 级别"
}
```

**响应对象 (`RPCSuccess`)**

```json
{}
```

**调用示例**

```bash
curl -X POST "https://backend.dooki.cloud/IPItemService/updateIPItem" \
  -H "Content-Type: application/json" \
  -H "X-Edge-Access-Token: <YOUR_TOKEN>" \
  -d '{
    ...
  }'
```

---

## updateIPItemsRead
> 设置所有为已读

- 角色：`admin`, `user`
- HTTP：`POST https://backend.dooki.cloud/IPItemService/updateIPItemsRead`
- RPC：`rpc updateIPItemsRead(UpdateIPItemsReadRequest) returns (RPCSuccess);`

**请求对象 (`UpdateIPItemsReadRequest`)**

```json
{}
```

**响应对象 (`RPCSuccess`)**

```json
{}
```

**调用示例**

```bash
curl -X POST "https://backend.dooki.cloud/IPItemService/updateIPItemsRead" \
  -H "Content-Type: application/json" \
  -H "X-Edge-Access-Token: <YOUR_TOKEN>" \
  -d '{
    ...
  }'
```

---