Configurar e validar objetos de negócios como endpoints de API no Jitterbit App Builder

Introdução

Esta página mostra como expor um objeto de negócios como um endpoint de API, como criar regras de validação personalizadas para os dados enviados a esse endpoint e como testar a configuração completa usando um cliente de API externo.

Parte 1: Configurar o Endpoint da API

Esta seção abrange os passos necessários para expor um objeto de negócios de aplicativo como uma API.

1. Criar um provedor de segurança de chave de API

Para autenticar-se contra a API, você primeiro precisa de um provedor de segurança. Siga estas etapas:

Selecione IDE > Provedores de Segurança.
Em Autenticação de Usuário, clique em + Autenticação de Usuário. A página Provedor é aberta.
Configure o provedor com estas configurações:
- Nome: Insira um nome descritivo, como Chave de API.
- Tipo: Selecione Chave de API.
- Habilitado: Selecione para habilitar o provedor.
Clique em Salvar.
(Opcional) Em Propriedades, clique em + Propriedade para adicionar e configurar parâmetros opcionais para sua chave de API.

2. Definir um endpoint de aplicativo

Em seguida, você precisa criar um ponto de acesso para seu aplicativo. Siga estas etapas:

Selecione IDE > APIs REST.
Clique em Gerenciar Endpoints. O popup Endpoints de Aplicativo é aberto mostrando aplicativos acessíveis e seus endpoints.
Localize o aplicativo que deseja expor e clique em seu ícone Editar.
Insira um nome para o endpoint, como endpoint-exemplo.
Clique no ícone (ou no botão Prosseguir) para salvar o nome do endpoint.
Feche o popup Endpoints de Aplicativo. Uma nova entrada para o endpoint aparece em Aplicativo.

3. Publicar um endpoint de objeto de negócios

Agora você pode publicar um objeto de negócios específico (como uma tabela) do seu aplicativo. Siga estas etapas:

Na página REST APIs, com seu aplicativo selecionado, clique no botão + Resource na seção Resources. O popup Resource é aberto.
Defina os seguintes valores:
- Table: Abra o menu e selecione a tabela que deseja expor.
- Endpoint: Insira um nome para o endpoint da tabela.
Clique em Save, e depois feche o popup Resource.
Para encontrar a URL completa do seu novo endpoint, localize seu aplicativo no painel Application e clique no ícone Doc. Isso abre um relatório contendo a documentação do endpoint da API.
Role pela documentação para encontrar a URL do endpoint do objeto de negócios que você acabou de criar. Copie esta URL para usar mais tarde.

4. Gerar uma chave de API específica do usuário

A etapa final de configuração é gerar uma chave de API para um usuário, permitindo que ele se autentique. Siga estas etapas:

Selecione IDE > User Management.
Em Users, clique no ícone Open record para o usuário ao qual você deseja conceder acesso à API. O popup User é aberto.
Expanda a seção Authentication e confirme que o Login Type está definido como Interactive.
Selecione More > Keys. O popup Keys é aberto.
Clique em Create. O popup Generate Key é aberto.
Defina os valores para o seguinte:
- Provider: Selecione o provedor de segurança que você criou na primeira etapa (por exemplo, API Key).
- (Opcional) Description: Insira uma descrição para esta chave.
Clique em Save. O App Builder gera automaticamente um valor para a chave. Copie o valor da chave gerada para usar nos testes.

Importante

Certifique-se de ter copiado a chave antes de fechar o popup Generate Key, pois não poderá ser exibida novamente.

Parte 2: Criar uma regra de validação personalizada

Esta seção aborda como criar e aplicar uma regra personalizada para validar dados recebidos antes de serem salvos. Este exemplo cria uma regra que impede que um registro seja salvo se sua Required Date estiver no passado.

1. Crie uma regra de negócios para validação

Siga estas etapas:

Abra seu aplicativo e selecione App Workbench > Regras.
Clique em Por Tabela, depois selecione a tabela que você está expondo (por exemplo, Pedido).
Em Regras, clique em + Regra.
Na página Regra, configure as propriedades básicas da regra:
- Nome: Insira um nome descritivo, como Validação: Data Não Pode Ser no Passado.
- Propósito: Selecione Validação.
- Alvo: A tabela já deve estar selecionada (por exemplo, Pedido).
Clique em Criar.
Configure a lógica da regra:
- Selecione a aba Colunas, depois adicione as colunas que a regra precisa. Para este exemplo, adicione ID do Pedido e Data Requerida.
- Selecione a aba Onde, depois adicione uma cláusula para definir a condição de falha. Para este exemplo, para verificar se a data requerida está no passado, adicione uma condição onde Data Requerida é menor ou igual a Agora().
(Opcional) Clique em Validar.

2. Anexe a regra de validação a um evento

Para tornar a regra ativa, associe-a a um evento no objeto de negócios. Siga estas etapas:

Em App Workbench > Regras, com Por Tabela selecionado, selecione a mesma tabela (Pedido neste exemplo).
Clique no ícone Eventos para (neste exemplo) Pedidos (Fonte). O popup Todos os Eventos é aberto.
Na linha Salvar, clique em Detalhe do Evento da Regra.
Em Validações, clique em Registrar. O popup Validação é aberto.
No menu Regra, selecione a regra de validação que você acabou de criar (Validação: Data Não Pode Ser no Passado).
Configure a ação de validação da seguinte forma:
- Vinculação: Selecione Implícita.
- Falha: Selecione Falhar nos dados retornados.
- Severidade: Selecione Erro.
- Mensagem: Insira a mensagem de erro a ser exibida quando a validação falhar, como A data requerida não pode estar no passado.
Clique em Salvar.

Parte 3: Teste o endpoint da API

Esta seção aborda como testar o endpoint usando um cliente de API de terceiros, como o Postman, para garantir que ele esteja funcionando conforme o esperado.

1. Configure o Cliente de Teste

Siga estas etapas:

No Postman, crie uma nova solicitação POST.
No campo de URL, cole a URL do endpoint que você copiou da documentação da API.
Configure a autorização:
- Selecione a aba Authorization.
- Para Type, selecione API Key.
- Para Key, insira X-API-Key.
- Para Value, cole a chave da API do usuário que você copiou anteriormente.
Configure o corpo da solicitação:
- Selecione a aba Body.
- Selecione o botão de opção Raw.
- No menu suspenso de formato, selecione JSON.

2. Teste a regra de validação (caso de falha)

Siga estas etapas:

No corpo JSON, cole um registro para acionar o erro de validação. Para este exemplo, use uma Required Date que esteja no passado.

Exemplo de registro de falha

{
    "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 que você configurou: A data obrigatória não pode estar no passado. O registro não é criado.

3. Teste o endpoint (caso de sucesso)

Siga estas etapas:

No corpo JSON, modifique os dados para que sejam válidos. Para este exemplo, altere a RequiredDate para uma data no futuro.

Exemplo de registro de sucesso

{
    "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.