Objeto REST no Jitterbit App Builder

Visão geral

Objetos REST permitem que desenvolvedores do App Builder utilizem APIs REST de forma semelhante aos Objetos de Dados do App Builder. Os Objetos REST suportam o seguinte:

• Operações CRUD
• Integração com vários controles do App Builder, como painéis de várias linhas/linhas únicas, listas
• Eventos personalizados
• Classificação
• Filtragem (string de consultar de filtro no estilo OData)

Para APIs REST que suportam operações no estilo CRUD, configurar um objeto REST pode ser uma maneira fácil de integrar uma API ao seu aplicativo App Builder.

Endpoints CRUD

Para uma API REST estilo CRUD, você precisará configurar Endpoints que permitam a criação, leitura, atualização e exclusão de registros. Em geral, isso significa configurar os seguintes Endpoints:

Exemplo de configuração da API REST do App Builder

As etapas abaixo demonstram como configurar endpoints CRUD para um servidor REST do App Builder. Neste exemplo, assumiremos que existe uma tabela como:

Esta API REST é exposta a partir do endpoint "northwinds" como um recurso chamado "customers". Portanto, a URL para acessar este endpoint seria:

https://api.example.com/rest/v1/northwinds/customers

Certifique-se de ter configurado a API REST no seu servidor e criado a Fonte de Dados REST antes de continuar.

Ler endpoint

• Navegue até IDE > Servidores de dados > Seu servidor de dados REST > Detalhes
• Clique em + Endpoint no painel Endpoints e configure as seguintes informações:
  • Nome: clientes (obter)
  • Endpoint: clientes
  • Método: GET
• Clique em Salvar
• Clique em Descobrir
• Voltar para a página anterior
• Selecione o endpoint do seu cliente (obter)
• Observe que existem três tabelas de saída
• Clique duas vezes na tabela clientes (obter)/itens
• Defina a coluna customerId como a chave primária
• Certifique-se de que as colunas estejam usando o tipo de armazenamento esperado
• Clique em Resultados e verifique se os dados retornados são conforme o esperado

Criar

• Navegue até IDE > Servidores de dados > Seu servidor de dados REST > Detalhes

• Clique em + Endpoint no painel Endpoints e configure as seguintes informações

  • Nome: clientes (inserir)
  • Endpoint: clientes
  • Método: POST

  • Exemplo de entrada - O App Builder espera que a entrada esteja no seguinte formato:

    {
      "item": {
        "customerId": "abcde",
        "name": "Test Customer",
        "daysActive": 10
      }
    }
    

• Clique em Salvar

• Clique em Descobrir
  • Observe que clicar em Descobrir mais de uma vez pode causar uma violação de chave primária, pois o registro "abcde" já existirá no servidor. Se isso acontecer, você precisará excluir o registro existente para que o Descobrir funcione. Exclua o registro no servidor da API REST do App Builder ou configure e importe o endpoint"Excluir".
• Voltar para a página anterior
• Selecione seu cliente (inserir) Endpoint
• Clique duas vezes na tabela clientes (inserir)
• Defina a coluna customerId como a chave primária
• Defina as colunas customerId, name e daysActive na direção Input/Output.
  • Quando criamos um registro, passamos todas as três colunas (Entrada). O servidor da API REST do App Builder ecoa essas colunas no JSON retornado (Saída). Se, por algum motivo, o servidor retornar um valor diferente do que enviamos (talvez formatando uma string), queremos que nosso registro contenha os valores retornados.
• Certifique-se de que as colunas estejam usando o tipo de armazenamento esperado

Atualizar

• Navegue até IDE > Servidores de dados > Seu servidor de dados REST > Detalhes
• Clique em + Endpoint no painel Endpoints e configure as seguintes informações
• Nome: clientes (atualização)
• Endpoint: clientes/{{item/customerId}}
• Método: POST

• Exemplo de entrada - O App Builder espera que a entrada esteja no seguinte formato:

  {
    "item": {
      "customerId": "abcde",
      "name": "Test Customer (updated)",
      "daysActive": 10
    }
  }
  

• Clique em Salvar

• Clique em Descobrir
• Voltar para a página anterior
• Selecione seu endpoint clientes (atualização)
• Clique duas vezes na tabela clientes (atualização)
• Defina a coluna customerId como a chave primária
• Defina as colunas customerId, name e daysActive na direção Input/Output.
• Certifique-se de que as colunas estejam usando o tipo de armazenamento esperado

