SEMP功能

本节提供了关于 SEMP API 架构中讨论的 SEMP v2 功能的更多详细信息：

select 查询参数允许您指定要在查询结果中包含或排除哪些数据字段.
where 查询参数允许您仅包含符合某些条件的结果.
您可以检索某些集合中的对象数量.
您可以检索队列、主题端点或重放日志中的消息数量.
不透明密码提供了一种机制，用于在响应中包含只写属性.
分页是将查询结果分成离散页面以限制返回数据大小的机制.

此外，一些操作不被支持：

SEMP API 不提供速率限制.我们建议您管理发送请求的频率.
不直接支持事务，但每个请求要么成功完成，要么完全不完成.
不支持对查询结果进行排序.

返回选定的数据字段

您可以使用 select 查询参数仅在响应中包含对象的指定属性，或从响应中排除对象的指定属性.使用此查询参数以限制每个返回对象的返回数据大小，仅返回所需的字段，或排除不需要的字段.

select 查询参数可以用于限制响应中返回的属性，但它不会强制返回否则不会返回的属性.

select

select 的值是属性名称的逗号分隔列表.名称可以包括 * 通配符（零个或更多字符）.支持使用点（例如，parentName.childName）的嵌套属性名称.问号字符 ?，通常用于匹配单个字符，不被支持.

属性名称采用以下形式：

<attribute-name>  = ["-"] <attribute-string> 0*n( "." <attribute-string> )     ; 属性名称，可能是嵌套的，可能以 "-" 开头

最多可以向 select 参数提供 256 个属性名称或模式.

如果列表中包含不以 " -" 开头的属性名称，则仅在响应中包含这些属性.如果列表中包含以 " -" 开头的属性名称，则这些属性将从响应中排除.

所有以 " -" 开头的属性名称必须在所有不以 " -" 开头的属性名称之后.此外，列表中的每个属性名称必须至少与对象中的一个属性匹配.

如果列表包含两种类型：

所有以 " -" 开头的属性名称必须在所有不以 " -" 开头的属性名称之后
第一组属性与第二组属性的差集将返回在响应中

如果列表为空（select=），则返回所有属性.

此外：

问题中的属性仅在返回的 data、collections 和 links 字段中，而不是在 meta 字段中.
嵌套使属性唯一.例如，select=-abc 不排除属性 example.abc.
包含或排除具有嵌套属性的属性将包含或排除所有嵌套属性.例如，select=example 包含 example.abc 和 example.xyz.
通配符匹配是在 <attribute-string> 中进行的，而不是在 <attribute-name> 中进行的.例如，select=*bc 不包括属性 example.abc，而 select=example.*bc 则包括.
select 参数在 where 参数之后应用.

以下是一些示例，其中 %2A 是 " *" 的百分比 URL 编码：

            ; 所有 MsgVpn 名称列表
/SEMP/v2/config/msgVpns?select=msgVpnName

; 所有 MsgVpns 及其属性列表，除了它们的名称
/SEMP/v2/config/msgVpns?select=-msgVpnName

; MsgVpn "finance" 的认证属性
/SEMP/v2/config/msgVpns/finance?select=authentication%2A

; MsgVpn "finance" 的所有属性，除了认证属性
/SEMP/v2/config/msgVpns/finance?select=-authentication%2A

; MsgVpn "finance" 的队列 "orderQ" 的访问相关属性
/SEMP/v2/config/msgVpns/finance/queues/orderQ?select=owner,permission

过滤

您可以使用 where 参数指定响应应仅包含满足某些条件的对象.当 GET 请求包含 where 查询参数时，事件代理仅返回其内容与所有给定表达式匹配的对象.

应用程序只能根据其给定 URI 将返回给它的字段进行过滤.例如，对 /SEMP/v2/config URI 基础路径的 GET 不能根据当前绑定的客户端数量过滤队列——当前客户端绑定计数不是队列的可配置属性，且在该 URI 基础路径中不可用.然而，它可以基于队列的配置 max-bind-count 进行过滤.

where

where 的值是表达式的逗号分隔列表.所有表达式都必须为真，对象才能包含在响应中.每个表达式采用以下形式：

<attribute-name> OP <value>

其中：

attribute-name 仅指返回的 data 字段中的属性，而不是 collections、links 或 meta 字段中的属性.不允许在 attribute-name 中使用通配符.即使它们是不透明的并且使用了 opaquePassword 查询参数，也不允许将只写属性与 where 参数一起使用.
OP 是 " =="、" !="、" <"、" >"、" <=" 或 " >=" 中的一个.
value 可以是数字、字符串、true 或 false，具体取决于 attribute-name 的类型.

此外：

