[comment]: # ({f372a49b-bdae00e2})
# 4 Zabbix agent 2 插件协议

Zabbix agent 2协议基于代码、大小和数据模型。

[comment]: # ({/f372a49b-bdae00e2})

[comment]: # ({b65bf947-dc813c37})


### 代码

| 类型 | 大小 | 说明 |
|-----|-----|----------|
| Byte | 4    | 负载类型，目前仅支持JSON格式。 |

[comment]: # ({/b65bf947-dc813c37})

[comment]: # ({8edb0275-b578c7c3})


### 大小

| 类型 | 大小 | 说明 |
|-----|-----|----------|
| Byte | 4    | 当前有效载荷的大小（字节）。 |

[comment]: # ({/8edb0275-b578c7c3})

[comment]: # ({0351e98f-bed7d280})


### 负载数据

| 类型 | 大小 | 说明 |
|-----|-----|----------|
| Byte | 由*Size*字段定义 | JSON格式数据. |

[comment]: # ({/0351e98f-bed7d280})

[comment]: # ({60a41fe8-07d42895})
##### Payload 数据定义

###### 通用数据

以下参数存在于所有请求/响应中:

| 名称 | 类型 | 说明 |
|-----|--------|----------|
| id | uint32 | 对于请求 - 用于将请求与响应关联的递增标识符。在请求方向内唯一（即从agent到插件或从插件到agent）。<br>对于响应 - 对应请求的ID。 |
| type | uint32 | 请求类型。 |

[comment]: # ({/60a41fe8-07d42895})

[comment]: # ({3cf942f4-1c1af50c})


###### 日志请求

插件发送的请求，用于将日志消息写入agent日志file。

|     |     |
|---|---|
| direction | plugin → agent |
| response | no  |

日志请求的特定参数：

| Name | Type | Comments |
|---------|--------|----------|
| severity | uint32 | 消息严重性（日志级别）。 |
| message | string | 要记录的日志消息。 |

*示例：*

    
{"id":0,"type":1,"severity":3,"message":"message"}

[comment]: # ({/3cf942f4-1c1af50c})

[comment]: # ({3640b089-9b4addbb})


###### 注册请求

由agent在agent启动阶段发送的请求，用于获取提供的指标以注册插件。

|     |     |
|---|---|
| direction | agent → 插件 |
| 响应 | 是 |

注册请求特有的参数:

| 名称 | 类型 | 备注 |
|---------|--------|----------|
| version | string | 协议 version <主版本号>.<次版本号> |

*示例:*

    
{"id":1,"type":2,"version":"1.0"}

[comment]: # ({/3640b089-9b4addbb})

[comment]: # ({92946a86-802a684d})


###### 注册响应

插件对注册请求的响应。

|     |     |
|---|---|
| direction | plugin → agent |
| response | n/a |

注册响应特有的参数：

| Name | Type | Comments |
|---------|--------|----------|
| name | string | 插件名称。 |
| metrics | array of strings (optional) | 插件中使用的指标及其描述。返回RegisterMetrics()。如果返回错误则不存在。 |
| interfaces | uint32 (optional) | 插件支持的接口的位掩码。如果返回错误则不存在。 |
| error | string (optional) | 如果插件无法启动，返回的错误消息。如果返回指标则不存在。 |

*示例：*

    {"id":2,"type":3,"metrics":["external.test", "External exporter Test."], "interfaces": 4}

或

    
{"id":2,"type":3,"error":"error message"}

[comment]: # ({/92946a86-802a684d})

[comment]: # ({f190dd1a-c0bcf831})


###### 启动请求

一个请求用于execute Runner接口的Start函数.

|     |     |
|---|---|
| direction | agent → plugin |
| response | no  |

该请求没有特定参数，仅包含[common data](#common-data)参数.

*示例:*

    
{"id":3,"type":4}

[comment]: # ({/f190dd1a-c0bcf831})

[comment]: # ({fce4bba2-9c1b2bdc})


###### 终止请求

由agent发送的用于关闭插件的请求.

|     |     |
|---|---|
| direction | agent → plugin |
| response | no  |

该请求没有特定参数，仅包含[common data](#common-data)参数.

*示例:*

    
{"id":3,"type":5}

[comment]: # ({/fce4bba2-9c1b2bdc})

[comment]: # ({43e9416d-c7292eea})


###### 导出请求

一个请求execute导出器接口的导出功能.

|     |     |
|---|---|
| direction | agent → plugin |
| response | no  |

export请求的特定参数:

| Name | Type | Comments |
|---------|--------|----------|
| key | string | 插件键值. |
| parameters | array of strings (optional) | 导出功能的参数. |

*示例:*

    
{"id":4,"type":6,"key":"test.key","parameters":["foo","bar"]}

[comment]: # ({/43e9416d-c7292eea})

[comment]: # ({33f976c2-4780d401})


###### 导出响应

导出器接口Export函数的响应结果。

|     |     |
|---|---|
| direction | plugin → agent |
| response | n/a |

export响应特有的参数：

| Name | Type | Comments |
|---------|--------|----------|
| value | string (optional) | Export函数的返回值。若返回错误则此字段不存在。 |
| error | string (optional) | Export函数执行失败时的错误信息。若返回值存在则此字段不存在。 |

*示例：*

    {"id":5,"type":7,"value":"response"}

或

    
{"id":5,"type":7,"error":"error message"}

[comment]: # ({/33f976c2-4780d401})

[comment]: # ({96eb71cf-a0e73519})


###### 配置请求

调用*Configurator*接口中*Configure*功能的execute请求.

|     |     |
|---|---|
| direction | agent → plugin |
| response | n/a |

*Configure*请求的专用参数:

| Name | Type | Comments |
|---------|--------|----------|
| global_options | JSON object | 包含全局agent配置选项的JSON object. |
| private_options | JSON object (optional) | 包含私有插件配置选项的JSON object(如果提供). |

*示例:*

    
{"id":6,"type":8,"global_options":{...},"private_options":{...}}

[comment]: # ({/96eb71cf-a0e73519})

[comment]: # ({99291487-38bbe293})


###### 验证请求

对execute *Validate* 函数的请求，该函数属于 *Configurator* 接口。

|     |     |
|---|---|
| direction | agent → 插件 |
| 响应 | 是 |

*验证*请求的特定参数:

| 名称 | 类型 | 备注 |
|---------|--------|----------|
| private_options | JSON object (optional) | 包含私有插件配置选项的JSON object（如提供）。 |

*示例:*

    
{"id":7,"type":9,"private_options":{...}}

[comment]: # ({/99291487-38bbe293})

[comment]: # ({3b19fa95-7c4cceea})


###### 验证响应

来自*Configurator*接口*Validate*函数的响应

|     |     |
|---|---|
| direction | plugin → agent |
| response | n/a |

*Validate*响应特有的参数:

| Name | Type | Comments |
|---------|--------|----------|
| error | string (optional) | 当Validate函数未成功执行时返回的错误信息。执行成功时该字段不存在。 |

*示例:*

    {"id":8,"type":10}

或

    
{"id":8,"type":10,"error":"error message"}

[comment]: # ({/3b19fa95-7c4cceea})