Explicando um Script Python para a API da Cato

Este programa de exemplo é curto e não inclui nenhuma lógica de tomada de decisão ou código para repetir ações.  Poderia ter sido ainda mais curto combinando algumas das linhas de código em uma única linha.  As linhas adicionais de código foram incluídas para facilitar a explicação do que está acontecendo.

# Importar código de biblioteca Python
import os
import urllib.request
import ssl
import json

# Obter a Chave da API da Cato de uma variável de ambiente
cato_api_key = os.getenv("CATO_API_KEY")

# Criar a solicitação GraphQL para ser enviada
get_total_admins = '''{
    admins (accountID: 12345) {
        total        
    }
}'''
graphql_query = {'query': get_total_admins}

# Construir a solicitação http
cato_api_url = "https://api.catonetworks.com/api/v1/graphql2"
headers = {'x-api-key': cato_api_key,
           'Content-Type':'application/json'}
unverified_ctx = ssl._create_unverified_context()
json_post = json.dumps(graphql_query)
json_post_encoded = json_post.encode()
request = urllib.request.Request(url=cato_api_url, data=json_post_encoded, headers=headers)

# Enviar a consulta e converter a resposta em um dicionário Python
response = urllib.request.urlopen(request, context=unverified_ctx, timeout=30)
json_response_encoded = response.read()
json_response = json_response_encoded.decode()
get_admins_total_result = json.loads(json_response)

# Extrair o total dos dados retornados e imprimi-lo
total = get_admins_total_result['data']['admins']['total']
print('O número total de admins definidos com sua conta é: {}'.format(total))

O diagrama fornecido abaixo mostra a sequência de eventos que ocorrem quando o programa é executado:

Uma das razões para usar Python no programa exemplo é a disponibilidade de um conjunto rico de bibliotecas.  Essas bibliotecas oferecem funções e objetos que podem lidar com uma ampla gama de tarefas.  Agora vamos passar por cada biblioteca importada e fornecer notas para explicar por que ela é necessária.

import os

import urllib.request

import ssl

import json

Esta linha de código usa a função da biblioteca getenv para ler a chave da API de uma variável de ambiente e atribuí-la a uma variável.

cato_api_key = os.getenv("CATO_API_KEY")

O servidor GraphQL da Cato espera receber esta chave em um cabeçalho HTTP.  A chave não é fornecida no documento JSON porque a especificação GraphQL não inclui autorização como parte do padrão.  Incluir autorização no documento JSON seria uma violação da especificação.  A chave da API da Cato é gerada por meio do Aplicativo de Gerenciamento da Cato.  Para mais informações sobre como criar uma chave de API, consulte Gerando Chaves de API para a API da Cato.

As próximas linhas de código criam um diretório Python contendo um par chave/valor.  O valor da entrada é construído usando uma string Python multi-linha que define a consulta que será enviada ao servidor GraphQL.

get_total_admins = '''{
    admins (accountID: 12345) {
        total    
    }
}'''
graphql_query = {'query': get_total_admins}

O servidor GraphQL da Cato interpretará esta string para significar: executar a função get_total_admins, passando dois argumentos (accountID e tipo) e retornando apenas o número "total" de entidades.  Ou dito mais diretamente, "Retornar o número total de entidades de admins que são definidos para um exemplo de conta # 12345".  Este exemplo específico da chamada de API admins ilustra uma vantagem importante de uma API GraphQL

O fato é que a chamada admins pode retornar muitos mais dados.  Por exemplo, é possível que uma aplicação solicite que admins devolva detalhes sobre cada admin.  No entanto, esta aplicação só precisa saber o número total de admins.  Esta característica do GraphQL evita o que é chamado de supercarregamento de dados e pode simplificar muito o código necessário para implementar a aplicação.

Nesta seção do programa, um objeto de solicitação é construído.  Este objeto será usado para enviar a chamada da API para o servidor GraphQL usando HTTPS. Este objeto de solicitação requer informações que são fornecidas por vários outros objetos que precisam ser criados primeiro.   Primeiramente, um objeto de string simples é construído para conter o URL do servidor GraphQL ao qual o objeto de solicitação enviará a consulta.

cato_api_url = "https://api.catonetworks.com/api/v1/graphql2"

Em seguida, é criado um dicionário que define dois cabeçalhos HTTP.  Esses cabeçalhos são usados pelo objeto de solicitação para construir uma solicitação HTTP POST que o servidor GraphQL aceitará.  Sem esses cabeçalhos, as solicitações HTTP POST seriam rejeitadas pelo servidor.

headers = {'x-api-key': cato_api_key,           
           'Content-Type':'application/json'}

A próxima linha de código cria um objeto de contexto SSL. Python usa este objeto para determinar como ele deve criptografar solicitações HTTP e enviá-las usando Segurança de Nível de Transporte (TLS). Aqui estamos criando um objeto de contexto SSL que não verifica certificados. Isso foi feito para evitar erros de certificado em redes sujeitas a inspeção upstream de TLS.

unverified_ctx = ssl._create_unverified_context()

As duas próximas linhas de código convertem o dicionário Python contendo a chamada da API da Cato em uma string e codificam essa string em bytes.  O segundo passo é necessário para permitir que a string seja transmitida pela rede.

json_post = json.dumps(graphql_query)
json_post_encoded = json_post.encode()

Finalmente, o objeto de solicitação é criado, e o programa está agora pronto para enviar a chamada get_total_admins ao servidor.

request = urllib.request.Request(url=cato_api_url, data=json_post_encoded, headers=headers)

Aqui o programa envia a solicitação ao servidor GraphQL chamando a função urlopen da biblioteca urllib.  Chamar esta função resultará no retorno de um objeto HTTPResponse.  

response = urllib.request.urlopen(request, context=unverified_ctx, timeout=30)

O objeto retornado pela função urlopen inclui um campo body que contém o documento JSON retornado pelo servidor.  Isso pode ser extraído do objeto executando seu método read, que retorna um objeto de bytes.  Este objeto de bytes é então convertido em um objeto de string chamando o método decode do objeto de bytes.

json_response_encoded = response.read()
json_response = json_response_encoded.decode()

Esta string decodificada contém um documento JSON que se parecerá com isto:

{    
    "data" : {
         "admins" : {
              "total": 4
         }
    }
}

Como você verá, o formato dos dados retornados se parece muito com o formato da solicitação que foi enviada para o servidor.  Isso é intencional e outra vantagem de usar a especificação GraphQL para implementar uma API.  Essa abordagem simplifica a codificação do aplicativo mantendo os dados retornados no mesmo formato da solicitação.

A linha final do código nesta seção do programa usa a função 'loads' da biblioteca json para converter a string JSON retornada em um dicionário aninhado Python.  

get_total_admin_result = json.loads(json_response)

As duas últimas linhas do código extraem o valor do campo total que foi retornado pelo servidor e o exibem no console. 

total = get_total_admins_result['data']['get_total_admins']['total']
print('O número total de admins definidos para sua conta é: {}'.format(total)) 

A saída será assim:

O número total de admins definidos para sua conta é: 4