Ir para o conteúdo

Publicar um aplicativo Jitterbit App Builder como endpoint de REST API

Visão geral

O App Builder permite publicar dados de um aplicativo como uma REST API, para que sistemas externos possam ler e escrever neles usando uma chave de API para autenticação, em vez de criar uma integração personalizada para cada consumidor. Esta página apresenta um exemplo completo: expor uma tabela customers de um aplicativo Northwinds como um recurso REST, depois gerar uma chave de API que um usuário específico pode usar para chamá-la.

Nota

Quando você empacota este aplicativo em um LP e o implanta em outro ambiente, a configuração de endpoint em IDE > REST APIs persiste automaticamente. Todas as outras configurações neste guia precisam ser recriadas manualmente em cada ambiente adicional.

Os passos são:

Etapa 1: Configurar um provedor de segurança de chave de API

Para proteger sua REST API, 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:

  1. Selecione IDE > Security Providers.

  2. Clique em + Security Provider. A página Provider abre:

    Página Provider

  3. Atribua um Name ao provedor. Por exemplo: API Key.

  4. Selecione API Key como o valor de Type.

  5. Marque a caixa para selecionar Enabled.

  6. Clique em Save.

Dependendo do seu caso de uso, é possível configurar uma das seguintes propriedades opcionais. Clique em + Property no painel Properties para abrir o diálogo Properties:

diálogo properties

  • Para permitir digitar a chave de API na barra de endereços do seu navegador para testes (não recomendado além de testes, pois não é muito seguro), selecione AllowApiKeyInQueryString como Parameter e digite True como Value, depois clique na marca para salvar o registro.

  • Para permitir que a chave de API seja passada por uma conexão HTTP insegura (não recomendado), selecione AllowInsecureHttp como Parameter e digite True em Value, depois clique na marca para salvar o registro.

Etapa 2: Configurar um endpoint

A REST API de cada aplicativo é acessada através de um segmento de caminho base, seu endpoint de aplicativo. Siga estas etapas para configurar um:

  1. Selecione IDE > REST APIs.

  2. Clique no botão Manage Endpoints no painel Services. O diálogo Applications abre:

    Diálogo Applications

  3. Clique no ícone editar do aplicativo que deseja configurar. Por exemplo: Northwinds Design.

  4. Digite o valor do endpoint no campo Endpoint. Por exemplo: northwinds.

  5. Clique no botão Proceed ou no ícone marca de seleção; ambos salvam o valor do endpoint. A linha do aplicativo agora mostra suas colunas Logging, Publish API Doc e Authentication.

  6. (A partir do App Builder 4.67. Se estiver usando uma versão anterior, pule para Etapa 3.) Associe os provedores permitidos para autenticar as requisições deste endpoint:

    1. Clique no ícone Authentication do aplicativo. O diálogo Authentication Providers abre:

Diálogo de Provedores de Autenticação

  1. Clique em + Autenticação. O diálogo Provedor abre:

    Diálogo Provedor

  2. Selecione um dos provedores de chave de API, HTTP ou Servidor de Autorização que você configurou. O campo Scheme preenchido automaticamente com o scheme desse provedor, um nome único que identifica o provedor em URLs e documentos JSON. Opcionalmente, insira uma Descrição e clique em Salvar. Repita as etapas 2 e 3 para cada provedor adicional que deseja permitir para autenticar as solicitações desse endpoint.

  3. Feche o diálogo.

Nota

Esta opção não está disponível em uma aplicação selada. Para uma aplicação selada, clique no ícone na sua coluna Web Service em Aplicações, o que abre o mesmo diálogo Provedores de Autenticação de fora da aplicação.

Etapa 3: Publicar um recurso