Objeto REST

Depois que seus CRUD Endpoints estiverem configurados, você poderá criar o Objeto REST.

Criar objeto REST

• Navegue até IDE > Servidores de Dados > Seu Servidor de Dados REST > Detalhes
• Clique em Mais > Super Objetos
• Clique em + Objeto REST
• Nomeie seu Objeto REST... assumiremos Clientes
• Clique no ícone de marca de seleção para salvar
• Clique no ícone de edição de lápis
• Habilite Inserir, Atualizar e Excluir clicando conforme apropriado
• Clique em Prosseguir ou no ícone de marca de seleção para salvar

Configurar composição única

• Clique no ícone Abrir Registro para o Objeto REST
• Clique no ícone Comp Único
• Adicione a tabela clientes (obter)/itens ao painel Tabelas
• Clique no ícone "*" Botão para adicionar todas as colunas
• Clique duas vezes na coluna customerId e defina-a como Chave Primária
• Percorra cada coluna e defina o Tipo de Dado Lógico adequadamente
• Observe que, se você clicar em Resultados antes de configurar a Computação de Muitos (abaixo), receberá a mensagem de erro "Sem sequência". Você precisará configurar o objeto Muitos primeiro.
• Retorne à tela Objetos REST

Configurar muitos comp

• Clique no ícone Muitas Compensações
• Adicione a tabela clientes (obter)/itens ao painel Tabelas
• Clique no ícone "*" Botão para adicionar todas as colunas
• Defina as colunas Destino com seus nomes de coluna correspondentes
• Clique duas vezes na coluna customerId e defina-a como Chave Primária
• Clique em Resultados e verifique se você vê os dados apropriados
• Retorne à tela Objetos REST

Configurar endpoints CRUD

Para cada lista de operação CRUD, configure o Endpoint e as Ligações conforme a tabela abaixo:

Agora você poderá clicar no botão Resultados no seu Objeto REST e adicionar/excluir/atualizar linhas.

Eventos personalizados

Objetos REST podem definir eventos personalizados de forma semelhante a outros Objetos de Dados do App Builder. Para adicionar um evento personalizado ao seu Objeto REST, você precisará:

• Crie um Endpoint de evento personalizado
• Crie uma regra CRUD para inserir no Endpoint
  • Você precisará de um aplicativo configurado com a fonte de dados
• Adicionar um evento personalizado ao objeto REST

Criar endpoint de evento personalizado

No App Builder, um evento personalizado em uma tabela pode ser chamado usando esta notação de URL:

https://example.com/rest/v1/northwinds/mytable(myevent)/{{primaryKeyColumn}}

Por exemplo, se continuarmos usando o exemplo acima, o seguinte Endpoint teria como alvo um evento "maiúsculo" na tabela "clientes":

customers(uppercase)/{{item/clienteId}}

Para configurar isso, faça o seguinte:

• Adicione um evento uppercase à tabela do App Builder
• Agora configure o lado de consumo do REST...
• Navegue até IDE > Servidores de dados > Seu servidor de dados REST > Detalhes

• Clique em + Endpoint no painel Endpoints e configure as seguintes informações

  • Nome: clientes (maiúsculas)
  • Endpoint: customers(uppercase)/{{item/clienteId}}
  • Método: POST

  • Exemplo de entrada - O App Builder espera que a entrada esteja no seguinte formato:

    {
      "item": {
        "customerId": "abcde"
      }
    }
    

• Clique em Salvar

• Clique em Descobrir
• Selecione o endpoint do seu cliente (em letras maiúsculas)
• Clique duas vezes na tabela clientes (letras maiúsculas)
• Defina a coluna customerId como a Chave Primária
• Verifique se as direções da coluna de saída e os tipos de armazenamento são conforme o esperado.

Criar regra CRUD de evento personalizada

Para chamar o endpoint do Evento Personalizado do seu Objeto REST, você precisa criar uma regra que Insere no Endpoint.

• Navegue até App Workbench > Fontes de dados > Selecione sua fonte de dados REST > Lógica
• Selecione o Endpoint do cliente (em letras maiúsculas)
• Clique em + Regra no painel Regras e defina o seguinte
  • Nome: Cliente (maiúsculas) Inserir
  • Finalidade: CRUD
  • Ação: Inserir
  • Fonte/Fonte de dados de destino: Sua fonte de dados
  • Alvo: clientes (letras maiúsculas)
