Utilização das funções JSON

O FileMaker Pro fornece várias funções de texto que permitem que seu app personalizado 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 mais informações sobre o formato de dados JSON, consulte json.org.

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 Função JSONFormatElements, 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

Os dois tipos a seguir de sintaxe para o parâmetro chaveOuÍndiceOuCaminho são compatíveis: notação de pontos e notação de colchetes.

A diferença entre a notação de ponto e colchetes é que, em vez de usar pontos (.) para separar nomes de chaves, a notação entre colchetes envolve nomes de chaves com aspas simples (') e colchetes ([]). Você pode usar as duas notações em chaveOuÍndiceOuCaminho. No entanto, será necessário usar a notação de colchetes se os nomes de chave incluírem pontos para que o analisador JSON possa identificar corretamente os nomes completos. Por exemplo, o nome de uma chave na raiz de um objeto JSON for "layout.response", então o chaveOuÍndiceOuCaminho precisará ser "['layout.response']".

O script de exemplo a seguir cria um registro para cada produto em uma matriz JSON. Supondo que os Exemplo de dados JSON estejam armazenados na variável $$JSON, o script usa JSONListValues para obter o conteúdo da matriz de produtos como uma lista de valores e usa ValueCount para determinar o número de produtos na lista. Criando um registro para um produto a cada vez no loop, o script usa GetValue para obter o objeto JSON para um produto da lista e define os campos para os valores obtidos usando JSONGetElement. Como as funções JSON analisam todo o objeto JSON passado para elas, talvez seja mais eficiente usar as funções JSON em objetos JSON menores dentro de um loop que é repetido muitas vezes.

Definir variável [ $ProductList ; Valor: JSONListValues ( $$JSON ; "padaria.produto" ) ]
Definir variável [ $ProductCount ; Valor: ValueCount ( $ProductList ) ]
Definir variável [ $i; Valor: 1 ]
If [ $ProductCount > 0 ]
   Loop [ Liberar: Sempre ]
      Novo registro/solicitação
      Definir variável [ $Product ; Valor: GetValue ( $ProductList ; $i ) ]
      Definir campo [ Produtos::ID ; JSONGetElement ( $Product ; "id" ) ]
      Definir campo [ Produtos::Preço ; JSONGetElement ( $Product ; "preço" ) ]
      Definir campo [ Produtos::Estoque ; JSONGetElement ( $Product ; "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 Função JSONSetElement. 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 os tipos de dados compatíveis, consulte a Função JSONSetElement. 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 ] ; 
      [ "stock" ; 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 
   ) ]

Outra função JSON que cria um elemento JSON é a função Função JSONMakeArray. Ele converte uma lista de valores em uma matriz JSON. Para aceitar dados formatados de maneiras diferentes, esta função permite que você especifique o caractere que separa cada valor e o tipo de dados JSON a ser usado.

Exclusão de elementos em dados JSON

Para excluir um elemento.use a Função JSONDeleteElement. 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 [ Liberar: Always ]
      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 [ Resultado do texto: 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 a chave "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 Função JSONFormatElements 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

Outra opção para determinar se os dados JSON são válidos antes de usá-los, use a Função JSONGetElementType e verifique se todo o objeto é um objeto JSON. Por exemplo:

Definir variável [ $result ; Valor: JSONGetElementType( $$JSON, "" ) ]
If [ $result ≠ JSONObject ]
    # $$JSON contém dados JSON inválidos.
End If

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

Use a Etapa de script Inserir do URL 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.example.com/rest/api/products" ]

Inserir do URL [ Com diálogo: Desativado; Destino: $$JSON ; $url ; Verificar certificados SSL ; opções cURL: "--data list=specials" ]

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

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:

• Função HexDecode

• Função HexEncode

• Função TextDecode

• Função TextEncode

• Função Base64Decode

• Função Base64EncodeRFC

• Função CryptAuthCode

• Função CryptDigest

• Função CryptGenerateSignature

• Função CryptVerifySignature

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.

• Nos dados JSON, os valores numéricos fracionários devem usar ponto "." como separador decimal, independentemente do separador especificado pelos formatos de sistema do computador ou dos formatos usados na criação do arquivo do FileMaker Pro.

Tópicos relacionados

• Funções JSON

• Funções de texto

• Funções de container