Criação de um app personalizado > Utilização de fórmulas e funções > Utilização das funções JSON
 

Utilização das funções JSON

O FileMaker Pro Advanced fornece várias funções de texto que permitem que sua solução analise e modifique dados JSON de outras fontes, como serviços da Web que transferem dados no formato JSON por meio de uma API REST.

Para obter mais informações sobre formato de dados JSON, consulte json.org.

Recuperação de dados JSON de um serviço da Web

Use a Inserir do URL etapa de script para acessar um serviço da Web, especificar parâmetros para as informações a serem recuperadas, enviar e receber cabeçalhos HTTP e armazenar os resultados em uma variável ou um campo.

Por exemplo, uma padaria disponibiliza sua lista de produtos aos clientes no formato JSON via uma API REST. A fórmula a seguir retorna os produtos promocionais do dia como dados JSON na variável $$JSON:

Definir variável [ $url ; "https://<bakery_domain_name>/rest/api/products" ]Inserir do URL [Verificar certificados SSL; Com diálogo: Off; $$JSON ;
$url ; "--data list=promoção" ]

Para visualizar os dados retornados em $$JSON, consulte Exemplo de dados JSON.

O FileMaker Pro Advanced também fornece várias funções utilitárias que manipulam a codificação de caracteres e a assinatura criptográfica exigida por algumas APIs REST:

HexDecode função

HexEncode função

TextDecode função

TextEncode função

Base64Decode função

Base64EncodeRFC função

CryptAuthCode função

CryptDigest função

Formatação de dados JSON

Os dados JSON não exigem espaços ou terminações de linha entre os elementos. No entanto, para facilitar a leitura dos dados ao depurar problemas, use a JSONFormatElements função, que adiciona caracteres de tabulação e de terminação de linha, conforme mostrado em Exemplo de dados JSON.

Análise de dados JSON

Use as seguintes funções JSON ao analisar dados JSON, ou seja, para obter chaves, valores ou matrizes ou objetos JSON completos que você pode processar ainda mais:

JSONGetElement – Consulta dados JSON em busca de um elemento (objeto, matriz ou valor)

JSONListKeys – Lista nomes de objeto (chaves) ou índices de matriz em dados JSON

JSONListValues – Lista valores em dados JSON

O primeiro parâmetro dessas funções, json, especifica o campo de texto, a variável ou a expressão do texto que contém dados JSON válidos para operação.

O segundo parâmetro, chaveOuÍndiceOuCaminho, especifica a parte dos dados JSON para operação:

Chave – o nome de uma chave em um objeto JSON

índice – o índice de um elemento em uma matriz JSON (o primeiro elemento possui um índice de 0)

Caminho – uma string hierárquica de nomes de chave, índices de matriz ou ambos

A seguinte sintaxe é suportada para o parâmetro chaveOuÍndiceOuCaminho.

 

parâmetro chaveOuÍndiceOuCaminho

Significa

"."

(opcional) O nível raiz, se for o primeiro caractere

".[n]"

Elementos no índice n de uma matriz no nível raiz

".nome"

A chave de um objeto chamado nome no nível raiz

".nomeA.nomeB.nomeC"

Um objeto chamado nomeC, que é descendente de nomeB e nomeA

".[3][2][1]nomeA[0]"

O primeiro elemento da matriz no objeto nomeA, que está no terceiro nível em um conjunto de matrizes aninhadas

O script de exemplo a seguir determina o número de produtos nos Exemplo de dados JSON (armazenados na variável $$JSON) usando JSONListKeys, cria um registro para cada produto e define os campos em cada registro com os valores obtidos usando JSONGetElement para cada produto.

Definir variável [ $ProductCount ; Valor:
   ValueCount (
      JSONListKeys ( $$JSON ; "padaria.produto" )
   ) ]
Definir variável [ $i; Valor: 0 ]
If [ $ProductCount > 0 ]
   Loop
      Novo registro/solicitação
      Definir campo [ Produtos::ID ;
         JSONGetElement ( $$JSON ; "padaria.produto[" & $i & "]id" ) ]
      Definir campo [ Produtos::Preço ;
         JSONGetElement ( $$JSON ; "padaria.produto[" & $i & "]preço" ) ]
      Definir campo [ Produtos::Estoque ;
         JSONGetElement ( $$JSON ; "padaria.produto[" & $i & "]estoque" ) ]
      Confirmar registros/solicitações [ Com diálogo: Desativado ]
      Definir variável [ $i ; Valor: $i + 1 ]
      Exit Loop If [ $i $ProductCount ]
   End Loop
End If

Alteração e adição de elementos em dados JSON

Para alterar valores e adicionar elementos em dados JSON, use a JSONSetElement função. Os parâmetros json e ChaveOuÍndiceOuCaminho funcionam nessa função conforme descrito em Análise de dados JSON. Se chaveOuÍndiceOuCaminho especificar um elemento existente, o valor desse elemento será alterado. Se o elemento não existir, um novo elemento será adicionado.