• Clique em Salvar
• Na aba Tabelas:
  • Selecione a coluna customerId e defina o item/customerId correspondente como a coluna de destino

Criar evento em letras maiúsculas no objeto REST

Agora, para conectar tudo, queremos criar o evento Uppercase no objeto REST.

• Navegue até App Workbench > Fontes de Dados > Selecione sua Fonte de Dados REST > Lógica
• Clique no ícone Eventos do seu objeto REST
• No painel Eventos, clique em + Evento de Tabela
• Defina o Nome como Maiúsculas
• Clique em Salvar
• No painel Ações, clique em Registrar Existente
• Selecione a regra Inserir Clientes (Maiúsculas)
• Clique em Salvar
• Insira vinculações explícitas de customerId para customerId
• Volte para a página Eventos
• Clique duas vezes no evento Uppercase
• Defina o escopo de Atualização como Linha

Você deve estar pronto para chamar o evento personalizado. Para testar, você pode criar uma página com um Painel Multi-Linhas que tenha um botão para chamar o evento.

Classificação, paginação e filtragem - Tipo de uso

As seções a seguir sobre Classificação, Paginação e Filtragem descrevem a configuração do Tipo de Uso em Parâmetros específicos. Os exemplos fornecidos são os nomes de parâmetros que o App Builder usa quando você acessa o App Builder por meio de uma interface de API REST. Se você estiver acessando outros endpoints de servidor de API REST externa, eles terão sua própria lista exclusiva de nomes de parâmetros e formatos de valor para Classificação, Paginação e Filtragem. As informações apresentadas nestas seções ajudam você a entender o que cada um dos Tipos de Uso é e como usá-los, independentemente do nome do parâmetro usado pela API REST que você está acessando. Os parâmetros da API do App Builder usados nestas seções são documentados em API REST artigo.

Classificação

O tipo de uso que lida com a classificação é Classificação de solicitação.

• Classificação de Solicitações - Defina este tipo de uso no parâmetro REST que a API usa para classificação. O nome e o conteúdo deste parâmetro serão definidos pelo provedor da API. Para este exemplo, usamos o nome do parâmetro da API do App Builder de $sort.

Para habilitar a classificação (com um servidor REST do App Builder ):

• Navegue até IDE > Servidores de Dados
• Selecione sua fonte de dados REST
• Clique em Detalhes
• Em Parâmetros do serviço da Web, clique em + Parâmetro
• Defina o tipo como Consulta
• Defina o nome como $sort
• Deixe o valor em branco
• Defina o tipo de uso como Classificação de solicitação
• Clique no ícone marca de seleção para salvar

Agora você deve conseguir classificar quaisquer dados obtidos usando esta fonte de dados REST do App Builder.

Paginação

Os tipos de uso que lidam com paginação são Contagem de solicitações, Limite de solicitações, Deslocamento de solicitações, Número de páginas de solicitações e Total de linhas de respostas.

• Contagem de Solicitações - Defina este Tipo de Uso no parâmetro REST que a API usa para indicar que você deseja que uma contagem total de linhas seja retornada. Algumas APIs não retornam automaticamente uma contagem total em suas respostas e exigem um parâmetro específico como gatilho. Para este exemplo, usamos o nome do parâmetro da API do App Builder de $count.
• Limite de Solicitação - Defina este Tipo de Uso no parâmetro REST que a API usa para indicar que você deseja que uma contagem total de linhas seja retornada. Algumas APIs não retornam automaticamente uma contagem total em sua resposta e exigem um parâmetro específico como gatilho. Para este exemplo, usamos o nome do parâmetro da API do App Builder de $limit.
• Deslocamento de Solicitação - Defina este Tipo de Uso no parâmetro REST que a API usa para indicar em qual linha você deseja começar a retornar dados. Para este exemplo, usamos o nome do parâmetro da API do App Builder de $offset.
• Solicitar Número da Página - Defina este Tipo de Uso no parâmetro REST que a API usa para indicar em qual página você deseja começar a retornar dados. Algumas APIs usam Número da Página em vez de Deslocamento, ou podem oferecer ambos. Você deve definir apenas um para o seu endpoint, não ambos. A API do App Builder não define um parâmetro para o número da página.
• Total de Linhas de Resposta - Defina este Tipo de Uso no parâmetro REST que a API usa para retornar a contagem total de linhas na resposta. Algumas APIs não retornam automaticamente a contagem total em suas respostas e exigem um parâmetro específico como gatilho. Consulte o tipo de uso Contagem de Solicitações acima.

