kafka-ui REST API文档：接口调用示例-优快云博客

kafka-ui REST API文档：接口调用示例

【免费下载链接】kafka-ui provectus/kafka-ui: Kafka-UI 是一个用于管理和监控Apache Kafka集群的开源Web UI工具，提供诸如主题管理、消费者组查看、生产者测试等功能，便于对Kafka集群进行日常运维工作。项目地址: https://gitcode.com/GitHub_Trending/ka/kafka-ui

1. 引言

你是否还在为Kafka集群管理和监控的复杂性而烦恼？是否需要一个直观、高效的方式来与Kafka集群进行交互？kafka-ui REST API为你提供了强大的接口支持，让你轻松实现主题管理、消费者组监控、消息生产与消费等功能。本文将详细介绍kafka-ui REST API的使用方法，通过丰富的代码示例和清晰的说明，帮助你快速上手，提升Kafka运维效率。

读完本文，你将能够：

掌握kafka-ui REST API的核心接口调用方法
实现主题的创建、查询、更新和删除
管理消费者组，包括偏移量重置和删除
生产和消费Kafka消息
监控和配置Kafka代理（Broker）
使用Schema Registry进行模式管理

2. API概述

2.1 基础信息

kafka-ui REST API基于HTTP/HTTPS协议，采用RESTful设计风格，支持JSON格式的请求和响应。所有API端点均以集群名称（clusterName）作为路径参数，以便在多集群环境中进行区分。

基础URL结构：

http://<kafka-ui-server>:<port>/api/clusters/{clusterName}/...

认证方式：

无认证（默认）
Basic Auth（可选配置）
OAuth2（可选配置）

2.2 接口分类

kafka-ui REST API主要分为以下几类：

接口类别	功能描述	核心控制器
主题管理	创建、查询、更新、删除主题	TopicsController
消费者组管理	查询消费者组、重置偏移量、删除组	ConsumerGroupsController
消息操作	生产消息、消费消息、删除消息	MessagesController
代理管理	查询代理信息、监控指标、配置管理	BrokersController
模式管理	注册、查询、删除模式，兼容性检查	SchemasController

3. 主题管理API

3.1 创建主题

功能：在指定集群中创建新的Kafka主题

请求：

方法：POST
路径：/api/clusters/{clusterName}/topics
请求体：TopicCreationDTO

请求示例：

curl -X POST "http://localhost:8080/api/clusters/my-cluster/topics" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "user-tracking-events",
    "partitions": 8,
    "replicationFactor": 3,
    "configs": [
      {"name": "retention.ms", "value": "604800000"},
      {"name": "cleanup.policy", "value": "compact"}
    ]
  }'

响应示例：

{
  "name": "user-tracking-events",
  "partitions": 8,
  "replicationFactor": 3,
  "configs": [
    {"name": "retention.ms", "value": "604800000", "default": false},
    {"name": "cleanup.policy", "value": "compact", "default": false},
    {"name": "segment.bytes", "value": "1073741824", "default": true}
  ],
  "internal": false,
  "partitionsStats": {
    "total": 8,
    "inSync": 8,
    "offline": 0,
    "underReplicated": 0
  }
}

3.2 查询主题列表

功能：获取指定集群中的主题列表，支持分页和筛选

请求：

方法：GET
路径：/api/clusters/{clusterName}/topics
查询参数：
- page: 页码（默认1）
- perPage: 每页数量（默认25）
- showInternal: 是否显示内部主题（默认false）
- search: 搜索关键词
- orderBy: 排序字段（name, totalPartitions, replicationFactor等）
- sortOrder: 排序方向（asc, desc）

请求示例：

curl -X GET "http://localhost:8080/api/clusters/my-cluster/topics?page=1&perPage=10&search=user&orderBy=name&sortOrder=asc"

响应示例：

{
  "topics": [
    {
      "name": "user-profiles",
      "partitions": 4,
      "replicationFactor": 3,
      "internal": false,
      "partitionsStats": {
        "total": 4,
        "inSync": 4,
        "offline": 0,
        "underReplicated": 0
      }
    },
    {
      "name": "user-tracking-events",
      "partitions": 8,
      "replicationFactor": 3,
      "internal": false,
      "partitionsStats": {
        "total": 8,
        "inSync": 8,
        "offline": 0,
        "underReplicated": 0
      }
    }
  ],
  "pageCount": 5
}

3.3 更新主题配置

功能：修改指定主题的配置参数

请求：

方法：PATCH
路径：/api/clusters/{clusterName}/topics/{topicName}
请求体：TopicUpdateDTO

请求示例：

