3. eAPI原理与实战

eAPI（Arista eAPI）是 EOS 内置的 HTTP/HTTPS 接口，它把 CLI 命令、配置操作和部分系统状态封装成 JSON-RPC 服务，让自动化脚本不必再通过 SSH 交互式地“敲命令—读回显”。理解 eAPI 的关键，是把它看成一个“带认证的 JSON-RPC 网关”：客户端用 HTTP POST 把 JSON 请求发到 /command-api，EOS 解析后执行对应命令，再把结构化结果以 JSON 返回。整个过程不依赖屏幕抓取，输出字段稳定，适合被程序消费。

传输层：HTTP 与 HTTPS 的取舍

eAPI 默认监听 80（HTTP）和 443（HTTPS）。HTTP 明文传输，账号密码和配置内容在网络中可被嗅探，只适合实验环境或带外管理网；生产环境应使用 HTTPS，并配合证书校验。EOS 默认使用自签名证书，客户端若开启严格校验会失败，常见做法是把设备证书导入信任库，或在受控内网中显式关闭校验（不推荐长期使用）。

启用 eAPI 的基本配置如下，其中 protocol https 表示只开放 HTTPS，local-http 表示允许本地 HTTP 访问：

management api http-commands
   protocol https
   no shutdown
   vrf MGMT
      no shutdown

配置后可用 show management api http-commands 查看监听状态、已启用协议和当前会话数。若返回 Enabled: Yes 且 HTTPS 端口为 443，说明服务已就绪。

JSON-RPC 请求与响应结构

eAPI 的请求体遵循 JSON-RPC 2.0 风格，核心字段包括：jsonrpc（固定为 "2.0"）、method（通常为 "runCmds"）、params（包含 version、cmds、format）、id（请求标识）。cmds 是一个字符串数组，每个元素是一条 CLI 命令；format 可选 "json" 或 "text"，选 "json" 时返回结构化对象，选 "text" 时返回原始文本。

下面是一个查询接口状态的请求示例：

{
  "jsonrpc": "2.0",
  "method": "runCmds",
  "params": {
    "version": 1,
    "cmds": ["show interfaces Ethernet1"],
    "format": "json"
  },
  "id": "req-001"
}

响应中 result 数组与 cmds 一一对应，每个元素是该命令的 JSON 结果。若命令执行失败，响应会包含 error 对象，其中有 code、message 和 data，data 里通常还能看到具体哪条命令出错。判断成功与否，应优先检查是否存在 error 字段，而不是只看 HTTP 状态码——eAPI 在命令级错误时仍可能返回 200。

认证方式

eAPI 支持三种认证：本地用户名密码、基于 aaa authentication 的集中认证、以及基于令牌的会话认证。最常用的是 HTTP Basic Auth，即在请求头中携带 Authorization: Basic base64(user:pass)。这种方式简单，但每次请求都要带密码，建议只在 HTTPS 下使用。

更安全的是先调用 createSession 获取会话令牌，后续请求在 params 中带上 session 字段，令牌默认有效期 300 秒，可通过 session-timeout 调整。令牌方式避免了密码反复传输，适合批量操作。无论哪种方式，账号都需要具备对应命令的权限级别（privilege level），否则会返回权限错误。

命令操作与配置操作

eAPI 执行命令时，默认在特权模式（enable mode）下运行，因此 show 类命令可直接执行。若需要进入配置模式，可在 cmds 中依次写入 configure、配置命令、end，EOS 会按顺序执行。例如批量修改接口描述：

{
  "jsonrpc": "2.0",
  "method": "runCmds",
  "params": {
    "version": 1,
    "cmds": [
      "configure",
      "interface Ethernet1",
      "description uplink-to-spine1",
      "end"
    ],
    "format": "json"
  },
  "id": "cfg-001"
}

注意：配置命令的返回结果通常为空对象，不能仅凭返回内容判断是否生效，应再发一条 show running-config interface Ethernet1 做校验。此外，eAPI 默认不自动保存配置，需要显式执行 write memory 或 copy running-config startup-config。

批量请求与错误处理

批量请求有两种粒度：一是单次请求的 cmds 数组包含多条命令，按顺序执行；二是通过 HTTP 连接复用连续发送多个请求。前者适合有依赖关系的命令序列，后者适合独立查询的并发采集。批量执行时，若中间某条命令失败，后续命令默认不再执行，响应中会指出失败位置。

错误处理建议遵循以下原则：先解析 error 字段，再根据 code 区分是语法错误、权限错误还是命令不存在；对可重试的网络超时，采用指数退避；对配置类操作，失败后应回滚或至少记录现场。下面是一个判断逻辑的示意：

实际编写脚本时，建议把“发送请求—解析响应—判断错误—记录日志”封装成统一函数，避免每个命令重复处理。对于批量配置，可先构造命令列表，再一次性提交；若担心部分失败，可拆成多个小批次，每批执行后校验 running-config，确认无误再继续。

掌握 eAPI 后，自动化脚本可以用统一接口完成查询、配置、校验和错误处理，为后续批量设备操作和配置一致性检查打下基础。