Objeto REST¶

Visão Geral¶

Os objetos REST permitem que os desenvolvedores do Vinyl façam uso de APIs REST de maneira semelhante aos objetos de dados do Vinyl. Objetos REST suportam o seguinte:

• Operações CRUD
• Integração com vários controles de Vinyl, como painéis multi-linha/linha única, listas
• Eventos personalizados
• Ordenação
• Filtragem (string de consultar de filtro de 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 Vinyl.

Endpoints CRUD¶

Para uma API REST estilo CRUD, você desejará configurar Endpoints que permitem que registros sejam criados, lidos, atualizados e excluídos. Em geral, isso significa configurar os seguintes Endpoints:

Exemplo de Configuração da API REST do Vinyl¶

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

Esta API REST é exposta no endpoint "northwinds" como um recurso chamado "clientes". Assim, a URL para atingir este endpoint seria:

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

Certifique-se de ter configurado a API REST em 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
• Volte para a página anterior
• Selecione seu endpoint clientes (get)
• Observe que existem três tabelas de saída
• Clique duas vezes na tabela clientes (get)/items
• Defina a coluna customerId como 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 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: clientes (inserir)
  • Endpoint: clientes
  • Método: POST

  • Sample Input - Vinyl 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 Discover funcione. Exclua o registro no servidor Vinyl REST API ou configure e importe o endpoint"Excluir".
• Volte para a página anterior
• Selecione seus clientes (inserir) Endpoint
• Clique duas vezes na tabela clientes (inserir)
• Defina a coluna customerId como chave primária
• Defina as colunas customerId, name e daysActive para a direção Input/Output.
  • Quando criamos um registro passamos nas três colunas (Input). O servidor Vinyl REST API ecoa essas colunas no JSON (saída) retornado. Se por algum motivo o servidor ecoou um valor diferente do que enviamos (talvez formatando uma string), desejaremos 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: POSTAR

• Entrada de amostra - O Vinyl 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 clientes (atualização)
• Clique duas vezes na tabela clientes (atualização)
• Defina a coluna customerId como chave primária
• Defina as colunas customerId, name e daysActive para a direção Input/Output.
• Certifique-se de que as colunas estejam usando o tipo de armazenamento esperado

Objeto REST¶

Depois que seus Endpoints CRUD forem 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 > Superobjetos
• Clique em + Objeto REST
• Nomeie seu objeto REST... assumiremos Clientes
• Clique no ícone da marca de seleção para salvar
• Clique no ícone de edição de lápis
• Ative 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 Composição única
• Adicione a tabela clientes (get)/items ao painel Tabelas
• Clique no "*" botão para adicionar todas as colunas
• Clique duas vezes na coluna customerId e defina como Chave primária
• Percorra cada coluna por vez e defina o Tipo de dados lógicos adequadamente
• Observe que se você clicar em Resultados antes de configurar o Many Comp (abaixo), você receberá uma mensagem de erro "Sem sequência". Você precisará configurar o objeto Many primeiro.
• Retorne à tela Objetos REST

Configurar Muitos Comp¶

• Clique no ícone Muitos Comp
• Adicione a tabela clientes (get)/items ao painel Tabelas
• Clique no "*" botão para adicionar todas as colunas
• Defina as colunas Target com seus nomes de coluna correspondentes
• Clique duas vezes na coluna customerId e defina 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 Endpoint e Bindings conforme tabela abaixo:

Agora você deve conseguir clicar no botão Resultados em seu objeto REST e adicionar/excluir/atualizar linhas.

Eventos Personalizados¶

Os objetos REST podem definir eventos personalizados de forma semelhante a outros objetos de dados do Vinyl. 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
• Adicione um evento personalizado ao objeto REST

Criar Endpoint de Evento Personalizado¶

No Vinyl, 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/customerId}}

Para configurar isso, faça o seguinte:

• Adicione um evento maiúsculo à tabela Vinyl
• 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/customerId}}
  • Método: POST

  • Sample Input - Vinyl espera que a entrada esteja no seguinte formato:

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

• Clique em Salvar

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

Criar Regra CRUD de Evento Personalizado¶

Para chamar o endpoint do evento personalizado a partir do seu objeto REST, você precisa criar uma regra que seja inserida no Endpoint.

• Navegue até App Workbench > Fontes de dados > Selecione sua fonte de dados REST > Lógica
• Selecione o Endpoint cliente (maiúsculas)
• Clique em + Regra no painel Regras e defina o seguinte
  • Nome: Cliente (maiúsculas) Inserir
  • Objetivo: CRUD
  • Ação: Inserir
  • Fonte de dados de origem/destino: 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 de destino

Criar Evento em 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 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 maiúsculo
• Defina o escopo de atualização como Row

