8809x

001738

Dipl.-Ing. Thomas Günthel

2025-06-09

VBA 中的 WebService API 教程

Webservice 是机器或程序之间的一种通信。由于这种通信是通过网络提供的，因此任何可以通过 HTTP 协议发送和接收字符串的程序都可以使用。RFEM 6 和 RSTAB 9 提供了一个基于这些跨平台 Webservices 的接口。本教程将通过 VBA 编程语言展示基础知识。

VBA 示例中的 Webservice API 基础

对于字符串格式化，使用 XML 格式并依据 SOAP 协议规范。下面的查询作为示例：



    <Body>
        
    </Body>

XML 格式化的一个典型元素是以 "<" 开头一个部分，然后是一个标识符，如果没有其他子元素，则用 "/>" 结束该部分。第三行示例：

当有子元素时，以 "<"、命令和 ">" 开始，并以 "</"、命令和 ">" 结束。适当的示例是 "Body" 部分：


<Body>
    
</Body>

使用空格和换行仅用于说明，传输时不需要。元素 "Body" 和 "Envelope" 是传输的标准元素，并用于每个命令。

所有可用命令可以通过 WSDL 接口读取。有软件可以借此生成列表，例如 SoapUI。RFEM 6 的 API 有两个命令列表，一个用于应用程序，一个用于模型。两者都可以在本文末尾下载。

由于命令通过 HTTP 发送，因此需要 URL 地址。RSTAB/RFEM 应用程序的默认地址是 "localhost:8081"，可以在程序设置中更改。

公司地址

打开的模型获取递增的地址，因此第一个打开的模型地址为 "localhost:8082"。

首次打开的模型

为了获得活动模型的地址，发送命令 "get_active_model"。RFEM 6 的相应回复如下：




    
        
            
                http://127.0.0.1:8082/

"Envelope" 部分的附加细节（德语：Umschlag/Briefumschlag，信封）以及前面的行 "<?xml version="1.0"?>" 用于展示采用的标准，此处不再深入讨论。无论如何可以看出，仍然使用了元素 "Envelope" 和 "Body"。在 "Body" 内部，RFEM 6 回应 "get_active_model" 命令，并附加单词 "Response"。此响应内容是一个值（"value"），即活动模型的地址。此外，RFEM 现在对进一步的访问被锁定。

在下面的示例中，将创建一个带有两个节点支撑和一负载的杆件。为了通过 VBA 与 RFEM 通信，需要以下对象：


request As MSXML2.XMLHTTP60
response As MSXML2.DOMDocument

对象 XMLHTTP60 具有一个用于发送 HTTP 请求至 URL 的集成功能，因此用于请求。然后可以通过 DOMDocuments 评估响应。以下示例结合了之前展示的 "get_active_model" 请求与在 VBA 中使用的命令：


'   get active model url with "get_active_model" command
str_envelope = 
    "" & _
    "   <Body>" & _
    "       " & _
    "   </Body>" & _
    ""

'   open request and send it
request.Open "Post", "http://localhost:8081/", False
request.Send (str_envelope)

'   get response and transform it to an xml-object
response.LoadXML (request.responseText)

首先，请求通过 XML 格式在变量 "str_envelope" 中存储，并通过变量 "request" 的 "Open" 方法打开请求至 RFEM。通过 "Send" 方法，现在可以发送 "str_envelope" 的内容。然后可以通过 "ResponseText" 方法检索响应。具体情形中，它通过 "LoadXML" 方法直接在变量 "response" 中读取。

类型 DOMDocuments 的变量 "response" 具有方法 LoadXML，能够识别 XML 格式化。优势在于类型 DOMDocuments 还提供 GetElementsByTagName 方法。这允许从代码中直接提取元素。接下来，将扩展之前的代码，以便提供模型的 URL 地址：


'   get http-status
status = request.status
If status <> "200" Then
    MsgBox "get_active_model: Sending not successful - " & response.Text
    Exit Sub
End If

url_model = response.GetElementsByTagName("value")(0).Text

