Utilização das funções JSON

O FileMaker Pro 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.

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" ]

O FileMaker Pro 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:

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 tubulação e de terminação de linha, conforme mostrado em Exemplo 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:

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.

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

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 JSON em json, você pode definir tipo como JSONRaw para que o analisador JSON determine o tipo de dados de valor.

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
   ) ]

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

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" )

? * 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: JSONFormatElement ( $$JSON ) ]
If [ Left ( $result ; 1 ) = "?" ]
# $$JSON contém dados JSON inválidos.
End If

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
}
]
}
}

•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.