curl -X PATCH "http://localhost:8080/api/clusters/my-cluster/topics/user-tracking-events" \
  -H "Content-Type: application/json" \
  -d '{
    "configs": [
      {"name": "retention.ms", "value": "1209600000"},
      {"name": "max.message.bytes", "value": "2097152"}
    ]
  }'

响应示例：

{
  "name": "user-tracking-events",
  "partitions": 8,
  "replicationFactor": 3,
  "configs": [
    {"name": "retention.ms", "value": "1209600000", "default": false},
    {"name": "max.message.bytes", "value": "2097152", "default": false},
    {"name": "cleanup.policy", "value": "compact", "default": false},
    {"name": "segment.bytes", "value": "1073741824", "default": true}
  ],
  "internal": false,
  "partitionsStats": {
    "total": 8,
    "inSync": 8,
    "offline": 0,
    "underReplicated": 0
  }
}

3.4 删除主题

功能：删除指定集群中的主题

请求：

方法：DELETE
路径：/api/clusters/{clusterName}/topics/{topicName}

请求示例：

curl -X DELETE "http://localhost:8080/api/clusters/my-cluster/topics/obsolete-topic"

响应示例：

HTTP/1.1 200 OK

4. 消费者组管理API

4.1 查询消费者组详情

功能：获取指定消费者组的详细信息，包括成员、订阅主题和偏移量

请求：

方法：GET
路径：/api/clusters/{clusterName}/consumer-groups/{groupId}

请求示例：

curl -X GET "http://localhost:8080/api/clusters/my-cluster/consumer-groups/user-service-group"

响应示例：

{
  "groupId": "user-service-group",
  "state": "STABLE",
  "coordinatorId": 1,
  "members": [
    {
      "clientId": "user-service-1",
      "consumerId": "consumer-user-service-group-1-abcdef12-3456-7890-abcd-ef1234567890",
      "host": "192.168.1.100:9092",
      "assignment": {
        "topics": [
          {
            "topic": "user-profiles",
            "partitions": [0, 1]
          },
          {
            "topic": "user-events",
            "partitions": [0, 1, 2, 3]
          }
        ]
      }
    },
    {
      "clientId": "user-service-2",
      "consumerId": "consumer-user-service-group-2-abcdef12-3456-7890-abcd-ef1234567890",
      "host": "192.168.1.101:9092",
      "assignment": {
        "topics": [
          {
            "topic": "user-profiles",
            "partitions": [2, 3]
          },
          {
            "topic": "user-events",
            "partitions": [4, 5, 6, 7]
          }
        ]
      }
    }
  ],
  "offsets": [
    {
      "topic": "user-profiles",
      "partition": 0,
      "currentOffset": 1500,
      "endOffset": 1500,
      "lag": 0,
      "metadata": ""
    },
    // 更多分区偏移量...
  ]
}

4.2 重置消费者组偏移量

功能：重置指定消费者组在特定主题上的偏移量

请求：

方法：POST
路径：/api/clusters/{clusterName}/consumer-groups/{groupId}/offsets/reset
请求体：ConsumerGroupOffsetsResetDTO

请求示例：

curl -X POST "http://localhost:8080/api/clusters/my-cluster/consumer-groups/user-service-group/offsets/reset" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "user-events",
    "resetType": "TIMESTAMP",
    "resetToTimestamp": 1620000000000,
    "partitions": [0, 1, 2, 3]
  }'

响应示例：

HTTP/1.1 200 OK

4.3 删除消费者组

功能：删除指定的消费者组

请求：

方法：DELETE
路径：/api/clusters/{clusterName}/consumer-groups/{groupId}

请求示例：

curl -X DELETE "http://localhost:8080/api/clusters/my-cluster/consumer-groups/old-consumer-group"

响应示例：

HTTP/1.1 200 OK

5. 消息操作API

5.1 生产消息

功能：向指定主题发送消息

请求：

方法：POST
路径：/api/clusters/{clusterName}/topics/{topicName}/messages
请求体：CreateTopicMessageDTO

请求示例：

curl -X POST "http://localhost:8080/api/clusters/my-cluster/topics/user-events/messages" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "key": "user123",
        "value": "{\"userId\":\"user123\",\"eventType\":\"login\",\"timestamp\":1620000000000}",
        "partition": 0,
        "headers": [
          {"key": "source", "value": "web"}
        ]
      },
      {
        "key": "user456",
        "value": "{\"userId\":\"user456\",\"eventType\":\"purchase\",\"timestamp\":1620000001000}",
        "partition": 1
      }
    ]
  }'

响应示例：

