O serviço web é uma comunicação entre máquinas e programas. Esta comunicação é fornecida através da rede e pode, portanto, ser utilizada por qualquer programa que permita enviar e receber strings através do protocolo HTTP. O RFEM 6 e o RSTAB 9 disponibilizam uma interface baseada nestes serviços web multiplataforma. Este tutorial mostra as noções básicas utilizando a linguagem de programação VBA.
Noções básicas dos serviços web e API utilizando um exemplo de VBA
Para a formatação da string, é utilizado o formato XML de acordo com as especificações do protocolo SOAP. A seguinte consulta serve de exemplo:
código.vba#
http://schemas.xmlsoap.org/soap/envelope/">
#/code#
Um elemento típico da formatação XML é o início de uma secção com o carácter "<". Segue-se um identificador e, se não estiverem presentes outros subelementos, a secção é fechada com "/>". Um exemplo é a terceira linha:
código.vba#
http://www.dlubal.com/rfem.xsd"/>
#/code#
Se existem sub-elementos, começa com "<", o comando e ">" e termina com "". Um exemplo apropriado é a secção "Corpo":
código.vba#
#/code#
A formatação com espaços e quebras de linha é utilizada aqui apenas para fins ilustrativos. Isto não é necessário para a transferência. Os elementos "Corpo" e "Envolvente" são elementos padrão para a transferência e são utilizados para cada comando.
Todos os comandos disponíveis podem ser lidos através da interface WSDL. Está disponível o software que permite criar listas. Um exemplo para tal software é o SoapUI. Existem duas listas para a API do RFEM 6; os comandos para a aplicação e os comandos para o modelo. Ambas as listas podem ser descarregadas no final deste artigo.
Uma vez que os comandos são enviados através de HTTP, são necessários endereços URL para o encastramento. O endereço predefinido das aplicações RSTAB/RFEM é "http://localhost:8081/" e pode ser alterado nas configurações do programa. Para os modelos abertos, são atribuídos endereços por ordem crescente, de modo que o primeiro modelo aberto tem o endereço "http://localhost:8082/". Para obter o endereço do modelo ativo, é enviado o comando "get_active_model". Uma resposta correspondente do RFEM 6 é assim:
#código.vba#
http://127.0.0.1:8082/
#/code#
Os detalhes adicionais da secção "Envolvente" bem como a linha anterior "" deveria mostrar primeiro as normas utilizadas e não será mais discutida aqui. De qualquer forma, é possível observar que os elementos "Envolvente" e "Corpo" são novamente utilizados. A resposta do RFEM 6 está contida no "Corpo" pelo nome de comando "get_active_model" e a palavra anexada "Resposta". O conteúdo desta resposta é um "valor", nomeadamente o endereço do modelo ativo. Além disso, o RFEM está agora bloqueado para acesso posterior.
No exemplo a seguir, queremos criar uma barra com dois apoios nodais e uma carga. Para poder comunicar com o RFEM através de VBA, são necessários os seguintes objetos:
#código.vba#
solicitar como MSXML2.XMLHTTP60
Resposta As MSXML2.DOMDocument
#/code#
O objeto XMLHTTP60 tem uma função integrada para enviar um pedido HTTP para um URL e é, por isso, utilizado para o pedido. A resposta pode então ser avaliada através do DOMDocument. O exemplo seguinte combina o pedido "get_active_model" apresentado anteriormente com os comandos utilizados em VBA:
#código.vba#
' obter URL do modelo ativo com o comando "get_active_model"
str_envelope =
"" & _
"
" & _
" " & _
"
" & _
""
' pedido de abertura e envio
pedido.Open "Post", "http://localhost:8081/", Falso
pedido.Enviar (str_envelope)
' obtém a resposta e transforma-a num objeto xml
resposta.LoadXML (request.responseText)
#/code#
Primeiro, o pedido é guardado no formato XML na variável "str_envelope" e o pedido é aberto no RFEM utilizando o método "Open" da variável "request". O conteúdo da variável "str_envelope" pode agora ser enviado através do método "Send". Em seguida, a resposta pode ser acedida através do método "ResponseText". Neste caso específico, esta é importada diretamente através do método "LoadXML" da variável "resposta".
A variável "resposta" do tipo DOMDocuments tem o método LoadXML e pode, portanto, reconhecer a formatação XML. A vantagem é que o tipo DOMDocuments também fornece o método GetElementsByTagName. Isto permite-lhe extrair elementos diretamente do código. A seguir, o código anterior é ampliado para que o endereço URL do modelo fique disponível:
#código.vba#
' obter estado http
estado = pedido.estado
Se o estado <> "200" Então
MsgBox "get_active_model: Envio sem sucesso - " &resposta.Texto
Sair do sub
End If
url_model = resposta.GetElementsByTagName("value")(0).Texto
#/code#
Antes de o URL ser lido, o estado da resposta pode ser verificado. Estes são códigos de estado HTTP normalizados. O estado "200" significa que a transferência foi "OK". Após esta consulta, o URL do modelo é guardado na cadeia de caracteres url_model. Para isso, é necessário procurar o elemento "value" na resposta XML. Se uma resposta contém vários elementos, todos os valores são guardados na secção "valor", para que não seja possível uma avaliação com o identificador "valor", mas sim os subelementos de "valor". No exemplo prático, serão fornecidas mais informações. No caso do endereço do modelo, o único valor retornado é o URL, por isso "valor" bem aqui.
== Exemplo prático em VBA ==
Agora que já conhecemos todos os elementos básicos, vamos ver um exemplo simples. Queremos criar uma viga em dois pilares aos quais uma carga de barra pode ser aplicada.
Primeiro, as variáveis descritas acima são definidas e inicializadas:
#código.vba#
' definir variáveis
Solicitar dimensões As MSXML2.XMLHTTP60
Resposta dim As MSXML2.DOMDocument60
Dim str_envolvente como cadeia de caracteres
Dim url_app como cadeia de caracteres
Dim url_model como cadeia de caracteres
' variáveis de início
Definir pedido = novo MSXML2.XMLHTTP60
Definir resposta = Novo MSXML2.DOMDocument60
Com resposta
.async = Falso
.preservechnb espaçamento = falso
.validateOnParse = Falso
.resolveExternals = Falso
' Utilizar funcionalidade completa do XPation
.SetProperty "SelectionLanguage", "XPath"
' Adicionar espaços de nome específicos para trabalhar com caminhos
.SetProperty "SelectionNamespaces", "xmlns:soap=""http://www.w3.org/2003/05/soap-envelop"" " & _
"xmlns:xsd=""http://www.dlubal.com/rfem.xsd"" & _
"xmlns:n1=""urn:schemas-Microsoft-com:rowset"" & _
"xmlns=""http://www.dlubal.com/pt/rfem.xsd"""
Terminar com
url_app = "http://localhost:8081/"
#/code#
Além das variáveis "request" e "response", é criada a string "str_envelope" para o pedido e "url_app" e "url_model" para os endereços da aplicação e do modelo. Durante a inicialização, as especificações conhecidas do protocolo SOAP podem ser transferidas para avaliar a formatação XML da resposta. O endereço do modelo será utilizado posteriormente, mas o endereço da aplicação tem de ser especificado. Como já mencionado, tem de ser introduzido o endereço padrão "http://localhost:8081/".
O próximo passo é testar a ligação à aplicação. Para este teste, a informação padrão da aplicação é consultada através do comando "get_information":
#código.vba#
' verificar URL da aplicação com o comando "get_information"
str_envelope = "" & _
" " & _
""
' pedido de abertura e envio
pedido.Open "Post", url_app, Falso
pedido.Enviar (str_envelope)
' obtém a resposta e transforma-a num objeto xml
resposta.LoadXML (request.responseText)
' obter estado http
estado = pedido.Estado
Se o estado <> "200" Então
MsgBox "get_information: Envio sem sucesso - " &resposta.Texto
Sair do sub
End If
' ler informação da aplicação
Dim str1 como cadeia de caracteres
str1 = ""
str1 = str1 & resposta.GetElementsByTagName("name")(0).Text & vbLf
str1 = str1 & resposta.GetElementsByTagName("type")(0).Text & vbLf
str1 = str1 & resposta.GetElementsByTagName("version")(0).Text & vbLf
str1 = str1 & resposta.GetElementsByTagName("language_name") (0).Text & vbLf
str1 = str1 & target.GetElementsByTagName("language_id")(0).Texto
MsgBox str1, vbInformation, "Resposta a pedido de ""get_information"""
#/code#
Conforme já descrito na primeira parte, o pedido com formatação XML é preparado e guardado em "str_envelope". "request.Open" abre a ligação com a aplicação. A palavra-chave "Postal" representa o envio do pedido. O terceiro parâmetro é definido como "verdadeiro" e assim é realizada uma transmissão síncrona. Por fim, a cadeia de caracteres preparada é enviada com "request.Send".
Após a transferência, a resposta é guardada em "resposta" e verificada através do "request.Status" se o pedido foi bem-sucedido. O estado é atribuído pelo RFEM para que retorne um erro no caso de um pedido incorreto; por exemplo, um comando desconhecido. Se o estado não é "200", o programa é interrompido e o erro é apresentado numa janela (MsgBox).
Se não tiverem ocorrido erros, as diferentes informações transferidas podem agora ser lidas através de "GetElementsByTagName". No exemplo em particular, a informação é apresentada numa janela.
Os seguintes elementos são muito semelhantes, pelo que apenas são descritas funções especiais (o código fonte completo pode ser descarregado). Para configurar uma viga em dois pilares com uma carga de barra, são necessárias as seguintes funções:
# Nó – conjunto_node
# Linha – conjunto_de
# Material – conjunto_material
# Secção – conjunto_secção
# Barra – conjunto_barra
# Apoio de nó – conjunto_nodal_support
# Parâmetros de cálculo – definir_estático_analysis_settings
# Caso de carga – Set_load_case
# Carga de barra – conjunto_member_load
A função "set_node" tem muitos parâmetros, mas geralmente não são necessários. Na lista de comandos já mencionada do modelo do RFEM, pode ver a variedade de parâmetros. Acima de tudo, os parâmetros que não estão assinalados como "opcionais" são importantes, uma vez que devem ser preenchidos em cada caso. No exemplo, são transferidos os seguintes parâmetros:
#código.vba#
begin_modification (url_model)
' definir nó 1 em [0,0,0] com o comando "set_node"
str_envelope =
"" & _
"
>"& _
""
#/code#
Apenas o número do nó não é opcional; as restantes podem ser atribuídas, mas não tem de ser. Além dos possíveis parâmetros, a lista de comandos também mostra as listagens de tipos. Neste caso específico, são atualmente possíveis cinco tipos diferentes. O tipo padrão "TYPE_STANDARD" foi selecionado. O primeiro nó aqui apresentado é criado na posição (0; 0; 0), o segundo nó em (5.5; 0; 0). Os valores para os números decimais são os seguintes:
#código.vba#
...
"" & _
"2" & _
"TYPE_STANDARD" & _
"5.5" & _
"0" & _
"0" & _
"" & _
...
#/code#
As listas são outra característica especial. A linha necessita de dois nós cujos números possam ser transferidos como uma lista. Os elementos de uma lista, como por exemplo "definition_nodes", são separados por espaços:
#código.vba#
...
"" & _
"" & _
"1" & _
"TYPE_POLYLINE" & _
"1 2" & _
"" & _
"" & _
...
#/code#
Para poder criar a barra, deve ser criada uma secção que, por sua vez, requer um material. As secções e os materiais podem ser utilizados da base de dados interna. Portanto, é suficiente especificar um identificador conhecido. Para o material, o identificador é "S235" e a secção tem o nome "IPE 300":
#código.vba#
...
"" & _
"" & _
"1" & _
"1" & _
"TYPE_STUNDATIONED_STEEL" & _
"IPE 300" & _
"" & _
"" & _
...
#/code#
Para verificar se um nome como "IPE 300" é válido, pode utilizar a entrada na interface gráfica do utilizador.
Para introduzir a barra em si, não é necessário nenhum conhecimento adicional, mas para introduzir um apoio fixo é necessário definir uma rigidez de mola "infinita". A palavra-chave "INF" é utilizada para a transferência:
#código.vba#
...
"" & _
"" & _
"1" & _
"1" & _
"INF" & _
"INF" & _
"INF" & _
"INF" & _
"0" & _
"INF" & _
"" & _
"" & _
...
#/code#
A criação do caso de carga e dos parâmetros de cálculo não requer conhecimentos adicionais. A última particularidade é um valor adicional ao criar a carga, porque esta tem de ser especificada fora da área "". No caso de uma carga de barra, o caso de carga correspondente tem de ser transferido para lá:
#código.vba#
...
"" & _
"1" & _
"" & _
"1" & _
"LOAD_TYPE_Force" & _
"1" & _
"LOAD_Distribution_UNIFORM" & _
"LOAD_DURECTION_GLOBAL_Z_OR_USER_DEFINED_W_TRUE" & _
"1000" & _
"" & _
"" & _
...
#/code#
Além disso, deve ser mencionado que a ordem dos elementos dentro da área do "valor" é irrelevante, mas fora da área não é. O caso de carga especificado deve, portanto, vir antes da área "valor".
Além das funções anteriores para criar e exportar dados, existem duas funções especiais que serão apresentadas aqui. Se forem transferidos elementos para o programa, este entra automaticamente no modo de "Modificação". O programa verifica e integra os novos elementos. Se tiverem de ser criados vários elementos novos, é, portanto, útil deixar o programa neste modo de edição desta vez, para que o processamento seja mais rápido. Para este efeito, estão disponíveis as funções "begin_modification" e "finish_modification".
No exemplo, "begin_modification" é chamado antes de criar o primeiro nó e "finish_modification" é chamado no final, após criar o caso de carga. Ambas as funções também foram criadas como funções VBA no programa. As funções são independentes e, portanto, as variáveis "solicitar" e "resposta" são criadas novamente dentro das funções. No entanto, uma vez que não são necessários novos elementos para isso, estes não serão mais descritos aqui. Uma comparação interessante é com e sem a utilização destas funções, as quais irão sempre resultar numa diferença de velocidade.
== Conclusão ==
O Serviço web e API é uma ferramenta poderosa para o RFEM e o RSTAB. A transferência simples baseada em HTTP permite que a interface seja implementada em muitas linguagens de programação, não apenas em VBA como aqui demonstrado, sendo possível a programação multiplataforma.
