Scripts REST

ATENÇÃO:

O tópico a seguir pode incluir referências aos aspetos de programação personalizada da linha de produtos IndySoft. Alguns aspetos das funcionalidades em questão podem não estar acessíveis aos clientes finais. A título de referência, as funcionalidades afetadas incluirão a palavra «script» ou «script personalizado».Consulte o tópico «Visão geral dos scripts personalizados» para obter mais informações sobre os scripts personalizados e sobre a forma como são implementados e suportados no produto.

Além disso, tenha em atenção que a utilização de scripts REST para aceder à base de dados IndySoft através da Web exigirá o registo do produto «IndySoft REST Scripting» no Módulo de Registo IndySoft. Contacte o departamento de vendas da IndySoft para obter mais informações. Se o «IndySoft REST Scripting» tiver sido registado como produto (através do Utilitário de Registo da IndySoft), a separador «REST Scripts» pode ser utilizada para modificar scripts e configurar o serviço IndySoft REST correspondente. Os scripts REST permitem o acesso à base de dados da IndySoft através de scripts web. A funcionalidade é inteiramente controlada pelos scripts criados/mantidos neste separador. O REST é simplesmente um estilo arquitetónico para pedidos e respostas HTTP. Se o IndySoft REST Server estiver em execução e tiverem sido criados um ou mais scripts REST, o IndySoft poderá monitorizar pedidos HTTP específicos e responder em conformidade através deste serviço.

