Publicar um app do Jitterbit App Builder como um endpoint de API REST

Visão geral

O App Builder permite publicar os dados de uma aplicação como uma API REST, para que sistemas externos possam ler e escrever nela 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 uma aplicação Northwinds como um recurso REST e gerar uma chave de API que um usuário específico pode usar para chamá-la.

As etapas são:

• Etapa 1: Configurar um provedor de segurança de chave de API
  Criar o provedor de segurança contra o qual os chamadores se autenticam.

• Etapa 2: Configurar um endpoint
  Atribuir à aplicação o segmento de caminho base usado em suas URLs de API REST.

• Etapa 3: Publicar um recurso
  Expor um objeto de negócio específico como um recurso do qual os chamadores podem ler e escrever, e controlar o que é retornado.

• Etapa 4: Configurar chaves de API para usuários
  Gerar a credencial que um usuário específico usa para se autenticar.

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

Para proteger sua API REST, 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 + User Authentication no painel User Authentication. A caixa de diálogo Provider é aberta:

   

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 a caixa de diálogo Properties:

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

Etapa 2: Configurar um endpoint

A API REST de cada aplicação é acessada por meio de um segmento de caminho base, seu endpoint de aplicação. Siga estas etapas para configurar um:

1. Selecione IDE > REST APIs.

2. Clique no botão Manage Endpoints no painel Services. A caixa de diálogo Applications é aberta:

   

3. Clique no ícone de edição da aplicação 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 de marca ; ambos salvam o valor do endpoint. A linha da aplicação 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 solicitações deste endpoint:

   1. Clique no ícone Authentication da aplicação. A caixa de diálogo Authentication Providers é aberta:

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

   

2. Selecione um dos provedores de chave de API, HTTP ou Servidor de Autorização que você configurou. O campo Esquema é preenchido automaticamente com o esquema 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 deste endpoint.

3. Feche o diálogo.

Etapa 3: Publicar um recurso

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

1. Selecione IDE > REST APIs.

2. No painel Serviços, localize o aplicativo e clique no ícone de chevron no seu bloco. A página REST API desse aplicativo é aberta, mostrando suas propriedades de Serviço e Recursos em uma única visualização.

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

   

4. Defina os seguintes valores:

   • Tabela: Selecione a tabela ou objeto de negócio que este recurso expõe. Após o recurso ser salvo, os ícones e ao lado deste campo se tornam clicáveis, levando você à página Definição de Tabela da tabela ou à página Construtor de Regras do objeto de negócio (no App Workbench), respectivamente. Apenas um dos dois está sempre disponível para um determinado recurso, dependendo se você selecionou uma tabela ou um objeto de negócio.

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

   • Limite Padrão GET e/ou Limite Máximo GET: Controle a quantidade de registros retornados em chamadas GET para seu endpoint de API.

   • Compatibilidade: (Opcional, desde App Builder 4.51.) Controla como o recurso se comporta. A compatibilidade permite que o App Builder introduza novas funcionalidades de endpoint entre versões, preservando 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, no qual eventos de Inserção não são precedidos por eventos de Novo. (Padrão para endpoints criados com App Builder 4.50 e anteriores.)

     • Versão 2: Use um comportamento REST melhorado, no qual eventos de Novo e quaisquer regras padrão são invocados antes de eventos de Inserção. (Padrão para endpoints criados com App Builder 4.51.)

     • Versão 3: (Desde 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 posteriores.)

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

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

5. Clique em Salvar.

6. A guia Nós do diálogo lista o nó raiz implícito deste recurso, juntamente com quaisquer nós filhos que você adicione. Clique no ícone de detalhes de um nó para abrir seu diálogo Nó: consulte Parâmetros de nó e Campos de nó para controlar quais de seus 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.) Nas propriedades do Service, expanda o menu Mais, depois clique no botão Configurar Autenticação. Isso abre o mesmo diálogo Provedores de Autenticação da Etapa 2, mostrando os provedores já associados a este endpoint e permitindo adicionar novos, se desejado:

   

   

Etapa 4: Configurar chaves de API para usuários

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 > Gerenciamento de Usuários.

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

   • O usuário deve ser configurado com o Tipo de Login Interativo.

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

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

4. Clique em Criar. O diálogo Gerar Chave abre:

   

5. Selecione o provedor de Chave de API que você criou na Etapa 1 como o Provedor, depois clique em Salvar. O 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.

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