JSONSetElement configura o elemento especificado com o parâmetro valor. Você pode especificar qualquer valor JSON válido, de uma string ou um número simples a uma matriz ou um objeto complexo.

O parâmetro tipo especifica o tipo de dados em valor, de forma que o analisador JSON vai seguir regras estritas ao lidar com cada tipo de dados. Para obter informações sobre os tipos de dados suportados, consulte JSONSetElement função. Para inserir dados em json que já estejam formatados como um elemento JSON válido, defina type como JSONRaw.

O exemplo a seguir adiciona os pares de chave-calor de um novo produto em um objeto JSON vazio. Em seguida, o novo objeto é adicionado ao final da matriz de produtos na variável $$JSON (consulte Exemplo de dados JSON).

Definir variável [ $NewProduct ; Valor:
   JSONSetElement ( "{}" ;
      [ "id" ; "FB4" ; JSONString ] ;
      [ "nome" ; "Bolo de baunilha" ; JSONString ] ;
      [ "preço" ; 17,5 ; JSONNumber ] ;
      [ "estoque" ; 12 ; JSONNumber ] ;
      [ "categoria" ; "Bolos" ; JSONString ] ;
      [ "desconto" ; true ; JSONBoolean ]
   ) ]
Definir variável [ $NextIndex ; Valor:
   ValueCount (
      JSONListKeys ( $$JSON ; "padaria.produto" )
   ) ]
Definir variável [ $$JSON ; Valor:
   JSONSetElement (
      $$JSON ; "padaria.produto[" & $NextIndex & "]" ; $NewProduct ;
      JSONObject
   ) ]

Exclusão de elementos em dados JSON

Para excluir um elemento, use a JSONDeleteElement função. Os parâmetros json e ChaveOuÍndiceOuCaminho funcionam nessa função conforme descrito em Análise de dados JSON. O parâmetro chaveOuÍndiceOuCaminho deve especificar um elemento existente em json.

O exemplo a seguir exclui o elemento em uma matriz de produtos cuja chave "id" possui o valor "FB3" na variável $$JSON (consulte Exemplo de dados JSON).

Definir variável [ $ProductCount ; Valor:
   ValueCount (
      JSONListKeys ( $$JSON ; "padaria.produto" )
   ) ]
Definir variável [ $i ; Valor: 0 ]
If [ $ProductCount > 0 ]
   Loop
      Definir variável [ $ID ; Valor:
         JSONGetElement ( $$JSON ; "padaria.produto[" & $i & "]id" ) ]
      If [ $ID = "FB3" ]
         Definir variável [ $$JSON ; Valor:
            JSONDeleteElement ( $$JSON ; "padaria.produto[" & $i & "]" ) ]
         Sair do script [Text Result: 0 ]
      End If
      Definir variável [ $i ; Valor: $i + 1 ]
      Exit Loop If [ $i $ProductCount ]
   End Loop
End If

Como lidar com erros em dados JSON

Se ocorrer um erro durante a análise do parâmetro json, as funções JSON retornarão "?" seguido por uma mensagem de erro do analisador JSON.

Por exemplo, quando ":" após "padaria" está ausente no Exemplo de dados JSON, esse cálculo

JSONGetElement ( $$JSON ; "padaria.produto[0]id" )

retornará esta mensagem de erro:

? * Line 3, Column 2
  Missing ':' after object member name
* Line 13, Column 5
  Extra non-whitespace after JSON value.

Para determinar se os dados JSON são válidos antes de usá-los, use a JSONFormatElements função e teste se o primeiro caractere é "?". Por exemplo:

Definir variável [ $result ; Valor: JSONFormatElements ( $$JSON ) ]
If [ Left ( $result ; 1 ) = "?" ]
   # $$JSON contém dados JSON inválidos.
End If

Exemplo de dados JSON

O exemplo de dados JSON a seguir contém um objeto "padaria" que possui uma matriz de três objetos "produto", cada um com vários pares de chave-valor.

{
"padaria" :
{
"produto" :
[
{
"id" : "FB1",
"nome" : "Rosquinhas",
"preço": 1,99,
"estoque" : 43,
"categoria" : "Pães",
"desconto" : true
},
{
"id" : "FB2",
"preço": 22,5,
"nome" : "Bolo de chocolate",
"estoque" : 23,
"categoria" : "Bolos",
"desconto" : true
},
{
"id" : "FB3",
"preço": 3,95,
"nome" : "Baguete",
"estoque" : 34,
"categoria" : "Pães",
"desconto" : true
}
]
}
}

Notas 

O analisador JSON preserva a ordem dos elementos em uma matriz, mas não a ordem dos elementos em um objeto. Por isso, as funções JSON podem retornar elementos em um objeto em uma ordem diferente da especificada.

Tópicos relacionados 

Funções de texto

Funções de Container