在读取 URL 之前，可以检查响应的状态。这是标准化 HTTP 状态码。状态 "200" 表示传输 "OK"。经此查询，字符串 url_model 中将存储模型的 URL。为此，从 XML 响应中查找元素 "value"。如果回答包含多个元素，将所有值放在 "value" 部分中，因此不能通过标识符 "value" 评估，而是要指向 "value" 的子元素。详情参见实用例子。就模型地址而言，唯一返回的值是 URL，因此 "value" 在这里成功。

VBA 中的实际示例

由于现在已知所有基本元素，接下来是一个简单示例。将在两个支撑上生成一个托梁，可以在其上施加杆载荷。

杆件荷载作用下在两根柱子上生成的梁

首先定义并初始化已经介绍的变量：


'    define variables
Dim request As MSXML2.XMLHTTP60
Dim response As MSXML2.DOMDocument60

Dim str_envelope As String
Dim url_app As String
Dim url_model As String

'   init variables
Set request = New MSXML2.XMLHTTP60

Set response = New MSXML2.DOMDocument60
With response
    .async = False
    .preserveWhiteSpace = False
    .validateOnParse = False
    .resolveExternals = False
    '   Use full XPath functionality
    .SetProperty "SelectionLanguage", "XPath"
    '   Add specific Namespaces to work with Paths
    .SetProperty "SelectionNamespaces", "xmlns:soap=""http://www.w3.org/2003/05/soap-envelope"" " & _
                    "xmlns:xsd=""http://www.dlubal.com/rfem.xsd"" " & _
                    "xmlns:n1=""urn:schemas-microsoft-com:rowset"" " & _
                    "xmlns=""http://www.dlubal.com/rfem.xsd"" "
End With

url_app = "http://localhost:8081/"

除了 "request" 和 "response" 变量，还创建了用于请求的字符串 "str_envelope" 和用于应用程序和模型地址的 "url_app" 和 "url_model"。初始化时可以使用熟知的 SOAP 协议规范以评估响应的 XML 格式化。模型地址稍后获取，但需提供应用程序的地址。如先前所述，应提供默认地址：

公司地址

接下来的步骤中，应测试对应用程序的连接。通过命令 "get_information" 以获取应用程序的标准信息以进行此测试：


'   check application url with command "get_information"
str_envelope = "" & _
                "   " & _
                ""

'   open request and send it
request.Open "Post", url_app, False
request.Send (str_envelope)

'   get response and transform it to an xml-object
response.LoadXML (request.responseText)

'   get http-status
status = request.Status
If status <> "200" Then
    MsgBox "get_information: Sending not successful - " & response.Text
    Exit Sub
End If

'   read application information
Dim str1 As String
str1 = ""
str1 = str1 & response.GetElementsByTagName("name")(0).Text & vbLf
str1 = str1 & response.GetElementsByTagName("type")(0).Text & vbLf
str1 = str1 & response.GetElementsByTagName("version")(0).Text & vbLf
str1 = str1 & response.GetElementsByTagName("language_name")(0).Text & vbLf
str1 = str1 & response.GetElementsByTagName("language_id")(0).Text

MsgBox str1, vbInformation, "Response to ""get_information"" request"

如在第一部分所述，首先准备 XML 格式化的请求并存储在 "str_envelope" 中。"request.Open" 打开至应用程序的连接。关键词 "Post" 代表发送请求。第三参数为 "true"，因此进行同步传输。随后 "request.Send" 发送准备好的字符串。

传输后，响应存储在 "response" 中，并通过 "request.Status" 检查请求是否成功。状态由 RFEM 提供，因此当请求错误，例如未知命令，返回错误。如果状态不是 "200"，程序中断并在窗口（MsgBox）中输出错误。

如果没有错误，现可通过 "GetElementsByTagName" 读取各种传输的信息。具体例中，信息随后在窗口中显示。

随后的元素有很大相似性，因此只讨论特点（完整源码可下载）。要构建一个带两个支撑的托梁并施加杆载荷，需要以下功能：

节点 - set_node
线 - set_line
材料 - set_material
截面 - set_section
杆件 - set_member
节点支撑 - set_nodal_support
计算参数 - set_static_analysis_settings
载荷工况 - set_load_case
杆载荷 - set_member_load

