Configurar e validar objetos de negócios como endpoints de API no Jitterbit App Builder
Visão geral
Esta página apresenta um fluxo de trabalho completo para expor dados do App Builder como uma API REST e controlar o que é salvo nela: configurar um objeto de negócios como um endpoint que sistemas externos podem chamar, adicionar uma regra de validação que rejeita dados inválidos antes de serem persistidos e testar tudo com um cliente de API de terceiros. O exemplo usado expõe um objeto de negócios Order e adiciona uma regra que rejeita qualquer pedido cuja Required Date já está no passado.
As etapas são:
-
Configurar o endpoint de API
Criar o provedor de segurança, endpoint de aplicativo e endpoint de objeto de negócios necessários para expor dados como uma API REST, e gerar uma chave para que um usuário específico possa se autenticar nela. -
Criar uma regra de validação personalizada
Adicionar uma regra de negócios que valida dados recebidos antes de serem salvos e anexá-la ao evento Save do endpoint. -
Testar o endpoint de API
Usar o Postman para confirmar que a regra de validação rejeita dados inválidos e que o endpoint aceita dados válidos.
Configurar o endpoint de API
Antes que sistemas externos possam ler ou escrever dados pela API REST do App Builder, é necessário expor um objeto de negócios específico como um endpoint e configurar uma forma para que os chamadores se autentiquem nele. Esta seção cobre as etapas de pré-requisito para ambos:
-
Etapa 1: Criar um provedor de segurança de chave de API
Configurar o provedor de segurança contra o qual os chamadores se autenticam. -
Etapa 2: Definir um endpoint de aplicativo
Atribuir ao seu aplicativo o segmento de caminho base usado em suas URLs de API REST. -
Etapa 3: Publicar um endpoint de objeto de negócios
Expor uma tabela específica como um recurso do qual os chamadores podem ler e escrever. -
Etapa 4: Gerar uma chave de API específica do usuário
Criar a credencial que um chamador específico usa para se autenticar.
Etapa 1: Criar um provedor de segurança de chave de API
Para autenticar solicitações feitas ao novo endpoint, primeiro é necessário um provedor de segurança de chave de API, que o App Builder usa para validar a chave que cada chamador apresenta. Siga estas etapas:
-
Selecione IDE > Security Providers.
-
Clique em + Security Provider. A página Provider é aberta:

-
Configure o provedor com estas configurações:
-
Name: Insira um nome descritivo, como
API Key. -
Type: Selecione API Key.
-
Enabled: Selecione para ativar o provedor.
-
-
Clique em Save.
-
(Opcional) Em Properties, clique em + Property para adicionar e configurar parâmetros opcionais para sua chave de API.
Etapa 2: Definir um endpoint de aplicativo
A API REST de cada aplicativo é acessada por um segmento de caminho base, seu endpoint de aplicativo. Defina um agora se seu aplicativo ainda não tiver um:
-
Selecione IDE > REST APIs.
-
Clique em Manage Endpoints. A caixa de diálogo Application Endpoints é aberta, mostrando os aplicativos acessíveis e seus endpoints:

-
Localize o aplicativo que deseja expor e clique no ícone Edit.
-
Insira um nome para o endpoint, como
endpoint-example. -
Clique no ícone (ou no botão Proceed) para salvar o nome do endpoint.
-
Feche a caixa de diálogo Application Endpoints. Uma nova entrada para o endpoint aparece em Services.
Etapa 3: Publicar um endpoint de objeto de negócios
Com um endpoint de aplicação em vigor, você pode publicar um objeto de negócios específico, como uma tabela, como um recurso que os chamadores podem ler e escrever:
-
No painel Services, clique no ícone de chevron do bloco da aplicação. A página REST API para essa aplicação é aberta.
-
No painel Resources, clique em + Resource. A caixa de diálogo Resource é aberta:

-
Defina os seguintes valores:
-
Table: Abra o menu e selecione a tabela que deseja expor.
-
Endpoint: Digite um nome para o endpoint da tabela.
Para uma descrição completa de todos os campos, consulte Etapa 3: Publicar um recurso em Publicar um aplicativo Jitterbit App Builder como um endpoint REST API.
-
-
Clique em Save, depois feche a caixa de diálogo Resource.
-
Para encontrar a URL completa do novo endpoint, combine a URL base da REST API da instância com o endpoint da aplicação (da etapa anterior) e o endpoint do recurso (desta etapa). Consulte Objetos de dados como recursos para o padrão exato de URI.
Etapa 4: Gerar uma chave de API específica do usuário
Por fim, gere uma chave de API vinculada a um usuário específico, para que a identidade e as permissões desse usuário se apliquem a cada solicitação feita com essa chave:
-
Selecione IDE > User Management.
-
Em Users, clique no ícone Open record do usuário para o qual deseja conceder acesso à API. A caixa de diálogo User é aberta.
-
Expanda a seção Authentication e confirme que Login Type está definido como Interactive.
-
Selecione More > Keys. A caixa de diálogo Keys é aberta.
-
Clique em Create. A caixa de diálogo Generate Key é aberta:

-
Defina valores para o seguinte:
-
Provider: Selecione o provedor de segurança criado em Etapa 1 (por exemplo,
API Key). -
(Opcional) Description: Digite uma descrição para essa chave.
-
-
Clique em Save. O App Builder gera automaticamente um valor para a chave. Copie o valor da chave gerada para usar em testes.
Importante
Certifique-se de ter copiado a chave antes de fechar a caixa de diálogo Generate Key, pois não é possível exibi-la novamente.
Criar uma regra de validação personalizada
Uma regra de validação permite rejeitar dados inválidos antes de serem salvos, em vez de fazê-lo depois. Este exemplo cria uma regra que impede que um registro seja salvo se sua Required Date está no passado, depois anexa essa regra ao evento Save do endpoint para que realmente seja executada.
Etapa 1: Criar uma regra de negócios para validação
Regras de negócios validam dados de tabela usando condições no estilo SQL em suas colunas. Crie uma agora para definir a verificação que o endpoint deve aplicar:
-
Abra a aplicação e selecione App Workbench > Rules.
-
Clique em By Table, depois selecione a tabela que está expondo (por exemplo,
Order). -
Em Rules, clique em + Rule. O Rule Builder é aberto:
-
Na página Rule, configure as propriedades básicas da regra:
-
Name: Digite um nome descritivo, como
Validation: Date Not in Past. -
Purpose: Selecione Validation.
-
Target: A tabela já deve estar selecionada (por exemplo,
Order).
-
-
Clique em Create.
-
Configure a lógica da regra:
- Selecione a guia Columns, depois adicione as colunas necessárias à regra. Para este exemplo, adicione
Order IDeRequired Date.
- Selecione a guia Columns, depois adicione as colunas necessárias à regra. Para este exemplo, adicione
-
Selecione a aba Where e adicione uma cláusula para definir a condição de falha. Neste exemplo, para verificar se a data necessária está no passado, adicione uma condição onde
Required Dateé menor ou igual aNow(). -
(Opcional) Clique em Validate.
Etapa 2: Anexar a regra de validação a um evento
Uma regra de validação não é executada por conta própria. É necessário anexá-la a um evento específico, neste caso Save, para que seja executada quando um registro estiver prestes a ser salvo:
-
Em App Workbench > Rules, com By Table selecionado, selecione a mesma tabela (
Orderneste exemplo). -
Clique no ícone Events para (neste exemplo)
Orders (Source). A caixa de diálogo All Events é aberta. -
Na linha Save, clique em Rule Event Detail.
-
Em Validations, clique em Register. A caixa de diálogo Validation é aberta:

-
No menu Rule, selecione a regra de validação que acabou de criar (
Validation: Date Not in Past). -
Configure a ação de validação da seguinte forma:
-
Binding: Selecione Implicit.
-
Failure: Selecione Fail on data returned.
-
Severity: Selecione Error.
-
Message: Digite a mensagem de erro a ser exibida quando a validação falhar, como
The required date cannot be in the past.
-
-
Clique em Save.
Testar o endpoint da API
Com o endpoint publicado e a regra de validação anexada, confirme se tudo funciona de ponta a ponta usando um cliente de API de terceiros. Esta seção usa o Postman, mas as mesmas requisições funcionam com qualquer cliente HTTP capaz de enviar requisições JSON autenticadas.
Etapa 1: Configurar o cliente de teste
Antes de enviar qualquer requisição, configure o Postman com a autenticação e o formato de corpo que seu endpoint espera:
-
No Postman, crie uma nova requisição
POST. -
No campo URL, cole a URL do endpoint que copiou na Etapa 3 da seção anterior.
-
Configure a autorização:
-
Selecione a aba Authorization.
-
Para Type, selecione API Key.
-
Para Key, digite
X-API-Key. -
Para Value, cole a chave de API específica do usuário que copiou na Etapa 4.
-
-
Configure o corpo da requisição:
-
Selecione a aba Body.
-
Selecione o botão de opção Raw.
-
No menu suspenso de formato, selecione JSON.
-
Etapa 2: Testar a regra de validação (caso de falha)
Primeiro, confirme se a regra de validação realmente bloqueia dados inválidos, enviando uma requisição que deveria falhar:
-
No corpo JSON, cole um registro para disparar o erro de validação. Neste exemplo, use uma
Required Dateque está no passado.Example failure record{ "OrderID": 11255, "OrderDate": "2014-05-26T00:00:00", "RequiredDate": "2014-05-20T00:00:00", "ShippedDate": "2014-05-28T00:00:00", "ShipCost": 1000.50, "ShipName": "Test Site", "ShipAddress": "508 Main Street", "ShipCity": "Harwich", "ShipState": "MA", "ShipZip": "02630", "ShipCountry": "USA", "AddedOn": null, "AddedBy": null, "EmployeeID": "0f9c520c-1890-11f1-b283-ab1e4a99c4ce", "ShipperID": "f4b1df98-188f-11f1-90ba-7a85ad06b57c" } -
Clique em Send.
-
Revise a resposta. Você deve ver um erro de validação com a mensagem personalizada configurada:
The required date cannot be in the past.O registro não é criado.
Etapa 3: Testar o endpoint (caso de sucesso)
Agora confirme se o endpoint aceita dados válidos quando a mesma condição de falha não se aplica mais:
-
No corpo JSON, modifique os dados para que sejam válidos. Neste exemplo, altere
RequiredDatepara uma data no futuro.Example success record{ "OrderID": 11255, "OrderDate": "2014-05-26T00:00:00", "RequiredDate": "2114-05-20T00:00:00", "ShippedDate": "2014-05-28T00:00:00", "ShipCost": 1000.50, "ShipName": "Test Site", "ShipAddress": "508 Main Street", "ShipCity": "Harwich", "ShipState": "MA", "ShipZip": "02630", "ShipCountry": "USA", "AddedOn": null, "AddedBy": null, "EmployeeID": "0f9c520c-1890-11f1-b283-ab1e4a99c4ce", "ShipperID": "f4b1df98-188f-11f1-90ba-7a85ad06b57c" } -
Clique em Send.
-
Revise a resposta. Você deve ver um status
200 OK, e o corpo da resposta não deve conter um erro de validação. -
Para confirmar, navegue até a tabela de dados em seu aplicativo App Builder e verifique se o novo registro foi criado com sucesso.