Com um endpoint de aplicação em vigor, agora você pode publicar um objeto de negócio específico como um recurso que sistemas externos podem chamar, controlando a quantidade de dados que retorna, sua versão de schema e quais eventos são expostos. Siga estas etapas:

  1. Selecione IDE > REST APIs.

  2. No painel Serviços, localize a aplicação e clique no ícone chevron no seu bloco. A página REST API para essa aplicação abre, exibindo suas propriedades Serviço e Recursos em uma única visualização.

  3. No painel Recursos, clique em + Recurso. O diálogo Recurso abre:

    Diálogo Recurso

  4. Defina os seguintes valores:

    • Tabela: Selecione a tabela ou objeto de negócio que este recurso expõe. Depois que o recurso é salvo, os ícones e próximos a este campo ficam clicáveis, levando você à página Definição de Tabela da tabela ou à página Rule Builder do objeto de negócio (no App Workbench), respectivamente. Apenas um dos dois está sempre disponível para um recurso determinado, dependendo de você ter selecionado uma tabela ou um objeto de negócio.

    • Endpoint: Insira o segmento de caminho onde a API acessa este recurso.

    • GET Default Limit e/ou GET Max Limit: Controle a quantidade de registros retornados em chamadas GET para seu endpoint da API.

    • Compatibilidade: (Opcional, desde o App Builder 4.51.) Controla como o recurso se comporta. Compatibilidade permite que o App Builder introduza nova funcionalidade de endpoint entre versões enquanto preserva o comportamento dos endpoints existentes para compatibilidade com versões anteriores. Selecione uma das seguintes opções:

      • Versão 1: Use o comportamento REST original, em que eventos Insert não são precedidos por eventos New. (Padrão para endpoints criados com App Builder 4.50 e anterior.)

      • Versão 2: Use um comportamento REST aprimorado, em que eventos New e quaisquer regras padrão são invocados antes de eventos Insert. (Padrão para endpoints criados com App Builder 4.51.)

      • Versão 3: (Desde o App Builder 4.52.) Igual à versão 2, mas as APIs retornam o valor lógico em vez do valor de armazenamento. Por exemplo, valores booleanos são retornados como true ou false em vez de 1 ou 0. (Padrão para endpoints criados com App Builder 4.52 e posterior.)

    • Excluir da Documentação: (Opcional, desde o App Builder 4.67.) Marque para omitir este recurso do documento OpenAPI publicado da aplicação, mesmo quando a publicação de documentação estiver ativada para a REST API como um todo.

    • Descrição: (Opcional.) Uma descrição do recurso, incluída no documento OpenAPI publicado da aplicação.

  5. Clique em Salvar.

  6. A aba Nodes do diálogo lista o nó raiz implícito deste recurso, junto com todos os nós filhos que você adicionar. Clique no ícone de detalhes de um nó para abrir seu diálogo Node: consulte Parâmetros de nó e Campos de nó para controlar quais campos são incluídos na resposta por padrão, ou Adicionar um nó filho para aninhar dados adicionais sob este recurso.

  7. (Desde App Builder 4.67.) Em Service propriedades, expanda o menu More, clique no botão Configure Authentication. Isso abre o mesmo diálogo Authentication Providers da Etapa 2, mostrando os provedores já associados a este endpoint e permitindo que você adicione novos se desejar:

    Menu More, botão Configure Authentication

    Diálogo Authentication Providers

Nota

Eventos personalizados não são mais expostos automaticamente. Use a aba Events do diálogo Resource para selecionar quais eventos estão disponíveis através da API. Consulte Invocar eventos personalizados para detalhes.

Etapa 4: Configurar chaves de API para usuários

Por fim, gere uma chave de API associada a um usuário específico, para que a identidade e as permissões desse usuário se apliquem a todas as solicitações feitas com essa chave:

  1. Selecione IDE > User Management.

  2. Selecione um usuário existente ou crie um novo usuário para usar na chamada da API.

    • O usuário deve ser configurado com o tipo de login Interactive.

    • O usuário não precisa ter Local Authentication.

  3. No registro do usuário selecionado ou criado, clique no ícone Keys.

  4. Clique em Create. O diálogo Generate Key abre:

    Diálogo Generate Key

  5. Selecione o provedor de chave de API que você criou na Etapa 1 como Provider, clique em Save. App Builder gera um valor de chave.

    Importante

    Copie a chave gerada agora. Ela não pode ser exibida novamente após você sair desta tela.

Dica

Opcionalmente, você pode configurar funções ou grupos de segurança para os objetos sendo acessados como endpoints.

Para testar ou configurar o uso de seus novos endpoints de API, use a API Key da etapa anterior, as informações de Base URL e Endpoint do documento da API, e o Name dos detalhes do recurso.

Nota

Você também pode publicar um documento OpenAPI (Swagger) descrevendo este endpoint, para que outros aplicativos da plataforma Harmony (como API Manager) bem como ferramentas externas de terceiros possam descobri-lo automaticamente.