# 从 Kafka 导入数据

通过 Kafka 连接器访问集群，再在导入任务中选择主题并将消息写入 Catalog 结构化表。连接器保存连接与认证配置；消费组、主题和起始位置属于导入任务配置。

## 准备连接

开始前，准备可从 MOI 执行环境访问的 Kafka 地址、认证信息、目标主题和可写入的 Catalog 数据库。使用 Schema Registry 时，还需准备相应地址和凭据。

1. 在**数据连接 > 连接器**中新建连接器，选择 **Kafka**。
2. 填写集群地址 `bootstrap_servers` 和安全协议。
3. 根据安全协议填写证书或 SASL 认证信息。
4. 使用 Schema Registry 时填写其配置。
5. 测试连接，通过后保存。

| 安全协议 | 需要检查 |
| --- | --- |
| `PLAINTEXT` | 无加密连接的网络与集群访问范围。 |
| `SSL` | TLS 连接及需要使用的 CA 证书。 |
| `SASL_PLAINTEXT` | SASL 机制、用户名和密码。 |
| `SASL_SSL` | SASL 认证及 TLS 证书配置。 |

SASL 机制包括 `PLAIN`、`SCRAM-SHA-256` 和 `SCRAM-SHA-512`。认证信息应填入对应字段，不写入连接器名称、说明或截图。

## 选择主题并创建导入任务

1. 创建结构化导入任务，选择已保存的 Kafka 连接器。
2. 探测并选择目标主题，检查采样内容或可用字段信息。
3. 按导入表单配置消费组、主题和起始位置，核对该配置适用于首次接入还是继续处理。
4. 选择已有目标表，或在目标数据库中新建表；检查消息字段、目标列及类型映射。
5. 检查写入规则后提交任务。
6. 在任务详情查看运行状态，并到 Catalog 目标表查询一条可辨认的测试消息。

主题探测或采样成功不等于所有消息都符合相同结构。不要把连接测试通过当作主题读取和目标表写入已经验证。具体消息格式与字段结构能力应以当前任务表单、采样结果和错误提示为准。

## 检查和恢复

连接失败时，检查地址、安全协议、证书、SASL 机制及网络访问；主题不可见时，检查主题名称和访问权限。目标表写入失败时，检查字段映射、数据类型及写入权限。

调整消费起始位置或重新创建任务前，先检查已有运行和目标数据，避免重复消费造成重复写入。暂停、恢复和重试应使用任务详情实际提供的操作，不能把重新创建任务当作所有故障的默认处理。

程序化操作见 SDK [检查数据源与采样](../../../developer/sdk/ai-studio/数据连接/检查数据源与采样.md)。
