Modelo de Tarefa, Totali Middleware
Referenciado por: Dicas Técnicas | Documentação em Fontes de Delphi | Modelo Artigo API Middleware | Totali Middleware |
Esse artigo explica como criar um novo serviço REST no Totali Middleware.
Tutorial
1. Incluir método no arquivo que implementa o serviço.
/Classes/.../api/json/
a) Se a tarefa pede para Validar acesso ao Middleware então é necessário que o método receba parâmetros com a seguinte estrutura:
{ "Parametros": { "Id":<id_de_conexao>, "Dados":<parametros_do_serviço> }, "Assinatura":"<assinatura_do_parametro>" }
A "Assinatura" será o MD5 de todo o bloco "Parametros" (apenas letras e número, sem caracteres especiais) + Chave_privada. Dessa forma, não precisamos nos preocupar se o parâmetro "Dados" é um texto, um número, um outro objeto JSON, ou qualquer outro tipo, uma vez que o bloco como um todo será assinado.
Exemplo de rotina que recebe parâmetros e valida se a conexão é válida.
function TNFeAPI.GetProximaNota(const pParametros: TJSONObject): TJSONObject; var oParmJSON: TParamJSON; oJSONDados: TJSONObject; oAPIResult: TAPIResult; begin Result := nil; oParmJSON := nil; oAPIResult := nil; try try oParmJSON := TParamJSONHelper.fromJSON(pParametros); TControleSessao.ValidaSessao(oParmJSON); oJSONDados := TJSONObject(oParmJSON.Dados); oAPIResult := NFeAPI.GetProximaNota(TJSONUtil.GetStr(oJSONDados, 'Filial'), TJSONUtil.GetStr(oJSONDados, 'Serie'), TJSONUtil.GetInt(oJSONDados, 'Quantidade')); Result := TAPIResultHelper.toJSON(oAPIResult); except on E: Exception do begin if Assigned(Result) then FreeAndNil(Result); raise Exception.Create('TNFeAPI.GetProximaNota - Erro ao executar serviço: ' + E.Message); end; end; finally if Assigned(oAPIResult) then FreeAndNil(oAPIResult); if Assigned(oParmJSON) then FreeAndNil(oParmJSON); end; end;
2. Documentar método criado na API externa seguindo os padrões de documentação.
a) Padrões de documentação em fontes de Delphi.
b) Adicionar na lista de APIs Documentação das APIs do Middleware.
c) Para documentação do Método utilizar Modelo Artigo API Middleware para documentação de métodos.
3. Adicionar enumerador na unit TTUEnumeradores, seguindo o padrão dos demais enumeradores de serviços.
TEnumServicos_TConexaoAPI = (TConexaoAPI_NaoEncontrado, TConexaoAPI_ConectaMiddleware, TConexaoAPI_TestaComunicacao); class function TEnum.ServicosConexaoAPIToStr(const pEnum: TEnumServicos_TConexaoAPI): String; begin case pEnum of TConexaoAPI_NaoEncontrado: result := ''; TConexaoAPI_ConectaMiddleware: result := 'ConectaMiddleware'; TConexaoAPI_TestaComunicacao: result := 'TestaComunicacao'; end; end; class function TEnum.ServicosConexaoAPIFromStr(const pValor: String): TEnumServicos_TConexaoAPI; begin Result := TConexaoAPI_NaoEncontrado; if UpperCase(pValor) = UpperCase('ConectaMiddleware') then result := TConexaoAPI_ConectaMiddleware else if UpperCase(pValor) = UpperCase('TestaComunicacao') then result := TConexaoAPI_TestaComunicacao; end;
4. Criar método na API interna chamada pela API JSON.
/Classes/.../api/interna/
Utilizando parâmetros de Delphi separados, devemos criar o método que efetivamente fará o serviço.
Para que a classe da API não cresça infinitamente, é uma boa prática delegar o serviço a uma nova classe de negócio especialmente criada para determinado serviço, sem características de API.
5. Se o serviço fizer parte de uma nova API, deve-se implementar a "leitura" dessa API no método CallPOSTServerMethod da unit TTUMiddlewareHandleContext. Exemplo:
// TConexaoAPI if UpperCase(Argumentos[2]) = UpperCase('TConexaoAPI') then begin Result := GetResultConexaoAPI(TEnum.ServicosConexaoAPIFromStr(Argumentos[3]),oJSONVal); FoundMethod := Result <> ''; end;
Se for apenas a criação de um novo método em uma API existente, basta adicionar a chamada no GetResult correspondente. Exemplo:
function TMiddlewareServerContext.GetResultConexaoAPI(pServico: TEnumServicos_TConexaoAPI; pParametros: TJSONValue): String; var oConexaoAPI : TConexaoAPI; begin Result := ''; oConexaoAPI := nil; try oConexaoAPI := TConexaoAPI.Create; case pServico of TConexaoAPI_ConectaMiddleware: Result := TServerUtils.Result2JSON(oConexaoAPI.ConectaMiddleware(TJSONObject(pParametros))); TConexaoAPI_TestaComunicacao: Result := TServerUtils.Result2JSON(oConexaoAPI.TestaComunicacao(TJSONObject(pParametros))); end; finally if Assigned(oConexaoAPI) then FreeAndNil(oConexaoAPI); end; end;
6. Implementar serviço no Testador
a) Criar nova guia dentro da guia referente a API alterada.
b) Criar ou TGroupBox sem Caption dentro da guia.
c) Utilizar o nome do serviço como sufixo no Name de cada componente: Ex.: ts_ServicoExemplo.
d) Método de teste de mandar a requisição e a resposta para os componentes gerais que se encontram na parte inferior da tela.