函数 "set_node" 像大多数其他函数一样，有众多参数，但通常不需要。在 RFEM 模型的命令列表中可以查看参数的多样性。至关重要的是那些没有标记为“可选”的参数，因为这些必须填写。在例子中，传递以下参数：


begin_modification (url_model)

'   set node 1 on [0,0,0] with "set_node" command
str_envelope =
    "" & _
        "<Body>" & _
            "" & _
                "" & _
                    "1" & _
                    "TYPE_STANDARD" & _
                    "0" & _
                    "0" & _
                    "0" & _
                "" & _
            "" & _
        "</Body>>" & _
    ""

在此只有节点号是非可选的，其他参数可分配。在命令列表中除了可能的参数还有类型的列举。此例中目前有五种类型可用。选择了标准类型 "TYPE_STANDARD"。此处展示的第一个节点创建在 (0;0;0)，第二个节点在 (5,5;0;0)。小数点值显示如下：


…
"" & _
        "2" & _
        "TYPE_STANDARD" & _
        "5.5" & _
        "0" & _
        "0" & _
    "" & _
…

另一个特点是列表。线需要两个节点，其编号以列表形式传递。列表中的元素，如此处的 "definition_nodes"，以空格分隔：


…
    "" & _
        "" & _
            "1" & _
            "TYPE_POLYLINE" & _
            "1 2" & _
        "" & _
    "" & _
…

为了创建杆件，还必须创建一个截面，再为其提供一个材料。截面和材料可以从内部数据库中使用。因此仅提供已知标识符即可。材料的标识符是 "S235"，截面名为 "IPE 300"：


…
    "" & _
        "" & _
            "1" & _
            "1" & _
            "TYPE_STANDARDIZED_STEEL" & _
            "IPE 300" & _
        "" & _
    "" & _
…

为了验证诸如 "IPE 300" 之类的名称是否合法，可以使用图形界面中的输入。

在图形用户界面中检查名称是否有效

输入杆件本身无需其他知识，但输入固定支撑则需定义“无限”弹性常量。为传递使用关键词 "INF"：


…
    "" & _
        "" & _
            "1" & _
            "1" & _
            "INF" & _
            "INF" & _
            "INF" & _
            "INF" & _
            "0" & _
            "INF" & _
        "" & _
    "" & _
…

建立荷载工况和计算参数不需额外知识。最后一点特点是在创建荷载时有一个附加值，需要在 "" 部分之外给出。在杆载荷的情形中，相关的荷载工况需在该处传递：


…
    "" & _
        "1" & _
        "" & _
            "1" & _
            "LOAD_TYPE_FORCE" & _
            "1" & _
            "LOAD_DISTRIBUTION_UNIFORM" & _
            "LOAD_DIRECTION_GLOBAL_Z_OR_USER_DEFINED_W_TRUE" & _
            "1000" & _
        "" & _
    "" & _
…

补充说明，"value" 部分内元素顺序无关，外部则相关。指定的荷载工况因此必须站在 "value" 部分之前。除了现有数据创建和读取的功能，还有两个特别的功能被介绍。当程序收到元素时，程序自动进入 "Modification" 模式，即编辑模式。程序检查新元素并进行处理。如果要创建多个新元素，程序在这段时间应保持在编辑模式下，以便于更快地完成处理。为此提供了 "begin_modification" 和 "finish_modification" 函数。在示例中，因此在创建第一个节点前调用 "begin_modification"，结束后在创建荷载工况之后调用 "finish_modification"。这两个函数在程序中也以 VBA 函数形式设置。函数独立，因此在函数中重新设置了 "request" 和 "response" 变量。但不再需要新元素，因此这里不再进一步扩展。比较有无使用这些函数的情况，总是会带来速度上的差异。 == 总结 == Webservice-API 是 RFEM 和 RSTAB 的一个强大工具。简单的基于 HTTP 的传输使得接口可以实现于多种编程语言中，不仅仅是这里展示的 VBA，从而允许跨平台编程。