{
  "offsets": [
    {
      "partition": 0,
      "offset": 1501,
      "timestamp": 1620000002000
    },
    {
      "partition": 1,
      "offset": 2001,
      "timestamp": 1620000002001
    }
  ]
}

5.2 消费消息

功能：从指定主题消费消息，支持不同的消费位置和筛选条件

请求：

方法：GET
路径：/api/clusters/{clusterName}/topics/{topicName}/messages
查询参数：
- seekType: 起始位置类型（beginning, end, timestamp, offset）
- seekTo: 起始位置值（根据seekType确定格式）
- limit: 消息数量限制
- q: 筛选条件
- filterQueryType: 筛选类型（string_contains, groovy_script）
- seekDirection: 消费方向（forward, backward）
- keySerde: key序列化器
- valueSerde: value序列化器

请求示例：

curl -X GET "http://localhost:8080/api/clusters/my-cluster/topics/user-events/messages?seekType=beginning&limit=10&keySerde=string&valueSerde=json"

响应示例：

{
  "records": [
    {
      "topic": "user-events",
      "partition": 0,
      "offset": 1500,
      "timestamp": 1620000000000,
      "key": "user123",
      "value": {
        "userId": "user123",
        "eventType": "login",
        "timestamp": 1620000000000
      },
      "headers": [
        {"key": "source", "value": "web"}
      ],
      "size": 128
    },
    // 更多消息...
  ],
  "total": 10,
  "hasMore": true
}

5.3 删除消息

功能：删除指定主题分区中的消息（仅支持日志压缩主题）

请求：

方法：DELETE
路径：/api/clusters/{clusterName}/topics/{topicName}/messages
请求体：包含要删除的分区列表

请求示例：

curl -X DELETE "http://localhost:8080/api/clusters/my-cluster/topics/user-sessions/messages" \
  -H "Content-Type: application/json" \
  -d '[0, 1, 2]'

响应示例：

HTTP/1.1 200 OK

6. 代理管理API

6.1 查询代理列表

功能：获取指定集群中的代理节点列表

请求：

方法：GET
路径：/api/clusters/{clusterName}/brokers

请求示例：

curl -X GET "http://localhost:8080/api/clusters/my-cluster/brokers"

响应示例：

{
  "brokers": [
    {
      "id": 1,
      "host": "broker1:9092",
      "port": 9092,
      "version": "2.8.0",
      "isController": true,
      "metrics": {
        "activeControllersCount": 1,
        "networkProcessorAvgIdlePercent": 0.9,
        "requestHandlerAvgIdlePercent": 0.85
      }
    },
    {
      "id": 2,
      "host": "broker2:9092",
      "port": 9092,
      "version": "2.8.0",
      "isController": false,
      "metrics": {
        "activeControllersCount": 0,
        "networkProcessorAvgIdlePercent": 0.88,
        "requestHandlerAvgIdlePercent": 0.82
      }
    },
    {
      "id": 3,
      "host": "broker3:9092",
      "port": 9092,
      "version": "2.8.0",
      "isController": false,
      "metrics": {
        "activeControllersCount": 0,
        "networkProcessorAvgIdlePercent": 0.89,
        "requestHandlerAvgIdlePercent": 0.84
      }
    }
  ]
}

6.2 查询代理配置

功能：获取指定代理节点的配置

请求：

方法：GET
路径：/api/clusters/{clusterName}/brokers/{brokerId}/config

请求示例：

curl -X GET "http://localhost:8080/api/clusters/my-cluster/brokers/1/config"

响应示例：

{
  "configs": [
    {
      "name": "advertised.listeners",
      "value": "PLAINTEXT://broker1:9092",
      "default": false,
      "readOnly": false,
      "sensitive": false,
      "source": "STATIC_BROKER_CONFIG"
    },
    {
      "name": "auto.create.topics.enable",
      "value": "true",
      "default": true,
      "readOnly": false,
      "sensitive": false,
      "source": "DEFAULT_CONFIG"
    },
    {
      "name": "log.retention.hours",
      "value": "168",
      "default": true,
      "readOnly": false,
      "sensitive": false,
      "source": "DEFAULT_CONFIG"
    },
    // 更多配置...
  ]
}

7. Schema Registry API

7.1 注册新模式

功能：在Schema Registry中注册新模式

请求：

方法：POST
路径：/api/clusters/{clusterName}/schemas
请求体：NewSchemaSubjectDTO

请求示例：

curl -X POST "http://localhost:8080/api/clusters/my-cluster/schemas" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "user-events-value",
    "schemaType": "AVRO",
    "schema": "{\"type\":\"record\",\"name\":\"UserEvent\",\"namespace\":\"com.example\",\"fields\":[{\"name\":\"userId\",\"type\":\"string\"},{\"name\":\"eventType\",\"type\":\"string\"},{\"name\":\"timestamp\",\"type\":\"long\"}]}"
  }'

