SEMP API架构
SEMP v2 由三个独立的 API 组成，每个 API 都有不同的目的.
| API | 基础路径 | 目的 |
|---|---|---|
| 配置 | /SEMP/v2/config | 读取和写入配置状态. |
| 监控 | /SEMP/v2/monitor | 查询管理和操作状态. |
| 操作 | /SEMP/v2/action | 执行操作. |
以下部分更详细地描述了 SEMP API 的结构.这些部分包括：
- 预留字符
- SEMP 资源
- 查询参数
- 集合计数
- HTTP 方法
- HTTP 响应代码
- HTTP 内容
预留字符
以下被视为 SEMPv2 URL 中的“数据”：
-
资源的标识属性；以及
-
查询参数的值.
当 URL 的这些数据部分包含 RFC 3986 “未预留” 字符集（A-Z, a-z, 0-9, -, _, ., 和 ~）之外的字符时，则必须对这些字符进行百分比编码.
然而，当逗号用作具有多个标识属性的资源的分隔符或具有多个值的查询参数的分隔符时，它们不能被百分比编码.
SEMP资源
SEMP v2 使用 URI 来定位 PubSub+ 事件代理的可管理 资源.资源是个体对象、对象集合或（仅在操作 API 中）操作.
资源始终是名词，个体对象是单数，集合是复数.集合中的对象通过对象 ID（obj-id）进行标识，该对象 ID 以 collection-name/obj-id 的形式跟随在集合名称之后.一个 obj-id 由一个或多个标识属性组成，用逗号分隔.出现在标识属性本身中的逗号必须进行百分比编码.
对象由属性、操作、集合和其他对象组成，这些对象又以 JSON 对象的形式作为名称/值对进行描述.对象的集合和操作不直接包含在对象的 JSON 内容中；相反，内容包括一个包含指向集合和操作的 URI 的属性.必须通过此 URI 管理这些包含的资源.
至少，每个对象都有一个 uri 属性，其中包含指向自身的 URI.集合中的对象至少有一个标识属性.这些属性可以具有属性——请参阅下面的属性属性以了解详细信息.
集合是无序的对象列表（除非另有说明），并由 JSON 数组描述.数组中的每个项目以与单个对象通常表示方式相同的方式表示一个对象.
对象中的操作通过 action-id 进行标识，该 action-id 以 obj-id/action-id 的形式跟随在对象名称之后.
操作也由属性组成，并以 JSON 对象的形式作为名称/值对进行描述.然而，与对象不同，它们不是集合的成员，不能被检索，只能被执行.操作仅存在于操作 API 中.
以下是一些示例：
/SEMP/v2/config/msgVpns ; MsgVpn 集合
/SEMP/v2/config/msgVpns/a ; 名为 "a" 的 MsgVpn 对象
/SEMP/v2/config/msgVpns/a/queues ; MsgVpn "a" 中的 Queue 集合
/SEMP/v2/config/msgVpns/a/queues/b ; MsgVpn "a" 中名为 "b" 的 Queue 对象
/SEMP/v2/config/msgVpns/a/bridges ; MsgVpn "a" 中的 Bridge 集合
/SEMP/v2/config/msgVpns/a/bridges/b,auto ; MsgVpn "a" 中名为 "b" 且虚拟路由器为 "auto" 的 Bridge 对象
/SEMP/v2/action/msgVpns/a/queues/b/startReplay ; 在 MsgVpn "a" 中的 Queue "b" 上启动重放的操作
/SEMP/v2/monitor/msgVpns/a/clients ; MsgVpn "a" 中的 Client 集合
/SEMP/v2/monitor/msgVpns/a/clients/c ; MsgVpn "a" 中名为 "c" 的 Client 对象
这些示例展示了资源对象 ID 由单个部分组成（通常是名称）的情况.事件代理中的一些对象由多个字符串唯一标识，在这种情况下，您将使用 ","（逗号）字符将字符串连接在一起以形成对象的 ID.例如：
/SEMP/v2/config/msgVpns/finance/bridges/ny-to-ldn,primary
在上面的示例中，在 finance Message VPN 中有一个 Bridge 集合，其中一个名为 ny-to-ldn，属于 primary 虚拟路由器.
作为一般规则，SEMP API 中的资源路径是可组合的.也就是说，客户端应用程序可以通过遵循众所周知的模式自行构建 URI.特别是，SEMP 不使用混淆或生成的 UUID 或任何其他为每个资源生成唯一 URI 的方案.SEMP API 参考显示了每个事件代理配置资源的资源 URI.
属性属性
对象或操作中的属性可能具有以下属性的任何组合：
| 属性 | 含义 |
|---|---|
| 标识 | 属性参与对象的唯一标识，并出现在其 URI 中. |
| 常量 | 属性值只能在对象创建时选择. |
| 必需 | 请求中必须提供属性. |
| 只读 | 属性值不能更改.只读属性可能出现在 POST 和 PUT/PATCH 请求中.然而，如果只读属性未被 标记为标识，则将被忽略. |
| 只写 | 属性只能写入，不能读取.此属性不会在 GET 请求中返回. |
即使它们是只写的，也可以在存在 opaquePassword 查询参数时以不透明形式检索不透明属性. | |
| 需要禁用 | 当对象（或对象的相关部分）处于启用状态时，不能更改属性. |
| 自动禁用 | 修改此属性时，如果对象（或对象的相关部分）处于启用状态，事件代理将暂时禁用一个或多个属性以应用更改. |
| 此操作可能会对服务产生影响. | |
| 弃用 | 属性已弃用，可能会在后续 SEMP 版本中被消除. |
| 不透明 | 当存在 opaquePassword 查询参数时，属性可以以不透明形式设置或检索.请参阅不透明密码以了解详细信息. |
在某些请求中，某些属性可能只能与其他属性的某些组合一起提供：
| 关系 | 含义 |
|---|---|
| 需要 | 如果请求中提供了特定属性或属性组合，则请求可以更改属性。 |
当满足以下所有条件时，不会对属性强制执行 requires 属性： |
- 属性不是只写的；
- 提供的属性值与其当前值（或在对象创建时为其默认值）相同；以及
- 属性需要一个只写属性。
此外，即使仅满足条件（a）和（b），也可能不强制执行requires属性。| | 冲突| 如果请求中未提供特定属性或属性组合，则请求可以提供属性.|
在监控 API 中，任何非标识属性可能不会在 GET 中返回.
SEMP API 参考为每个资源识别所有属性属性，以便清楚地了解对象的哪些属性具有分配的属性.
HTTP方法
POST、PUT、PATCH、DELETE 和 GET HTTP 方法根据以下一般原则操纵资源.请注意，某些方法仅在某些 API 中使用：
| 方法 | 资源 | 描述 | 请求体 | 响应体 | 说明 |
|---|---|---|---|---|---|
| POST | 集合 | 创建新对象 | 初始属性值 | 对象属性和元数据 | 缺失的属性将设置为默认值.如果对象已存在，则事件代理返回 400 错误. |
| PUT | 对象 | 更新现有对象 | 新属性值 | 对象属性和元数据 | 如果对象不存在，则事件代理会创建它.缺失的属性将设置为默认值，除非 SEMP 用户没有权限修改属性.在这种情况下，其值将保持不变而不是设置为默认值. |
此外，在 PUT 时，只写属性的值不会设置为其默认值，除非满足以下两种情况之一：与另一个非只写属性存在相互需要关系，两个属性都未包含在请求中，且非只写属性当前未设置为其默认值；或属性也是不透明的，并且请求中提供了 opaquePassword 查询参数. | |||||
| PUT | 操作 | 执行操作 | 操作参数 | 操作元数据 | |
| PATCH | 对象 | 更新现有对象 | 新属性值 | 对象属性和元数据 | 缺失的属性保持不变.如果对象不存在，则事件代理返回 400 错误. |
| DELETE | 对象 | 销毁现有对象 | 空 | 对象元数据 | 如果对象不存在，则事件代理返回 400 错误. |
| GET | 对象 | 检索对象 | 空 | 对象属性和元数据 | 如果对象不存在，则事件代理返回 400 错误. |
| GET | 集合 | 检索对象集合 | 空 | 对象属性和集合元数据 | 如果集合为空，则事件代理返回带有 200 代码的空集合. |
方法覆盖
如果您使用的客户端不支持所有 HTTP 方法，或者您通过限制 HTTP 方法的代理传递请求，则可以通过使用 POST 并将 X-Http-Method-Override 头设置为所需方法来覆盖 HTTP 方法.例如，要执行 PATCH 请求，请执行带有 X-Http-Method-Override: PATCH 头的 POST.
查询参数
查询参数与所有 HTTP 方法一起用于各种目的.
可以在单个 URI 中一起使用多个查询参数，用 & 符号分隔.例如：
; 使用两个假设查询参数 "q1" 和 "q2" 及其值 "val1" 和 "val2" 请求 MsgVpns 集合
/SEMP/v2/config/msgVpns?q1=val1&q2=val2
API 参考列出了每个端点的查询参数.
常用查询参数
有一些查询参数在许多 URI 中是常见的，因为它们允许对查询结果进行高级操作，如过滤和分页.这些参数在下表中列出.
| 参数 | 含义 | 适用于 | 详细信息，请参阅... |
|---|---|---|---|
| 对象 | 集合 | ||
| --- | --- | --- | --- |
| select= list-of-attrs | 在响应中包含或排除指定的数据属性. |  | |
| where= list-of-exprs | 如果所有列出的表达式为真，则在响应中包含对象. | ||
| cursor= opaque-value | 分页 GET 请求中的当前位置. | ||
| count= number | 响应中最多包含这么多对象. | ||
| opaquePassword= password | 提供了一种机制来在响应中返回只写属性. |
集合计数
仅支持某些集合的计数.有关详细信息，请参阅检索集合中的对象数量.
HTTP响应代码
API 在每个响应中返回一个 HTTP 响应代码.这些代 码代表三类响应：成功（2xx）、客户端错误（4xx）和服务器错误（5xx）.
| 代码 | 状态 | 含义 |
|---|---|---|
| 200 | OK | 请求成功. |
| 204 | 无内容 | 事件代理成功处理了请求，并且不返回任何内容. |
| 400 | 错误请求 | 请求有问题.例如，存在拼写错误或请求的对象找不到. |
| 401 | 未授权 | 客户端身份验证有问题.例如，密码不正确或用户不存在. |
| 403 | 禁止 | 请求包含有效数据且被事件代理理解，但拒绝执行操作. |
| 404 | 未找到 | 请求的资源找不到，但将来可能可用. |
| 414 | URI 太长 | 提供的 URI 太长，事件代理无法处理. |
| 500 | 内部服务器错误 | 事件代理出现问题. |
| 502 | 错误网关 | 事件代理作为网关或代理时从上游服务器收到无效响应. |
| 503 | 服务不可用 | 事件代理无法处理请求（因为它过载或正在维护）. |
| 504 | 网关超时 | 事件代理作为网关或代理时未及时从上游服务器收到响应. |
| 529 | 无 SEMP 会话可用 | 事件代理无法创建请求的会话，因为连接的 SEMP 客户端或 Broker Manager 用户太多. |
500 级错误表明事件代理存在问题，如系统过载，导致请求无法成功完成.另一方面，400 级错误可能是客户端可以纠正并重试的问题.在 API 身份验证失败时返回 401 错误，以与使用此 HTTP 响应代码提示客户端进行身份验证的一些应用程序（如 Web 浏览器）兼容.
在错误的情况下，HTTP 响应正文包含有关错误性质的更详细信息，并包含有关请求的附加信息.这在 SEMP 错误处理中有描 述.
HTTP内容
SEMP 使用 JSON 对请求和响应的有效载荷进行编码.
您可以包含一个 Content-Encoding 头，其值为 gzip 以压缩请求.同样，指定一个 Accept-Encoding 头为 gzip 以请求事件代理压缩其响应.
对于带有正文的请求，需要一个 Content-Type 头值为 application/json.
请求和响应的格式取决于 URI，并在 SEMP API 参考中完全记录.
对象有效载荷的一个目标是实现获取、更新、修改的使用模式（即您 GET 一个对象，对其进行一些更改，然后 PUT 该对象以保存更改）.SEMP 在设计时就考虑了这种类型的使用，例如：
- API 在 GET、POST、PUT 和 PATCH 方法之间协调对象的格式.
- PUT 和 PATCH 方法忽略 HTTP 内容对象中的非标识只读属性.
- GET 返回的对象模式包含写入属性，如
password，因为它们用于创建对象.然而，这些属性在实际响应中是缺失的.
目前，SEMP 仅支持 HTTP 内容的 UTF-8 编码.
响应锚点
所有 SEMP 请求都有非空响应.所有响应分为两部分：数据（请求的内容）和元数据（关于响应的信息）.如果相应的请求包含允许压缩的 Accept-Encoding 头，则事件代理会适当地压缩响应正文.
SEMP 响应的基本 JSON 结构如下：
{
"collections": [
{
"<collection-name>": {
"count": <number>
},
"<collection-name>": {
"count": <number>
}
}
],
"data": {
// 数据属性
},
"links": {
// 指向 XXXX 的链接
},
"meta": {
"count": <number>,
"error": {
"code": <number>,
"description": <string>,
"status": <string>
},
"paging": {
"cursorQuery": <string>
"nextPageUri": <string>
},
"request": {
"method": <string>,
"uri": <string>
},
"responseCode": <number>
}
}
集合字段锚点
如果对支持的集合执行 GET，则其子集合中的对象数量将返回在 collections 部分.有关详细信息，请参阅从端点或重放日志检索消息计数.
数据字段锚点
data 字段是可选的.如果存在，其值是 JSON 对象或数组.此字段返回的内容取决于 URI.
链接字段锚点
links 字段是可选的.如上所述，在 SEMP 资源中，对象由属性、操作、集合和其他对象组成.如果响应中存在，则 links 字段包含指向集合和操作的 URI 列表.您必须使用这些 URI 来管理包含的资源.
元数据字段锚点
meta 字段是必需的.其值是 JSON 对象，并且在所有 URI 中具有共同的定义.下表总结了 meta 字段中的信息.
| 字段 | 子字段 | 描述 | 可选？ |
|---|---|---|---|
count | 请求的对象总数，无论页面大小如何.这可能是集合中所有对象的计数或过滤后的子集.它代表一个时间点的快照，并且在分页时可能会发生变化. | 是 | |
responseCode | HTTP 响应代码，是 200（成功）、4xx（客户端错误）或 5xx（服务器错误）之一. | 否 | |
request | method | 导致此响应的请求的 HTTP 方法. | 否 |
uri | 导致此响应的请求的 URI.该 URI 可能已规范化. | ||
error | code | 唯一标识发生的错误的错误代码. | 是–仅在错误时提供. |
description | 问题的详细描述. | ||
status | 与 code 相关的简洁状态字符串. | ||
paging | cursorQuery | 下一页对象的光标或位置.将其用作下一个请求的 cursor 查询参数. | 是–仅在集合中有更多页面时提供. |
nextPageUri | 下一页对象的 URI.字段 cursorQuery 已嵌入此 URI 中. |