Eis um exemplo muito simples. Suponha que seja o proprietário do domínio myurl.com e queira permitir que um pedido web específico devolva a data de vencimento da calibração de um ativo específico. (Este é um exemplo muito simples!). Primeiro, deve configurar um script REST que seja acionado com base em pedidos HTTP específicos. Este script iria ler os parâmetros necessários em cada pedido e, em seguida, enviar uma resposta HTTP. O nome do script corresponderia à parte final do URL na solicitação. Em seguida, instalaria/executaria o serviço REST da IndySoft (apontando para o seu domínio myurl.com a funcionar numa porta específica, etc. A funcionalidade de script REST no IndySoft permite aceder a todas as propriedades das solicitações HTTP (URL, porta, IP, etc.), ao tipo de solicitação («GET», «POST», «PUT», «DELETE»), a todos os cabeçalhos, a todos os parâmetros de consulta e ao corpo da mensagem (seja em formato de texto ou binário). Estão disponíveis funções de script específicas para devolver cada um. No nosso exemplo, suponhamos que o pedido web do lado do cliente seja realizado inteiramente na URL (não é necessário um corpo de mensagem neste exemplo do cliente):

http://myurl.com:9001/IndyScripts/ReturnDueDate?Company=ABC+COMPANY&Id=ABC123

Assim, a partir do URL do exemplo acima, vemos que o nosso servidor REST IndySoft está a funcionar através de HTTP (e não de HTTPS), que o domínio onde está configurado é myurl.com e que o URI relativo (conforme configurado na instalação) é «IndyScripts». O nome do script que está a ser chamado é «ReturnDueDate». Por fim, são passados dois parâmetros de consulta: «Company» e «Id». Apenas os pedidos HTTP enviados para «[http://myurl.com:9001/IndyScripts]» (http://myurl.com:9001/IndyScripts') chegarão ao servidor REST da IndySoft. Além disso, apenas os pedidos seguidos (no URL) de um nome de script irão executar um script, como no caso de 'http://myurl.com:9001/IndyScripts/ReturnDueDate', que executa o script 'ReturnDueDate'. Por fim, o script irá ler os parâmetros da consulta (entre outros detalhes, conforme necessário) e responder em conformidade. Segue-se um exemplo do script do servidor REST:

sCompany = RequestQueryParameter("Company")

sID = RequestQueryParameter("Id")

if tdDoSQLRecords(1, "SELECT SCHED_DUE_DATE FROM SCHEDGI WHERE COMPANY = '" & sCompany & "' AND GAGE_SN = '" & sID & "' AND SCHED_TYPE = 'CALIBRATION'") then

sDueDate = tdFieldbyNameAsString(1, "SCHED_DUE_DATE")

ResponseStatusCode(700)

ResponseBodyAsText(sDueDate)

Else

sDueDate = ""

ResponseStatusCode(800)

ResponseBodyAsText(sDueDate)

End If

Este é, portanto, um exemplo muito simples. O script lê os parâmetros de consulta da URL para «Empresa» e «Id.». Note que os símbolos codificados por percentagem são automaticamente substituídos pela função RequestQueryParameter («ABC+COMPANY» é devolvido como «ABC COMPANY»). Se for encontrada uma data de vencimento de CALIBRAÇÃO para este ativo, essa data é devolvida sob a forma de texto, juntamente com um código de resposta HTTP 700. Se não for encontrada nenhuma data de vencimento, é devolvido um texto vazio e um código de resposta HTTP 800. Em scripts mais comuns, a resposta seria uma página HTML completa. Ou então, a resposta incluiria um ficheiro XML no corpo da mensagem de resposta que fornece mais detalhes sobre a transação concluída. Mas isso é o básico: enviar um pedido HTTP para um URL + URI relativa + script + parâmetros opcionais. Inclua nesta solicitação cabeçalhos opcionais e/ou o corpo da mensagem. O script do servidor responde a pedidos válidos, lê os detalhes da mensagem e envia uma resposta adequada. As respostas HTTP incluem um código de resposta e um corpo de mensagem em formato de texto ou binário. O cliente HTTP deve ser capaz de responder de forma adequada (se a resposta for um ficheiro HTML, este será apresentado; se houver um PDF no corpo da mensagem, este será exibido, etc.)

Configuração do IndySoftRESTServer
O primeiro passo (após registar o «IndySoft REST Scripting» no Utilitário de Registo do IndySoft) é configurar o Serviço IndySoft REST no seu servidor web. Este serviço responderá a todos os pedidos web relacionados com este domínio. Para abrir o ecrã de configuração, prima o botão «IndySoftRESTServer Setup» acima da grelha «REST Scripts»:

Configuração do IndySoftRESTServer

Configurações do IndySoft REST Server

Esta caixa de diálogo é utilizada para instalar/desinstalar o Serviço REST da IndySoft, iniciar/parar o serviço e introduzir/guardar todas as definições relacionadas. IMPORTANTE: Serão necessários direitos de administrador do Windows se esta caixa de diálogo for utilizada para instalar/desinstalar o serviço ou para reservar automaticamente um espaço de nomes para o anfitrião/URI. Certifique-se de que encerra e reinicia o IndySoftSyncOptions.exe com a opção «Executar como administrador» no Windows antes de continuar.

·Instalar serviço / Desinstalar serviço: o botão na parte superior da caixa de diálogo pode ser utilizado para instalar ou desinstalar o serviço, conforme o caso. Tenha em atenção que são necessários os direitos de acesso adequados no Windows para realizar esta ação. Depois de instalado, verá o serviço listado entre os serviços do Windows como «IndySoft REST Server». Após a instalação ou desinstalação, a janela de diálogo irá fechar. Nota: talvez seja melhor verificar o botão «Definições avançadas» antes de instalar o serviço. Depois de instalado, o serviço pode ser iniciado ou parado através dos botões na parte inferior da caixa de diálogo. Obviamente, o serviço também pode ser parado ou iniciado diretamente a partir dos Serviços do Windows.

·Porta utilizada: Introduza a porta pretendida para o serviço REST da IndySoft. Esta porta pode ser especificada na solicitação HTTP após o domínio do host, seguida de dois pontos (ver exemplo na caixa de diálogo).

·Utilizar HTTPS: assinale esta caixa se preferir utilizar pedidos HTTPS em vez de HTTP. Se for utilizado HTTPS, é necessário especificar um certificado. Ao guardar as definições (ao clicar em OK), o IndySoft irá solicitar-lhe automaticamente que selecione um certificado através do Windows. Este processo ocorrerá quando a IndySoft tentar registar o Host especificado.

·Host: introduza o nome do domínio do seu host para este servidor.Nota: À medida que as definições são guardadas (ao clicar no botão OK), o IndySoft tentará registar automaticamente este espaço de nomes de URL. O IndySoft REST Server baseia-se no hHTTPsys em modo de kernel, o que significa que o sistema operativo processa todos os pedidos HTTP. Nesta arquitetura, o kernel reencaminha os pedidos HTTP com base no URL solicitado. Para que isto funcione, precisamos primeiro de reservar um espaço de nomes de URL. A reserva de espaço de nomes atribui os direitos sobre uma parte do espaço de nomes de URL HTTP a um determinado grupo de utilizadores do Windows. Uma reserva confere a esses utilizadores o direito de criar serviços que escutam nessa parte do espaço de nomes. Suponhamos, então, que, com base nas definições especificadas nesta caixa de diálogo, o seu servidor funcione no endereço «[http://myurl.com:9001/IndyScripts/]» (http://myurl.com:9001/IndyScripts/'). Nesse caso, a IndySoft tentará reservar esse espaço de nomes para garantir que o Windows aceite os pedidos HTTP para esses endereços, em vez de os recusar. Se precisar de configurar estas regras manualmente, solicite a ferramenta IndyHTTPConfig.exe ao Suporte da IndySoft. Note que esta mesma ferramenta IndyHTTPConfig.exe já está incluída no Servidor de Aplicações de 3 Camadas (caso esse serviço esteja instalado no mesmo servidor).

·URI relativa: introduza o nome da URI relativa. Esta é a parte do espaço de nomes que se segue ao Host; por exemplo, a parte «IndyScripts» do URL completo «http://myurl.com:9001/IndyScripts/ScriptNameHere»

·Exemplo: Este texto de leitura apenas acrescenta as quatro definições acima ao formato exigido ao efetuar o pedido do cliente. Note que a parte final do URL incluirá uma referência ao script específico (seguida de quaisquer parâmetros de consulta opcionais). O pequeno botão à direita desta caixa de edição abrirá o URL indicado. O seu navegador predefinido irá processar o pedido. Nota: este link não está necessariamente completo — uma vez que, normalmente, são necessários parâmetros de consulta adicionais ou um corpo de mensagem, trata-se apenas de um ponto de partida.

·Início de sessão no servidor: O IndySoft REST Server executa os scripts através da ligação do cliente à base de dados. Isto significa que determinadas configurações, como o e-mail, seguirão as definições do utilizador e da localização. Por esse motivo, é importante especificar um nome de utilizador que deverá ser utilizado para carregar estas definições no arranque do IndySoft REST Server. Será utilizada a localização PRÉ-DEFINIDA para este utilizador.

·Pré-carregar scripts: Quando esta opção estiver marcada, todos os scripts serão pré-carregados na memória no arranque do IndySoft REST Server. Isto permite uma execução ligeiramente mais rápida de cada pedido web. A desvantagem é que, se o script for alterado (no IndySoft DataSync Utility... Scripts REST), será necessário parar e reiniciar o serviço para que as alterações na funcionalidade fiquem disponíveis. Se esta caixa não estiver marcada, o script é carregado da base de dados em cada pedido.

·Registar todos os pedidos: Esta opção só deve ser ativada, normalmente, durante a depuração de um novo script. Quando esta opção está ativada, todos os pedidos são registados no separador «Histórico/Estado». O registo de pedidos incluirá uma lista completa de todas as propriedades, cabeçalhos, parâmetros de consulta e corpos de mensagem disponíveis para consulta no script. Os valores serão registados no registo no mesmo formato em que podem ser referenciados (se desejado) no script.

·Definições avançadas: Se desejar, utilize esta caixa de diálogo para especificar dependências de serviços e credenciais. Nota: estas definições só serão aplicadas ao serviço após a instalação

·Iniciar/Parar o serviço: utilize os dois botões no canto inferior esquerdo da caixa de diálogo para iniciar/parar o IndySoft REST Server.

Grelha de scripts REST
Adicionar/Editar/Eliminar script REST - utilize estas opções para adicionar, editar ou eliminar um script REST. Estas opções só estão disponíveis se o «IndySoft REST Scripting» for um produto registado. Caso contrário, ser-lhe-á solicitado um código de resposta que só pode ser obtido junto do Apoio ao Cliente da IndySoft.

Imprimir grelha de scripts REST - Utilize esta opção para imprimir rapidamente uma lista atualizada da grelha de scripts REST.

Ver apenas o script REST - Utilize este botão para rever o script REST atualmente selecionado sem direitos de edição. Esta opção é útil se não tiver direitos de edição, mas precisar de confirmar o funcionamento do script selecionado.

Importar/Exportar Script REST - Utilize estas opções para importar um script REST a partir de um ficheiro zip (conforme exportado anteriormente através da opção de exportação) ou para exportar o script atualmente selecionado para um ficheiro zip.

Configuração do servidor REST do IndySoft - Utilize esta opção para abrir a caixa de diálogo de configurações do servidor REST.

Adicionar/Editar Script REST
·Nome do script - O nome exclusivo do script REST. Este nome aparecerá no histórico de registos e em quaisquer e-mails enviados a partir do script ou em resposta a erros do script.

·Ativo - Se o script foi carregado/executado pelo serviço REST da IndySoft. O script só pode ser testado a partir do ecrã IndySoftSyncOptions se esta opção não estiver marcada.

·VBScript/Pascal - Cada script pode ser escrito na sintaxe VBScript ou Pascal

·Nome codificado (para URL) - O nome do script («Nome do script», à esquerda) deve ser utilizado para chamar este script a partir de um pedido HTTP na Web. Se o nome do script contiver caracteres que não podem ser introduzidos numa URL, deve ser utilizada a versão codificada do nome do script (conforme mostrado automaticamente aqui). Por exemplo, o nome do script «WEB SCRIPT» seria codificado como «WEB%20SCRIPT» numa URL.

·Descrição - Uma descrição mais detalhada do script

·Erros do script para - Pode conter um ou mais endereços de e-mail. Essas pessoas receberão automaticamente um e-mail caso o script apresente um erro durante a execução. Note que estes erros estão relacionados com a compilação do script, não sendo necessariamente erros internos do script que possam ser detetados nessa fase. Por exemplo, se houver erros de sintaxe no script, estes endereços de e-mail serão notificados (uma vez que o script não pode ser compilado). Mas se o seu script carregar um ficheiro XML, por exemplo, e esse ficheiro XML tiver um formato incorreto que devolva um código de erro, a lógica do seu script pode ou não responder a esse código de erro — isso depende do autor do script. Portanto, se o seu script detetar o código de erro, pode chamar a função SendEMail a partir do próprio script para responder a esse erro. Se pretender indicar estes endereços de «Enviar erros para» a partir do script, utilize a função SendScriptErrorsTo.

À direita do script, encontra-se o separador «Procedimentos/Funções», que apresenta aos utilizadores os procedimentos e funções disponíveis. Os utilizadores podem arrastar e soltar essas funções/procedimentos na área do script. O separador «Registo de depuração» regista quaisquer erros de sintaxe durante o teste do script. Além disso, este texto «Registo de depuração» pode ser preenchido com notas de depuração a partir do próprio script, chamando a função DebugLog.

Para obter assistência ou consultar os procedimentos e funções de script relacionados com REST disponíveis, consulte os tópicos «Funções de script REST» na documentação de ajuda do IndySoft Custom Scripting. |