响应示例：

{
  "subject": "user-events-value",
  "version": 1,
  "id": 1,
  "schemaType": "AVRO",
  "schema": "{\"type\":\"record\",\"name\":\"UserEvent\",\"namespace\":\"com.example\",\"fields\":[{\"name\":\"userId\",\"type\":\"string\"},{\"name\":\"eventType\",\"type\":\"string\"},{\"name\":\"timestamp\",\"type\":\"long\"}]}",
  "references": []
}

7.2 查询模式

功能：获取指定主题的最新模式

请求：

方法：GET
路径：/api/clusters/{clusterName}/schemas/{subject}/latest

请求示例：

curl -X GET "http://localhost:8080/api/clusters/my-cluster/schemas/user-events-value/latest"

响应示例：

{
  "subject": "user-events-value",
  "version": 1,
  "id": 1,
  "schemaType": "AVRO",
  "schema": "{\"type\":\"record\",\"name\":\"UserEvent\",\"namespace\":\"com.example\",\"fields\":[{\"name\":\"userId\",\"type\":\"string\"},{\"name\":\"eventType\",\"type\":\"string\"},{\"name\":\"timestamp\",\"type\":\"long\"}]}",
  "references": []
}

7.3 检查模式兼容性

功能：检查新模式与现有模式的兼容性

请求：

方法：POST
路径：/api/clusters/{clusterName}/schemas/{subject}/compatibility
请求体：NewSchemaSubjectDTO

请求示例：

curl -X POST "http://localhost:8080/api/clusters/my-cluster/schemas/user-events-value/compatibility" \
  -H "Content-Type: application/json" \
  -d '{
    "schemaType": "AVRO",
    "schema": "{\"type\":\"record\",\"name\":\"UserEvent\",\"namespace\":\"com.example\",\"fields\":[{\"name\":\"userId\",\"type\":\"string\"},{\"name\":\"eventType\",\"type\":\"string\"},{\"name\":\"timestamp\",\"type\":\"long\"},{\"name\":\"ipAddress\",\"type\":\"string\"}]}",
    "references": []
  }'

响应示例：

{
  "isCompatible": true,
  "message": "Schema is compatible with the latest version"
}

8. API调用流程示例

以下是一个完整的kafka-ui API调用流程示例，展示了如何创建主题、注册模式、生产消息和消费消息：

mermaid

9. 总结与展望

本文详细介绍了kafka-ui REST API的核心功能和使用方法，包括主题管理、消费者组管理、消息操作、代理管理和Schema Registry等模块。通过丰富的代码示例和清晰的说明，帮助读者快速掌握API的使用技巧。

kafka-ui REST API为Kafka集群管理提供了强大的接口支持，能够满足各种自动化和集成需求。未来，随着kafka-ui的不断发展，API将进一步完善，提供更多高级功能，如集群监控告警、数据迁移工具等。

如果你觉得本文对你有帮助，请点赞、收藏并关注我们，获取更多Kafka和kafka-ui的使用技巧和最佳实践。下期我们将介绍如何使用kafka-ui API构建自定义监控仪表盘，敬请期待！

10. 附录：API参考速查表

API类别	端点	方法	主要功能
主题管理	/topics	GET	查询主题列表
主题管理	/topics	POST	创建主题
主题管理	/topics/{topicName}	GET	查询主题详情
主题管理	/topics/{topicName}	PATCH	更新主题配置
主题管理	/topics/{topicName}	DELETE	删除主题
消费者组	/consumer-groups	GET	查询消费者组列表
消费者组	/consumer-groups/{groupId}	GET	查询消费者组详情
消费者组	/consumer-groups/{groupId}	DELETE	删除消费者组
消费者组	/consumer-groups/{groupId}/offsets/reset	POST	重置消费者组偏移量
消息操作	/topics/{topicName}/messages	GET	消费消息
消息操作	/topics/{topicName}/messages	POST	生产消息
消息操作	/topics/{topicName}/messages	DELETE	删除消息
代理管理	/brokers	GET	查询代理列表
代理管理	/brokers/{brokerId}	GET	查询代理详情
代理管理	/brokers/{brokerId}/config	GET	查询代理配置
模式管理	/schemas	GET	查询模式列表
模式管理	/schemas	POST	注册新模式
模式管理	/schemas/{subject}/latest	GET	查询最新模式
模式管理	/schemas/{subject}/compatibility	POST	检查模式兼容性

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考