" ==" 和 " !=" 操作符可用于执行字符串、数字或布尔值（true 或 false）比较.
" <"、" >"、" <=" 和 " >=" 操作符可用于执行字符串或数字比较.
当 value 是字符串时：
- value 可以包括 " *" 通配符，它可以匹配零个或更多字符.反斜杠字符 (" \") 可用于转义 " *" 通配符或另一个反斜杠." *" 通配符只能与 " ==" 和 " !=" 操作符一起使用.如果 " *" 用作其他操作符的字面量，则必须使用 " `"" 进行转义.
- value 限制为 266 个字符.
- " <"、" >"、" <=" 和 " >=" 操作符执行简单的字节对字节比较.
当 value 是数字时，它不能超过 int64 Swagger 格式类型的大小.
一次最多可以使用四个表达式.
where 参数在 select 参数之前应用.

以下是一些示例，其中 %3D、%21、%3E 和 %2A 分别是 " ="、" !"、" >" 和 " *" 的百分比 URL 编码：

; 仅启用的 MsgVpns (enabled==true)
/SEMP/v2/config/msgVpns?where=enabled%3D%3Dtrue

; 仅使用基本非 LDAP 认证的 MsgVpns (authenticationBasicEnabled==true,authenticationBasicType!=ldap)
/SEMP/v2/config/msgVpns?where=authenticationBasicEnabled%3D%3Dtrue,authenticationBasicType%21%3Dldap

; 仅允许超过 100 个客户端连接的 MsgVpns (maxConnectionCount>100)
/SEMP/v2/config/msgVpns?where=maxConnectionCount%3E100

; 仅以 "B" 开头的 MsgVpns (msgVpnName==B*)
/SEMP/v2/config/msgVpns?where=msgVpnName%3D%3DB%2A

检索集合中的对象数量

当您发出对支持的集合之一的 GET 请求时，总项目数将返回在 GET 响应的元数据中的 count 字段中.

当使用 GET 方法检索以下集合时支持计数：

/SEMP/v2/monitor/msgVpns/<name>/clients
- clients/*/rxFlows
- clients/*/transactedSessions
- clients/*/txFlows

对于 clients 的 rxFlows、transactedSessions 和 txFlows 集合，仅支持所有客户端的计数（即，星号是必需的）.在这种情况下，仅返回响应的元数据部分.

/SEMP/v2/monitor/msgVpns/<name>/queues
- queues/<name>/msgs
- queues/<name>/txFlows

对于 queues 集合和子集合，不允许使用星号.

/SEMP/v2/monitor/msgVpns/<name>/topicEndpoints
- topicEndpoints/<name>/msgs
- topicEndpoints/<name>/txFlows

对于 topicEndpoints 集合和子集合，不允许使用星号.

/SEMP/v2/monitor/msgVpns/<name>/transactions

对于 transactions 集合，不允许使用星号.

如果请求通过 where 查询参数进行过滤，则响应中不包括 count 字段.

例如，假设 finance Message VPN 有以下队列：

一个独占队列
一个非独占、非分区队列
一个具有四个分区的分区队列

您可以发出以下请求：

curl -X GET solace:solace 192.0.2.1:8080/SEMP/v2/monitor/msgVpns/finance/queues

代理的响应将包含 meta 部分中的 count 字段中的队列数量，如下所示.在这种情况下，Message VPN 中总共有七个队列（包括分区）.

...
{

...

    "meta": {
        "count": 7,
        "request": {
            "method": "GET",
            "uri": "http://192.0.2.1:8080/SEMP/v2/monitor/msgVpns/finance/queues"
        },
        "responseCode": 200
    }
}

从端点或重放日志检索消息计数

对于支持的集合，除了集合中的对象数量外，还返回包含的消息数量.以下集合支持消息计数：

/SEMP/v2/monitor/msgVpns/<name>/queues
/SEMP/v2/monitor/msgVpns/<name>/topicEndpoints
/SEMP/v2/monitor/msgVpns/<name>/replaylogs

消息是子集合——当您发出对支持的集合之一的 GET 请求时，消息的数量（或计数）已包含在响应的 collections 字段中.

例如，要检索 "Sales" Message VPN 中每个队列的总消息数量，您可以发出以下请求：

curl -u "solace:solace" "192.0.2.1:8080/SEMP/v2/monitor/msgVpns/Sales/queues?count=100&select=queueName,msgs.count"

代理的响应的 collections 部分为每个队列包括一个 msgs.count 字段，显示该队列中的消息数量.在这种情况下，有两个队列——一个队列包含 50 条消息，另一个队列包含 75 条消息.如果还有更多队列（最多 100 个），此响应也会捕获它们，因为请求将页面大小增加到 100（最大支持值）.

{
    "collections":[
        {
            "msgs":{
                "count":50
            }
        },
        {
            "msgs":{
                "count":75
            }
        }
    ],
    "data":[
        {
            "queueName":"q1"
        },
        {
            "queueName":"q2"
        }
    ],
    "links":[
        {},
        {}
    ],
    "meta":{
        "count":2,
        "request":{
            "method":"GET",
            "uri":"http://192.0.2.1:8080/SEMP/v2/monitor/msgVpns/Sales/queues?count=100&select=queueName,msgs.count"
        },
        "responseCode":200
    }
}

由于队列名称返回在 data 部分，消息计数返回在 collections 部分，您必须使用 data 部分中队列的索引来确定 collections 部分中相应的消息计数.在前面的示例中，您可以确定 q1 有 50 条消息，因为 q1 是 data 部分中第一个 queueName 字段的值，而 50 是 collections 部分中第一个 msgs.count 字段的值.

当轮询对象（特别是队列）时，使用 select 子句限制请求内容仅为您需要的内容非常重要.例如，如果您只想获取每个队列中的消息数量，您应该使用 select=queueName,msgs.count.这样做可以大大减少代理处理请求所需的时间，并减少干扰其他代理服务性能的可能性.

不透明密码

具有不透明属性的属性也是只写的，因此通常不能在 GET 中检索.然而，当在 opaquePassword 查询参数中提供密码时，具有不透明属性的属性将以不透明形式在 GET 中检索，使用此密码进行加密.该查询参数也可以用于 POST、PATCH 或 PUT，以使用在 GET 中检索到的不透明属性值设置不透明属性，只要：

提供了用于检索不透明属性值的相同密码；以及
发送请求的代理与生成不透明属性值的代理具有相同的主版本和次版本 SEMP 版本.

查询参数中提供的密码必须至少为 8 个字符，最多为 128 个字符.

该查询参数只能在配置 API 中使用，由具有全局/管理员访问级别的用户使用，并且仅通过 HTTPS 使用.

分页

当检索集合时，GET 方法支持分页.集合可能包含数百、数千甚至数百万个项目.因此，这些请求必须分页才能进行管理.分页由两个查询参数控制，其使用方法如下所述.

参数	含义
count=`<number>`	在响应中最多包含这么多对象.
cursor=`<opaque value>`	分页 GET 请求中的当前位置.

count

限制响应中的对象数量.

这可以用于限制大型集合的响应大小. count 的最小值为 1，默认值为 10.还有一个每个集合的最大值以限制请求处理时间.每个集合的实际 count 上限可能不同，并且请求的 count 大于此上限将被限制在实际上限.由于没有保证应用程序可以通过单个 GET 请求请求集合中的所有项目的可靠方式，因此应用程序应始终编写为处理分页.

最大页面大小因集合而异，并且会随着版本的变化而变化.使用大页面大小可能导致您的请求需要很长时间.

count 参数不保证将返回最少数量的对象.页面可能包含少于 count 个对象，甚至为空.尽管如此，后续页面上可能仍有其他对象可供检索.

例如：

; 最多 25 个 MsgVpns
/SEMP/v2/config/msgVpns?count=25

cursor

下一页对象的位置或光标.

通过 cursor 查询参数控制检索后续页面.此参数为事件代理提供了足够的上下文以检索集合中的下一组对象.

当请求集合并且可能有额外的对象可供检索但未包含在初始响应中时，响应包括一个 paging 字段，其中包含两个子字段：

nextPageUri 提供与刚刚处理的请求等效的 URI，但 cursor 和 count 查询参数已填写，以从集合中 GET 下一组对象.
cursorQuery 字符串仅提供在下一个请求中使用的 cursor 值.这对于使用生成的 SDK 库构建的客户端很有用，这些客户端不直接操作 URI.

应用程序必须继续使用 cursorQuery（如果提供）以检索与请求关联的完整对象集，即使页面包含的对象少于请求的数量（参见 count 查询参数文档）或为空.

光标是不应由 SEMP 客户端创建或解释的不透明数据，只能按描述使用.

响应中缺少 paging 字段表示已返回完整集合或已检索到集合的最后一页.

在 SEMP 中，检索集合时，可能会在分页响应中收到部分填充或甚至为空的页面.这在使用对象过滤时尤其常见.处理分页的应用程序应继续检索下一页，直到响应中缺少 paging 字段以确认已检索到完整响应.

速率限制

目前，SEMP 不强制执行速率限制.建议用户避免频繁轮询事件代理.一般来说，发送到事件代理的 SEMP 请求的平均数量应少于 10 个请求/秒.

事务

SEMP 不支持事务，因为无法将多个 SEMP 请求组合在一起并保证它们作为一个完整单元的成功或失败.

然而，任何单个 SEMP POST、PUT 或 PATCH 请求将成功完成或完全不完成.例如，对队列进行 PATCH，更改三个属性，其中对第三个属性的更改失败，将使队列没有前两个属性的更改；所有三个更改必须成功，否则对象将保持其原始状态.然而，这种支持仍然不是事务性的，因为事件代理在处理单个请求的中途重启可能会导致请求仅部分满足.通过 Solace CLI 或传统 SEMP 用户对 Solace 对象的并发修改是请求失败并使请求部分满足的另一种方式.SEMP v2 用户应避免通过 Solace CLI 或传统 SEMP 用户对对象进行并发修改.

任何返回多个对象的单个 SEMP GET 请求都保证成功完成或完全不完成.例如，在执行 GET 集合时，如果在处理 GET 时发生故障，则不会返回部分集合结果.同样，对单个对象的 GET 返回该对象的全部状态或无状态.

排序

不支持对查询响应进行排序.

返回选定的数据字段​

select​

过滤​

where​

检索集合中的对象数量​

从端点或重放日志检索消息计数​

不透明密码​

分页​

count​

cursor​

速率限制​

事务​

排序​