Ir para o conteúdo

Configurar e validar objetos de negócio 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ócio 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 em todo o documento expõe um objeto de negócio Order e adiciona uma regra que rejeita qualquer pedido cuja Required Date já está no passado.

As etapas são:

  • Configurar o endpoint da API
    Criar o provedor de segurança, o endpoint da aplicação e o endpoint do objeto de negócio necessários para expor dados como uma API REST, depois gerar uma chave para que um usuário específico possa se autenticar contra ela.

  • Criar uma regra de validação personalizada
    Adicionar uma regra de negócio que valida dados recebidos antes de serem salvos e anexá-la ao evento Save do endpoint.

  • Testar o endpoint da 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 da API

Antes que sistemas externos possam ler ou escrever dados através da API REST do App Builder, é necessário expor um objeto de negócio específico como um endpoint e configurar uma forma para que os chamadores se autentiquem contra ele. Esta seção aborda as etapas de pré-requisito para fazer ambos:

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:

  1. Selecione IDE > Security Providers.

  2. Em User Authentication, clique em + User Authentication. A caixa de diálogo Provider é aberta:

    provider dialog

  3. Configure o provedor com estas configurações:

    • Name: Digite um nome descritivo, como API Key.

    • Type: Selecione API Key.

    • Enabled: Selecione para ativar o provedor.

  4. Clique em Save.

  5. (Opcional) Em Properties, clique em + Property para adicionar e configurar parâmetros opcionais para a chave de API.

Etapa 2: Definir um endpoint da aplicação

A API REST de cada aplicação é acessada através de um segmento de caminho base, seu endpoint da aplicação. Defina um agora se a aplicação ainda não tiver um:

  1. Selecione IDE > REST APIs.

  2. Clique em Manage Endpoints. A caixa de diálogo Application Endpoints é aberta mostrando as aplicações acessíveis e seus endpoints:

    Application Endpoints dialog

  3. Localize a aplicação que deseja expor e clique no ícone Edit.

  4. Digite um nome para o endpoint, como endpoint-example.

  5. Clique no ícone (ou no botão Proceed) para salvar o nome do endpoint.

  6. 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ócio

Com um endpoint de aplicação em vigor, você pode publicar um objeto de negócio específico, como uma tabela, como um recurso que os chamadores podem ler e escrever:

  1. No painel Services, clique no ícone de chevron no bloco do seu aplicativo. A página REST API desse aplicativo abre.

  2. No painel Resources, clique em + Resource. A caixa de diálogo Resource abre:

    Caixa de diálogo Resource

  3. 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.

  4. Clique em Save e feche a caixa de diálogo Resource.

  5. Para encontrar a URL completa do seu novo endpoint, combine a URL base da REST API da sua instância com o endpoint do seu aplicativo (da etapa anterior) e o endpoint do recurso (desta etapa). Consulte Objetos de dados como recursos para o padrão URI exato.

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:

  1. Selecione IDE > User Management.

  2. Em Users, clique no ícone Open record do usuário ao qual deseja conceder acesso à API. A caixa de diálogo User abre.

  3. Expanda a seção Authentication e confirme que Login Type está definido como Interactive.

  4. Selecione More > Keys. A caixa de diálogo Keys abre.

  5. Clique em Create. A caixa de diálogo Generate Key abre:

    Caixa de diálogo Generate Key

  6. Defina valores para o seguinte:

    • Provider: Selecione o provedor de segurança que você criou em Etapa 1 (por exemplo, API Key).

    • (Opcional) Description: Digite uma descrição para essa chave.

  7. 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 ela não pode ser exibida 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 depois do fato. Este exemplo cria uma regra que impede que um registro seja salvo se sua Required Date estiver no passado e anexa essa regra ao evento Save do endpoint para que ela seja executada.

Etapa 1: Criar uma regra de negócio para validação

As regras de negócio validam dados de tabela usando condições no estilo SQL sobre suas colunas. Crie uma agora para definir a verificação que seu endpoint deve aplicar:

  1. Abra seu aplicativo e selecione App Workbench > Rules.

  2. Clique em By Table e selecione a tabela que está expondo (por exemplo, Order).

  3. Em Rules, clique em + Rule. O Rule Builder abre:

    Construtor de regras

  4. 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).

  5. Clique em Create.

  6. Configure a lógica da regra:

    • Selecione a guia Columns e adicione as colunas que a regra precisa. Para este exemplo, adicione Order ID e Required Date.

  7. Selecione a aba Where e adicione uma cláusula para definir a condição de falha. Neste exemplo, para verificar se a data obrigatória está no passado, adicione uma condição onde Required Date é menor ou igual a Now().

  8. (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 ela seja executada quando um registro estiver prestes a ser salvo:

  1. Em App Workbench > Rules, com By Table selecionado, selecione a mesma tabela (Order neste exemplo).

  2. Clique no ícone Events para (neste exemplo) Orders (Source). A caixa de diálogo All Events é aberta.

  3. Na linha Save, clique em Rule Event Detail.

  4. Em Validations, clique em Register. A caixa de diálogo Validation é aberta:

    Validation dialog

  5. No menu Rule, selecione a regra de validação que você acabou de criar (Validation: Date Not in Past).

  6. 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.

  7. 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 solicitações funcionam com qualquer cliente HTTP capaz de enviar solicitações JSON autenticadas.

Etapa 1: Configurar o cliente de teste

Antes de enviar qualquer solicitação, configure o Postman com a autenticação e o formato de corpo que seu endpoint espera:

  1. No Postman, crie uma nova solicitação POST.

  2. No campo URL, cole a URL do endpoint que você copiou na Etapa 3 da seção anterior.

  3. 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 você copiou na Etapa 4.

  4. 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.

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 solicitação que deve falhar:

  1. No corpo JSON, cole um registro para disparar o erro de validação. Neste exemplo, use uma Required Date que 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"
}

  2. Clique em Send.

  3. Revise a resposta. Você deve ver um erro de validação com a mensagem personalizada que configurou: 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:

  1. No corpo JSON, modifique os dados para que sejam válidos. Neste exemplo, altere RequiredDate para 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"
}

  2. Clique em Send.

  3. Revise a resposta. Você deve ver um status 200 OK e o corpo da resposta não deve conter um erro de validação.

  4. Para confirmar, navegue até a tabela de dados em seu aplicativo App Builder e verifique se o novo registro foi criado com sucesso.