Para habilitar a paginação (com um servidor REST do App Builder ):

• Navegue até IDE > Servidores de Dados
• Selecione sua fonte de dados REST
• Clique em Detalhes
• Em Parâmetros do serviço da Web, clique em + Parâmetro
  • Defina o tipo como Consulta
  • Definir nome para $count
  • Defina o valor como verdadeiro
  • Defina o tipo de uso como Contagem de solicitações
  • Clique no ícone marca de seleção para salvar
• Em Parâmetros do serviço da Web, clique em + Parâmetro
  • Defina o tipo como Consulta
  • Definir nome como $limit
  • Deixe o valor em branco
  • Defina o tipo de uso como Limite de solicitação
  • Clique no ícone marca de seleção para salvar
• Em Parâmetros do serviço da Web, clique em + Parâmetro
  • Defina o tipo como Consulta
  • Definir nome para $offset
  • Deixe o valor em branco
  • Defina o tipo de uso como Solicitar compensação
  • Clique no ícone marca de seleção para salvar
• Para todos os Endpoints que suportam paginação, navegue até a tabela de Endpoint que contém o parâmetro "count".
  • No nosso exemplo acima, esta seria a tabela de clientes (obter)
  • Defina o tipo de uso da coluna de contagem como Linhas de total de resposta

O botão Carregar mais linhas agora deve funcionar para quaisquer dados obtidos deste Endpoint.

Opções de exibição do painel

Ao configurar um painel para exibir dados de Objeto REST, há opções disponíveis no Edge Case que permitem controlar como o painel exibe os registros. Você pode controlar se o App Builder carrega um número definido de registros juntamente com o botão "Carregar Mais Linhas" ou se exibe um número definido de registros juntamente com os controles de navegação de paginação na área da barra de ferramentas para carregar mais registros.

Além disso, se a configuração da API REST oferecer suporte, você poderá definir o número de registros que o App Builder exibirá inicialmente no painel.

Para carregar mais linhas

• Navegue até o painel usando o Objeto REST como Fonte
• Vá para Criar Esta Página
• Vá para Mais > Caso Extremo para o painel
• Defina a Opção de Paginação como Carregar Mais Linhas

Para habilitar a paginação

• Navegue até o painel usando o Objeto REST como Fonte
• Vá para Criar Esta Página
• Vá para Mais > Caso Extremo para o painel
• Defina a Opção de Paginação como Paginação

Para definir o número de registros iniciais carregados

• Navegue até o painel usando o Objeto REST como Origem
• Vá para Criar Esta Página
• Vá para Mais > Caso Extremo para o painel
• Defina Linhas por Solicitação como o valor numérico que você deseja carregar inicialmente

Filtragem

Os Tipos de Uso que lidam com filtragem são Filtro de Solicitação e Filtro de Solicitação (OData). Defina este tipo de uso no parâmetro REST que a API usa para filtragem. O Filtro de Solicitação é para filtragem simples, enquanto o Filtro de Solicitação (OData) é para filtragem usando o padrão OData. Este padrão define diferentes condições de filtragem. A API do App Builder usa o filtro no estilo OData, como usado em nosso exemplo. Verifique a documentação específica da sua API para ver se a filtragem OData é compatível antes de usá-la. Mais informações sobre a filtragem OData podem ser encontradas aqui nestas recomendações da API REST artigo.

Para habilitar a filtragem (com um servidor REST do App Builder ):

• Navegue até IDE > Servidores de Dados
• Selecione sua fonte de dados REST
• Clique em Detalhes
• Em Parâmetros do serviço da Web, clique em + Parâmetro
  • Defina o tipo como Consulta
  • Definir nome para $filter
  • Deixe o valor em branco
  • Defina o tipo de uso como Filtro de solicitação (OData)
  • Clique no ícone marca de seleção para salvar

Agora você deve conseguir filtrar quaisquer dados obtidos usando esta fonte de dados REST do App Builder.

A filtragem por meio de um serviço REST oferece suporte ao seguinte:

Operadores

• eq- Igual
• neq- Não igual
• gt- Maior que
• ge- Maior ou Igual
• lt - Menor que
• le - Menor ou igual

Limitações

• Sem operadores aritméticos
• Nenhum operador lógico ou/não
• Sem operadores de agrupamento
• Sem funções de consultar
• Sem aliases de parâmetros