Ir para o conteúdo

Objeto REST no Jitterbit App Builder

Visão Geral

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

  • Operações CRUD
  • Integração com vários Controles do App Builder, como Painéis de Múltiplas Linhas/Linha Única, Listas
  • Eventos Personalizados
  • Ordenação
  • Filtragem (string de consulta 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 com seu aplicativo do App Builder.

Endpoints CRUD

Para uma API REST no estilo CRUD, você vai querer configurar Endpoints que permitam que registros sejam Criados, Lidos, Atualizados e Excluídos. Em geral, isso significa configurar os seguintes Endpoints:

Operação Método URL de Exemplo
Criar POST para um recurso de coleção https://api.example.com/rest/v1/customers
Ler GET de um recurso de coleção https://api.example.com/rest/v1/customers
Atualizar PUT ou POST para um recurso de item https://api.example.com/rest/v1/customers/<customerId>
Excluir DELETE de um recurso de item https://api.example.com/rest/v1/customers/<customerId>

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

Os passos abaixo demonstram como configurar endpoints CRUD para um servidor REST do App Builder. Neste exemplo, vamos assumir que existe uma tabela como:

Coluna Atributos Tipo Lógico
CustomerId Chave Primária String
Nome String
DiasAtivos Inteiro

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

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

Certifique-se de que você configurou a API REST em seu servidor e criou a Fonte de Dados REST antes de continuar.

Endpoint de Leitura

  • 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: customers (get)
    • Endpoint: customers
    • Método: GET
  • Clique em Salvar
  • Clique em Descobrir
  • Volte para a página anterior
  • Selecione seu endpoint customers (get)
  • Observe que há três tabelas de Saída
  • Clique duas vezes na tabela customers (get)/items
  • Defina a coluna customerId como a Chave Primária
  • Certifique-se de que as colunas estão usando o tipo de armazenamento esperado
  • Clique em Resultados e verifique se os dados retornados estã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: customers (insert)
    • Endpoint: customers
    • Método: POST

    • Entrada de Exemplo - 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 antes que o Descobrir funcione. Exclua o registro no servidor da API REST do App Builder ou configure e importe o endpoint "Excluir".
  • Volte para a página anterior
  • Selecione seu Endpoint customers (insert)
  • Clique duas vezes na tabela customers (insert)
  • Defina a coluna customerId como a Chave Primária
  • Defina as colunas customerId, name e daysActive para a direção Entrada/Saída.
    • 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 ecoar um valor diferente do que enviamos (talvez formatando uma string), queremos que nosso registro contenha os valores retornados.
  • Certifique-se de que as colunas estão usando o tipo de armazenamento esperado

Atualização

  • 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: customers (atualizar)
  • Endpoint: customers/{{item/customerId}}
  • Método: POST

  • Entrada de Exemplo - 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
  • Volte para a página anterior
  • Selecione seu endpoint customers (atualizar)
  • Clique duas vezes na tabela customers (atualizar)
  • Defina a coluna customerId como a Chave Primária
  • Defina as colunas customerId, name e daysActive para a direção Entrada/Saída.
  • Certifique-se de que as colunas estão usando o tipo de armazenamento esperado

Objeto REST

Uma vez que seus Endpoints CRUD tenham sido configurados, você pode 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... vamos assumir Clientes
  • Clique no ícone de marca de verificação para salvar
  • Clique no ícone de lápis para editar
  • Ative Inserir, Atualizar e Excluir clicando, conforme apropriado
  • Clique em prosseguir ou no ícone de marca de verificação para salvar

Configurar comp único

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

Configurar comp muitos

  • Clique no ícone Comp Muitos
  • Adicione a tabela customers (get)/items ao painel de Tabelas
  • Clique no botão "*" para adicionar todas as colunas
  • Defina as colunas Alvo para seus nomes de coluna correspondentes
  • Clique duas vezes na coluna customerId e defina como uma 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ções CRUD, configure o Endpoint e os Bindings conforme a tabela abaixo:

Operação CRUD Endpoint Binding (Objeto REST) Binding (Endpoint)
Deletar customers (delete) customerId item/customerId
Inserir customers (insert) customerId item/customerId
" " daysActive item/daysActive
" " name item/name
Atualizar customers (update) customerId item/customerId
" " daysActive item/daysActive
" " name item/name

Agora você deve ser capaz de clicar no botão Resultados no seu Objeto REST e adicionar/deletar/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á:

  • Criar um Endpoint de evento personalizado
  • Criar 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 "uppercase" na tabela "customers":

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

Para configurar isso, faça o seguinte:

  • Adicione um evento uppercase à tabela do App Builder
  • Agora configure o lado de consumo 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: customers (uppercase)
    • Endpoint: customers(uppercase)/{{item/customerId}}
    • Método: POST
    • Entrada de Exemplo - O App Builder espera que a entrada esteja no seguinte formato:

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

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

Criar regra CRUD de evento personalizado

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

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

Criar evento em maiúsculas no objeto REST

Agora, para conectar tudo, queremos criar o evento em Maiúsculas no Objeto REST.

  • Navegue até App Workbench > Fontes de Dados > Selecione Sua Fonte de Dados REST > Lógica
  • Clique no ícone Eventos para seu Objeto REST
  • No painel de Eventos, clique em + Evento de Tabela
  • Defina o Nome como Maiúsculas
  • Clique em Salvar
  • No painel de Ações, clique em Registrar Existente
  • Selecione a Regra Inserir Clientes (maiúsculas)
  • Clique em Salvar
  • Insira ligações explícitas para customerId para customerId
  • Volte para a página de Eventos
  • Clique duas vezes no evento Maiúsculas
  • 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 de Múltiplas 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 definição do Tipo de Uso em Parâmetros específicos. Os exemplos dados são os nomes dos Parâmetros que o App Builder usa quando você acessa o App Builder através de uma interface de API REST. Se você estiver acessando outros endpoints de servidor API REST externos, eles terão sua própria lista única de nomes de Parâmetros e formatos de valor para Classificação, Paginação e Filtragem. As informações apresentadas nessas seções são para ajudá-lo a entender quais são 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 nessas seções estão documentados em mais detalhes no artigo API REST.

Ordenação

O Tipo de Uso que lida com ordenação é Request Sort.

  • Request Sort - Defina este tipo de uso no parâmetro REST que a API utiliza para ordenaçã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 como $sort.

Para habilitar a ordenaçã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 Web Service, clique em + Parâmetro
  • Defina o Tipo como Query
  • Defina o Nome como $sort
  • Deixe o Valor em branco
  • Defina o Tipo de Uso como Request Sort
  • Clique no ícone de marca de verificação para salvar

Agora você deve ser capaz de ordenar qualquer dado que seja recuperado usando esta fonte de dados REST do App Builder.

Paginação

Os Tipos de Uso que lidam com paginação são Request Count, Request Limit, Request Offset, Request Page Number e Response Total Rows.

  • Request Count - Defina este Tipo de Uso no parâmetro REST que a API utiliza para indicar que você gostaria de receber uma contagem total de linhas. Algumas APIs não retornam automaticamente uma contagem total em sua resposta e requerem um parâmetro específico como um gatilho. Para este exemplo, usamos o nome do parâmetro da API do App Builder como $count.
  • Request Limit - Defina este Tipo de Uso no parâmetro REST que a API utiliza para indicar que você gostaria de receber um limite na contagem total de linhas. Algumas APIs não retornam automaticamente uma contagem total em sua resposta e requerem um parâmetro específico como um gatilho. Para este exemplo, usamos o nome do parâmetro da API do App Builder como $limit.
  • Request Offset - Defina este Tipo de Uso no parâmetro REST que a API utiliza para indicar a partir de qual linha você gostaria de começar a retornar dados. Para este exemplo, usamos o nome do parâmetro da API do App Builder como $offset.
  • Request Page Number - Defina este Tipo de Uso no parâmetro REST que a API utiliza para indicar em qual página você gostaria de começar a retornar dados. Algumas APIs usam o Número da Página em vez de Offset, ou podem oferecer ambos. Você deve definir apenas um para seu endpoint, não ambos. A API do App Builder não define um parâmetro para o número da página.
  • Response Total Rows - Defina este Tipo de Uso no parâmetro REST que a API utiliza para retornar uma contagem total de linhas na resposta. Algumas APIs não retornam automaticamente uma contagem total em sua resposta e requerem um parâmetro específico como um gatilho. Veja o tipo de uso Request Count 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 Web clique em + Parâmetro
    • Defina o Tipo como Consulta
    • Defina o Nome como $count
    • Defina o Valor como true
    • Defina o Tipo de Uso como Contagem de Solicitações
    • Clique no ícone de marca de verificação para salvar
  • Em Parâmetros do Serviço Web clique em + Parâmetro
    • Defina o Tipo como Consulta
    • Defina o Nome como $limit
    • Deixe o Valor em branco
    • Defina o Tipo de Uso como Limite de Solicitações
    • Clique no ícone de marca de verificação para salvar
  • Em Parâmetros do Serviço Web clique em + Parâmetro
    • Defina o Tipo como Consulta
    • Defina o Nome como $offset
    • Deixe o Valor em branco
    • Defina o Tipo de Uso como Deslocamento de Solicitações
    • Clique no ícone de marca de verificação para salvar
  • Para todos os Endpoints que suportam paginação, navegue até a tabela de Endpoints que contém o parâmetro "count".
    • No nosso exemplo acima, esta seria a tabela de clientes (get)
    • Defina o tipo de uso da coluna de contagem como Total de Linhas da Resposta

O botão Carregar Mais Linhas deve agora funcionar para qualquer dado buscado deste Endpoint.

Opções de exibição do painel

Quando você configura um painel para exibir dados de Objetos REST, há opções disponíveis em Edge Case que fornecem controle sobre como o painel exibe os registros. Você pode controlar se o App Builder carrega um número definido de registros junto com um botão Carregar Mais Linhas, ou se exibe um número definido de registros junto com controles de navegação de paginação na região da barra de ferramentas para carregar mais registros.

Além disso, se a configuração da API REST suportar, você pode definir o número de registros que o App Builder exibe inicialmente no painel.

Para carregar mais linhas
  • Navegue até o painel usando o Objeto REST como Fonte
  • Vá para Projetar Esta Página
  • Vá para Mais > Edge Case 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 Projetar Esta Página
  • Vá para Mais > Edge Case 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 Fonte
  • Vá para Design This Page
  • Acesse More > Edge Case para o painel
  • Defina Rows Per Request para o valor numérico que você deseja carregar inicialmente

Filtragem

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

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

  • Navegue até IDE > Data Servers
  • Selecione sua fonte de dados REST
  • Clique em Details
  • Em Parâmetros do Serviço Web, clique em + Parameter
    • Defina o Tipo como Query
    • Defina o Nome como $filter
    • Deixe o Valor em branco
    • Defina o Tipo de Uso como Request Filter (OData)
    • Clique no ícone de checkmark para salvar

Agora você deve ser capaz de filtrar qualquer dado que seja buscado usando esta fonte de dados REST do App Builder.

A filtragem via um Serviço REST suporta o seguinte:

Operadores

  • eq – Igual
  • neq – Diferente
  • gt – Maior Que
  • ge – Maior Que ou Igual
  • lt – Menor Que
  • le – Menor Que ou Igual

Limitações

  • Sem operadores aritméticos
  • Sem operadores lógicos ou/não
  • Sem operadores de agrupamento
  • Sem funções de consulta
  • Sem aliases de parâmetros