Como formatar as saídas do conector HTTP

Saiba como estruturar as saídas do conector HTTP.

Visão geral

O editor de funções de conector no Tulip permite estruturar os dados retornados pelas funções de conector para que sejam úteis e utilizáveis em seus aplicativos. Neste artigo, abordaremos os conceitos básicos de formatação de funções de conector Outputs, apresentando a você:

• O conceito de "Saída" de um conector
• Ferramentas disponíveis para formatação de saídas
• Vários formatos de saída comuns

O que são saídas?

As saídas são usadas para definir e estruturar os resultados de retorno da função do conector. É por meio delas que você extrai as informações importantes para seus aplicativos de um corpo de retorno HTTP maior.

Como estruturar as saídas

Localize a seção Outputs (Saídas ) no canto inferior esquerdo do Connector Function Editor.

Para começar a adicionar saídas, clique em Add Function Outputs (Adicionar saídas de função).

É uma boa prática nomear suas saídas com um rótulo que possa ser identificado. Esses nomes aparecem como variáveis nos aplicativos, portanto, é importante poder distingui-los.

Para entender os resultados de uma solicitação HTTP, é importante primeiro entender a forma de um objeto retornado nos resultados do teste. O diagrama abaixo ilustra como os resultados são divididos em seções de Objetos e Matrizes.

:::(Info) (OBSERVAÇÃO) Se você nunca trabalhou com JSON antes, talvez não esteja familiarizado com dois tipos de dados essenciais, objetos e matrizes. Matrizes são listas de valores do mesmo tipo. Por exemplo, [1,2,3,5] ou [oak, elm, alder, hickory]. Os valores em matrizes estão contidos entre colchetes, [ ]. Os objetos são um tipo de dados para manter pares de chave:valor. Os pares chave:valor em um objeto podem ser de vários tipos diferentes, inclusive matrizes e objetos aninhados. Os objetos são contidos entre colchetes, { }. :::

Para obter mais informações sobre objetos e matrizes, consulte Entendendo matrizes e objetos nas saídas de funções do Connector.

Notação de pontos

Para conectores HTTP, as saídas usam um formato chamado Dot Notation. A notação de ponto permite acessar valores dentro de um objeto. A notação de ponto é útil para extrair apenas o que você precisa de um grande corpo de resposta JSON e oferece mais flexibilidade na formatação das funções do conector HTTP. Simplificando: é um formato estruturado com base em valores que são aninhados uns nos outros.

Vamos detalhar como a notação de ponto é usada nas saídas do conector com um exemplo.

O objeto de exemplo a seguir, chamado "employees", contém uma matriz de objetos com detalhes sobre cada funcionário. Se quisermos acessar apenas o título de cada funcionário, usaremos a sintaxe: employees.title. Estamos usando um Dot para acessar os valores associados às chaves nas quais estamos interessados. Digamos que desejássemos obter apenas o primeiro resultado. Especificaríamos isso adicionando a posição do índice entre o nome do objeto principal, "employees", e o valor no qual estamos interessados, "title". A sintaxe seria semelhante a: employees.0.title. No caso de objetos mais complexos, talvez seja necessário ir além do objeto para obter as informações desejadas.

Vamos dar um passo adiante com outro exemplo. Nesse caso, digamos que estejamos interessados em criar uma função de conector para extrair informações associadas a artigos na Knowledge Base. Nosso conector retorna o seguinte objeto JSON de nome "data" que contém dados sobre um determinado artigo:

Se quisermos extrair apenas, por exemplo, o ID, o título, a versão e se o artigo está oculto ou não. Precisaríamos especificar isso usando saídas. Vamos demonstrar como a notação de ponto aparece na seção de saídas do editor:

Para extrair resultados como "id" e "title", precisamos especificar onde esses resultados estão no JSON. O corpo da saída é "data", correspondente ao primeiro menu suspenso na seção Resultados do teste. Cada resultado dentro do menu suspenso "data" é aninhado dentro desse objeto. Na seção Outputs (Saídas ), um ponto significa ir uma camada além do objeto "data".

:::(Info) (OBSERVAÇÃO) Não importa se o ponto é colocado no corpo ou na frente de propriedades individuais, desde que haja um ponto separando cada camada do JSON:

Quando clicamos na guia Outputs (Saídas ) na seção Test Results (Resultados do teste ), as saídas filtram o restante dos dados para que vejamos apenas as informações que nos interessam.

Outra maneira de escrever suas saídas é em uma única linha. Isso mostra o caminho completo em uma consulta.

Para facilitar a escrita do caminho de saída, você também pode clicar em uma linha de dados para adicioná-la como uma nova saída.

Para obter mais informações sobre o uso da notação de pontos, consulte este recurso: Como usar a notação de ponto para acessar informações em um objeto JSON.

Resultados de saída

Há várias maneiras de estruturar as saídas, mas a forma de fazê-lo depende inteiramente do que você deseja fazer com os dados em seus aplicativos. Antes de começar a estruturar as saídas, pense em seu objetivo final. Você deseja exibir vários tipos de dados em variáveis individuais? Ou você tem os mesmos tipos de dados em uma matriz que deseja simplesmente analisar para obter informações relevantes?

Os exemplos a seguir são todos baseados na mesma função de conector e, em cada caso, o corpo dos resultados do teste é o mesmo. No entanto, os resultados variam de acordo com a forma como são estruturados.

O exemplo a seguir mostra como as saídas do conector para o caminho JSON data.hits.slug. Da forma como essa saída está estruturada, o conector retorna uma grande matriz de todos os slugs de URL para artigos da Base de Conhecimento. Em nossos aplicativos, esse retorno do conector poderá ser acessado em uma variável de matriz.

Podemos estruturar as saídas como uma lista de objetos e extrair tipos de dados individuais dos resultados, criando vários objetos de dados que podem ser visíveis individualmente nos aplicativos.

As listas de objetos são objetos que contêm vários tipos de dados aninhados dentro delas. Use listas de objetos clicando no tipo de saída e alternando o botão List (Lista) no canto direito.

Quando você tem uma lista de objetos, pode usar facilmente diferentes tipos de dados como partes individuais de dados em seus aplicativos.

Se voltarmos ao exemplo acima, vamos transformar nosso caminho de saída data.hits.slug em uma lista. Você pode ver nos resultados abaixo que a Tulip está estruturando esse retorno do conector como uma matriz de slugs, com cada posição de índice listada ao lado de cada valor.

Com esse entendimento das saídas em mente, agora você pode mapear as saídas para suas próprias funções de conector e otimizar os resultados retornados de seus conectores!

Leitura adicional

• Uso de conectores HTTP em aplicativos
• Exibição de listas interativas de registros de tabela ou saída de conector em aplicativos

Encontrou o que estava procurando?

Você também pode ir para community.tulip.co para postar sua pergunta ou ver se outras pessoas tiveram uma pergunta semelhante!