Você deve estar pronto para chamar o evento personalizado. Para testar, você pode criar uma página com um Painel Multi-Row que possui 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 de Tipo de uso em parâmetros específicos. Os exemplos dados são os nomes dos parâmetros que o Vinyl usa quando você acessa o Vinyl por meio de uma interface REST API. Se você estiver acessando outros endpoints externos do servidor REST API, 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 são para ajudá-lo a entender o que 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 Vinyl usados nessas seções estão documentados posteriormente na API REST artigo.

Ordenação¶

O tipo de uso que trata da classificação é Solicitar classificação.

• Solicitar classificação – Defina esse 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 Vinyl de $sort.

Para Ativar a Classificação (com um Servidor Vinyl REST):¶

• Navegue até IDE > Servidores de dados
• Selecione sua fonte de dados REST
• Clique em Detalhes
• Em Parâmetros de 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 Solicitar classificação
• Clique no ícone marca de seleção para salvar

Agora você deve ser capaz de classificar todos os dados obtidos usando esta fonte de dados REST do Vinyl.

Paginação¶

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

• Contagem de solicitações - Defina esse tipo de uso no parâmetro REST que a API usa para indicar que você gostaria que uma contagem total de linhas fosse 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 Vinyl de $count.
• Limite de solicitação - Defina esse tipo de uso no parâmetro REST que a API usa para indicar que você gostaria que uma contagem total de linhas fosse 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 Vinyl de $limit.
• Request Offset - Defina esse tipo de uso no parâmetro REST que a API usa para indicar em qual linha você gostaria de começar a retornar dados. Para este exemplo, usamos o nome do parâmetro da API Vinyl de $offset.
• Request Page Number - Defina esse tipo de uso no parâmetro REST que a API usa para indicar em qual página você gostaria de começar a retornar dados. Algumas APIs usam Page Number em vez de Offset ou podem oferecer ambos. Você deve definir apenas um para o seu endpoint, não ambos. A API Vinyl não define um parâmetro para número de página.
• Total de linhas de resposta - Defina esse tipo de uso no parâmetro REST que a API usa para retornar uma contagem total de linhas na resposta. Algumas APIs não retornam automaticamente uma contagem total em suas respostas e exigem um parâmetro específico como gatilho. Consulte o tipo de uso da contagem de solicitações acima.

Para Ativar a Paginação (com um Servidor Vinyl REST):¶

• Navegue até IDE > Servidores de dados
• Selecione sua fonte de dados REST
• Clique em Detalhes
• Em Parâmetros de serviço da Web, clique em + Parâmetro
  • Defina o tipo como Consulta
  • Defina o nome como $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 de serviço da 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ção
  • Clique no ícone marca de seleção para salvar
• Em Parâmetros de serviço da 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 Solicitar deslocamento
  • Clique no ícone marca de seleção para salvar
• Para todos os Endpoints que suportam paginação, navegue até a tabela Endpoint 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 de resposta

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

Opções de Exibição do Painel¶

Quando você configura um painel para exibir dados do objeto REST, há opções disponíveis em Edge Case que fornecem controle sobre como o painel exibe os registros. Você pode controlar se o Vinyl carrega um determinado número de registros junto com um botão Carregar mais linhas ou se ele exibe um determinado número de registros junto com os 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ê poderá definir o número de registros que o Vinyl exibe 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 > Edge Case para o painel
• Defina a Opção de paginação para Carregar mais linhas

Para Ativar a Paginação¶

• Navegue até o painel usando o objeto REST como fonte
• Vá para Criar esta página
• Vá para Mais > Edge Case para o painel
• Defina a Opção de paginação como Paging

Para Definir o Número de Registros Iniciais Carregados¶

• Navegue até o painel usando o objeto REST como fonte
• Vá para Criar esta página
• Vá para Mais > Edge Case para o painel
• Defina Rows Per Request como o valor numérico que você deseja carregar inicialmente

Filtragem¶

Os tipos de uso que tratam da filtragem são Filtro de Solicitação e Filtro de Solicitação (OData). Configure esse 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 filtro. A API Vinyl usa filtro de estilo OData conforme usado em nosso exemplo. Verifique a documentação específica da 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 Ativar a Filtragem (com um Servidor Vinyl REST):¶

• Navegue até IDE > Servidores de dados
• Selecione sua fonte de dados REST
• Clique em Detalhes
• Em Parâmetros de serviço da Web, clique em + Parâmetro
  • Defina o tipo como Consulta
  • Defina o nome como $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 ser capaz de filtrar todos os dados obtidos usando esta fonte de dados REST do Vinyl.

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 ou/não operadores lógicos
• Sem operadores de agrupamento
• Sem funções de consultar
• Sem aliases de parâmetro