Explicando um Script Python para a API 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 ser ainda mais curto combinando algumas das linhas de código em uma única linha.  As linhas extras 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 API Cato de uma variável de ambiente
cato_api_key = os.getenv("CATO_API_KEY")

# Criar a solicitação GraphQL a 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 administradores definidos em sua conta é: {}'.format(total))

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

Uma das razões para usar Python para o programa de exemplo é a disponibilidade de um rico conjunto de bibliotecas.  Essas bibliotecas fornecem funções e objetos que podem lidar com uma ampla gama de tarefas.  Agora analisaremos cada biblioteca importada e forneceremos 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 de biblioteca getenv para ler a chave API de uma variável de ambiente e atribuí-la a uma variável.

cato_api_key = os.getenv("CATO_API_KEY")

The Cato GraphQL server expects to receive this key in a nHTTP header.  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 API Cato é gerada através do Aplicativo de Gerenciamento Cato.  Para mais informações sobre a criação de uma chave API, consulte Gerando Chaves de API para a API Cato.

As próximas linhas de código criam um diretório Python contendo um par de chave/valor.  O valor da entrada é construído usando uma string Python multilinha 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 Cato GraphQL irá interpretar essa string como: execute a função get_total_admins, passando dois argumentos para ela (accountID e tipo) e retornando apenas o número "total" de entidades.  Ou afirmado de forma mais direta, "Retorne o número total de entidades de administradores que estão definidos para o exemplo conta # 12345".  This specific example of the admins API call  illustrates an important advantage of a GraphQL API

O fato é que a chamada admins pode retornar muito mais dados.  Por exemplo, é possível para uma aplicação solicitar que admins retorne detalhes sobre cada administrador.  No entanto, esta aplicação só precisa saber o número total de administradores.  Essa característica do GraphQL evita o que é referido como excesso de busca e pode simplificar significativamente o código necessário para implementar a aplicação.

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

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

Em seguida, um dicionário é criado para definir dois cabeçalhos HTTP.  Esses cabeçalhos são usados pelo objeto de requisição para construir uma requisição HTTP POST que o servidor GraphQL aceitará.  Sem esses cabeçalhos, as requisiçõ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. O Python usa esse objeto para determinar como ele deve criptografar as requisições HTTP e enviá-las usando Segurança a 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 à inspeção TLS upstream.

unverified_ctx = ssl._create_unverified_context()

As próximas duas linhas de código convertem o dicionário Python que contém a chamada API 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 requisiçã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 requisição para o 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 isso:

{    
    "dados" : {
         "admins" : {
              "total": 4
         }
    }
}

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

A linha final de código nesta seção do programa utiliza a função 'loads' da biblioteca json para converter a string JSON retornada em um dicionário aninhado do 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 imprimem 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