Página editado por Mauricio Rogerio Obenaus Preparação da DBO Para uma DBO ser acessível ao serviço REST, essa DBO deve estar preparada. Ela deve possuir os seguintes pré-processadores: &GLOBAL-DEFINE XMLReceiver YES &GLOBAL-DEFINE XMLProducer YES &GLOBAL-DEFINE DYNAMIC-QUERY-ENABLED YES Por outro lado, a BO não poderá possuir a definição do pré-processador CHANGE-QUERY-TO-FIND nem o valor “Main” no pré-processador CHANGE-QUERY-TO-FIND-PROCS, pois tal combinação impede que os dados da tabela sejam lidos e expostos pelo serviço REST. &GLOBAL-DEFINE CHANGE-QUERY-TO-FIND TRUE &GLOBAL-DEFINE CHANGE-QUERY-TO-FIND-PROCS Main Datasul REST - DBO - Liberação no serviço Para acessar uma DBO pelo serviço REST, a DBO deverá ser liberada no serviço (deploy), para facilitar o serviço disponibiliza uma URL (http://localhost:8080/datasul-rest/resources/dbo/application.wadl/add) com a seguinte pagina: Onde no botão "Browse" deverá ser selecionado o arquivo da DBO compilada (.R) e no campo DBO File PATH deverá ser informado o caminho da DBO relativo ao PROPATH no AppServer. Por exemplo a DBO boun007na está localizada em um diretório chamado unbo no PROPATH. Esse processo faz a valiaçãod da DBO e verifica se ela possui todos os metodos que o DATASUL-REST precisa para funcionar, caso a DBO não tenha os metodos necessários será mostrada um erro informando o que falta implementar na DBO. Datasul REST - DBO - URL Para acessar uma DBO pelo serviço REST a URL da DBO padrão é formada da seguinte dorma: /datasul-rest/resources/api/[caminho da dbo], onde, por exemplo se a DBO chamada for /adbo/boad107na.p fica /datasul-rest/resources/dbo/adbo/boad107na. Datasul REST - DBO - Metodos O serviço REST de DBO disponibiliza 5 maneiras de chamar a DBO para fazer as operações de CRUD, são as seguintes: MetodoURLMetodo HTTPObjetivo getAll/datasul-rest/resources/dbo/[caminho da DBO]/GETRetorna os registros da DBO (Paginado) create/datasul-rest/resources/dbo/[caminho da DBO]/POSTCria um novo registro usando a DBO get/datasul-rest/resources/dbo/[caminho da DBO]/[chaves da tabela]GETBusca um registro da DBO pela chave da tabela update/datasul-rest/resources/dbo/[caminho da DBO]/[chaves da tabela]PUTGrava um registro que ja existe na tabela delete/datasul-rest/resources/dbo/[caminho da DBO]/[chaves da tabela]DELETERemove o registro da tabela com a DBO Neste exemplo o [chaves da tabela] corresponde aos parametros do metodo goToKey da DBO Metodo getAll O metodo get all suporta alguns paramtros de query que podem ser colocados na URL da chamada HTTP. são eles: parametroValorObjetivoValor DefaultExemplo limitInteiroLimita o resultado do GET para este numero de registros (tamanho da pagina)10limit=50 startInteiroIndica o primeiro registro que deve ser carregado na lista (usado na paginação)1start=51 fieldslista separada por virgulaIndica quais campos do registro deverão ser retornadosnenhumfields=codigo,descricao,texto whereStringconteudo utilizado para montar o WHERE da query (padrão progress)nenhumwhere=codigo eq "34" or texto <> ? orderlista separada por virgulaIndica os campos que deverão ser usados para ordenação da busca e do resultadonenhumorder=descricao,texto asclista separada por virgulaInidica se os campos da ordem deve ser ascendentes ou descendentesnenhumasc=true,false property¹StringCampo com o qual será adicionada uma clausula de seleçãonenhumproperty=codigo value¹StringValor para o campo que será adicionado a clausula de seleção do property correspondentenenhumvalue=3 1 - os parametros property e value podem ser repetidos nos parametros da URL e tem que ser na mesma quantidade, cada par property e value gera uma clausula de seleção na busca dos dados da tabela, todas as clausulás são adicionadas a um WHERE com o operador AND. Os campos utilizados no property obrigatóriamente deve estar na temp-table da DBO, isso é necessário porque a temp-table identifica o tipo de dado do campo. O parametro value permite que seja informado um modificador identificando como a clausula para este campo deverá ser montato: ModificadorFunçãoExemploResultado NenhumClausula de igualdade do campo?property=codigo&value=4WHERE codigo = 4 [inicial];[final]Clausula de faixa de valores?property=codigo&value=4;8WHERE codigo >= 4 AND codigo <= 8 [valor1]|[valor2]|[valor3]Clausula de varios valores?property=codigo&value=4|8|12WHERE codigo =4 OR codigo = 8 OR codigo = 12 *[valor]*Clausula contem valor?property=descricao&value=*texto*WHERE descricao MATCHES "*texto*" [valor]*Clausula começa com valor?property=descricao&value=texto*WHERE descricao MATCHES "texto*" *[valor]Clausula termina com valor?property=descricao&value=*textoWHERE descricao MATCHES "*texto" As clausulas de contem, começa e termina com valor são aplicaveis somente a campos CHARACTER. O retorno será um array JSON com os registros selecionados, na ordem informada que será colocado no atributo data do retorno, no retorno tambem será alimentado o atributo length com a contagem dos registros da seleção, por exemplo: JSON de Retorno Expand source { "messages": [], "length": 771, "data": [{ "pais": "AFRICA", "estado": "AFR" }, { "pais": "África do Sul", "estado": "AF" }, { "pais": "Africa do Sul", "estado": "AFS" }, { "pais": "AFRICA DO SUL", "estado": "AS" }, { "pais": "AFRICA DO SUL", "estado": "EX" }, { "pais": "AFRICA DO SUL", "estado": "ZA" }, { "pais": "ALBANIA", "estado": "ALB" }, { "pais": "ALBANIA", "estado": "EX" }, { "pais": "Alemanha", "estado": "" }, { "pais": "Alemanha", "estado": "AH" }] } ainda é possivel passar 2 parametros especiais para o serviço de DBO via header da requisição HTTP: noErrorMessage - quando a BO não encontra nenhum registro é retornado uma mensagem, se esse parametro possuir o valor true, não é retornado mensagem se não encontrar regitros. noCount - se esse parametro tiver o valor true o serviço de DBO não irá efetuar a contagem de registros para retonar no atributo length. Metodo get O metodo get tem o objetivo de buscar um registro na tabela da DBO, para buscar um registro, deverá ser passada a chave do registro no caminho da URL da requisição HTTP, conforme os parametros do metodo goToKey, o retorno ira retornar um objeto JSON no atributo data do retorno, este metodo tambem suporta o paramatro fields (acima) Por exemplo: A DBO adbo/boad107na da tabela estabelec, possui um campo chave "cod-estabel" a URL para acessar o estabelecimento com codigo "abc" fica assim: http://localhost:8080/datasul-rest/resources/dbo/adbo/boad107na/abc A DBO unbo/boun007na da tabela estado, possui dois campos na chave "pais" e "estado", para acessar o estado de SC do Brasil a URL fica assim: http://localhost:8080/datasul-rest/resources/dbo/unbo/boun007na/Brasil/SC JSON de Retorno Expand source { "messages": [], "length": 0, "data": { "pais": "BRASIL", "estado": "SC", "no-estado": "Santa Catarina teste", "cod-sinief": 0, "per-icms-int": 0, "per-sub-tri": 0, "per-ir-adic": 0, "per-icms-ext": 0, "perc-exc": [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0], "est-exc": ["","","","","","","","","","","","","","","","","","","","","","","","",""], "per-desc-icms": [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0], "imp-desc-icms": [false,false,false,false,false,false,false,false,false,false,false,false,false,false,false,false,false,false,false,false,false,false,false,false,false], "ind-uf-subs": false, "desc-icms": 0, "ind-base-st": 1, "pc-icms-st": 0, "dia-vcto-ipi": 1, "dia-vcto-icms": 1, "dia-vcto-iss": 1, "dia-vcto-irrf": 1, "dia-vcto-pis": 1, "dia-vcto-cofins": 1, "venc-icms": [0,0,0,0,0], "venc-ipi": [0,0,0,0,0], "venc-iss": [0,0,0,0,0], "venc-irrf": [0,0,0,0,0], "venc-icmsub": [0,0,0,0,0], "venc-pis": [0,0,0,0,0], "venc-cofins": [0,0,0,0,0], "nr-tb-pauta": "GR2014", "possui-subst-trib": false, "char-1": "", "char-2": "", "dec-1": 0, "dec-2": 0, "int-1": 0, "int-2": 0, "log-1": false, "log-2": false, "data-1": null, "data-2": null, "check-sum": "", "cdn-moeda-corr-icms": 0, "cod-uf-ibge": "", "r-Rowid": "003D093900010000574845524520282850524F47524553535F5245434944203D20000000A90008FFFB00000000000000000000000000005C0129292000" } } ainda é possivel passar o parametro especial noErrorMessage para o serviço de DBO via header da requisição HTTP, quando a BO não encontra nenhum registro é retornado uma mensagem, se esse parametro possuir o valor true, não é retornado mensagem se não encontrar o regitro. Metodo create O metodo create tem o objetivo de criar um registro na tabela da DBO, não ha parametros na URL para este metodo, apenas o registro da tabela deverá ser passado no payload da requisição HTTP. A API permite que no payload do POST tenha um JSON com apenas alguns campos da tabela, os outros campos serão preenchidos com os valores default do dicionario ou os valores definidos pelo metodo beforeNewRecord/afterNewRecord da DBO O Payload para ser enviado ao metodo POST da DBO deve ter o Content-Type: application/json, para o exemplo usando a URL http://localhost:8080/datasul-rest/resources/dbo/unbo/boun007na um payload valido é: Exemplo Payload JSON Expand source { "pais": "USA", "estado": "CA", "no-estado": "California" } Metodo udpate O metodo update possui a mesma URL do metodo get para localizar o registro da tabela, porem o metodo HTTP muda para PUT e o metodo recebe como payload um objeto JSON com o registro que deverá ser atualizado na tabela, onde cada atributo do objeto corresponde a um campo na tabela. A API permite que no payload do PUT tenha um JSON com apenas alguns campos da tabela, os outros campos serão preenchidos com os valores atuais do registro no banco, ou seja só serão alterados os campos que forem enviados para a API. O Payload para ser enviado ao metodo PUT para a URL deve ter o Content-Type: application/json, para o exemplo usando a URL http://localhost:8080/datasul-rest/resources/dbo/unbo/boun007na/Brasil/SC um payload valido é: Exemplo Payload JSON Expand source { "no-estado": "Santa Catarina" } Metodo delete O metodo delete possui a mesma URL do metodo get para localizar o registro da tabela, porem o metodo HTTP muda para DELETE, o metodo não recebe mais nenhum parametro, e o resultado desta chamada termina com o registro da tabela excluido. Campos extras Uma DBO normalmente retorna dados de apenas uma tabela, porem sempre existe a necessiade de trazer campos das tabelas estrangeiras, ou no caso de campos codificados a sua respectiva descricao. Para suprir essa necessidade o datasul-rest para DBO permite que seja retornados dados extras para cada registros que vier pelo metodo HTTP GET Para trazer os campos extras, são necessários: Definir uma temp-table com o nome RowObjectExtra, essa temp-table deve ter o campor r-Rowid; Definir uma procedure getRowObjectExtra que tenha um parametro de output para a temp-table RowObjectExtra. Popular a temp-table RowObjectExtra corretamente, uma sugestão é criar um registro cada cada RowObject atraves da procedure afterCopyBuffer2TT nesse metodo o campo r-Rowid deve ser preenchido. Abaixo segue um exemplo para uma DBO: Exemplo de RowObjectExtra Expand source DEFINE TEMP-TABLE RowObjectExtra NO-UNDO FIELD r-Rowid AS ROWID FIELD extra1 AS CHAR FIELD extra2 AS INT. PROCEDURE getRowObjectExtra: DEFINE OUTPUT PARAMETER TABLE FOR RowObjectExtra. END PROCEDURE. PROCEDURE afterCopyBuffer2TT: CREATE RowObjectExtra. ASSIGN RowObjectExtra.r-Rowid = ROWID({&TableName}) RowObjectExtra.extra1 = "CUSTOM" + mensagem.descricao RowObjectExtra.extra2 = 10000 + mensagem.cod-mensagem. END PROCEDURE. O resultado é que o datasul-rest irá adicioar para cada objeto de dados retornado um atributo "_" (underline) contendo os campos da RowObjectExtra, conforme o exemplo abaixo: Resulta de RowObjectExtra Expand source { "messages": [], "length": 110, "data": [{ "cod-mensagem": 0, "descricao": "Sem Mensagem Padrao", "texto-mensag": "", "char-1": "", "char-2": "", "dec-1": 0, "dec-2": 0, "int-1": 0, "int-2": 0, "log-1": false, "log-2": false, "data-1": null, "data-2": null, "check-sum": "", "r-Rowid": "003D056900010000574845524520282850524F47524553535F5245434944203D200000000F0008FFFB0000000000000000000000000000000129292000", "_": { "extra1": "CUSTOMSem Mensagem Padrao", "extra2": 10000 } }, { "cod-mensagem": 1, "descricao": "IPI-TRIBUTADO 5%", "texto-mensag": "* IPI - ALIQUOTA 5% DECRETO 4542/02\n* TRANSPORTE DE CARGA PROPRIA.", "char-1": "", "char-2": "", "dec-1": 0, "dec-2": 0, "int-1": 0, "int-2": 0, "log-1": false, "log-2": false, "data-1": null, "data-2": null, "check-sum": "", "r-Rowid": "003D056900010000574845524520282850524F47524553535F5245434944203D200000000F0008FFFB0000000000000000000000000000000229292000", "_": { "extra1": "CUSTOMIPI-TRIBUTADO 5%", "extra2": 10001 } }] } Tratamento de RowErrors O serviço de DBO retorna os erros de negocio no atributo messages, porem ignora to tipo INTERNAL com codigos: 3, 6, 8, 10, 19414, 19413 e tipo XML com codigo 6. Exibir Online · Ver Alterações Online Continue reading...
