Объяснение скрипта Python для Cato API

Эта примерная программа короткая и не включает логику принятия решений или код для повторения действий.  Ее можно было бы сделать еще короче, объединив некоторые строки кода в одну.  Дополнительные строки кода включены для облегчения объяснения происходящего.

# Импортировать код библиотеки Python
import os
import urllib.request
import ssl
import json

# Получить API-ключ Cato из переменной среды
cato_api_key = os.getenv("CATO_API_KEY")

# Создать GraphQL-запрос для отправки
get_total_admins = '''{
    admins (accountID: 12345) {
        total    
    }
}'''
graphql_query = {'query': get_total_admins}

# Построить 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)

# Отправить запрос и преобразовать ответ в словарь 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)

# Извлечь общее количество из полученных данных и вывести его
total = get_admins_total_result['data']['admins']['total']
print('Общее количество администраторов, определенное для вашей учетной записи: {}'.format(total))

Диаграмма, представленная ниже, показывает последовательность событий, которые происходят при запуске программы:

Одной из причин использования Python для примерной программы является доступность богатого набора библиотек.  Эти библиотеки предоставляют функции и объекты, которые могут справляться с широким спектром задач.  Теперь мы пройдемся по каждой импортированной библиотеке и предоставим примечания, чтобы объяснить, почему она нужна.

import os

import urllib.request

import ssl

import json

Эта строка кода использует функцию библиотеки getenv для чтения ключа API из переменной среды и присваивает его переменной.

cato_api_key = os.getenv("CATO_API_KEY")

Сервер Cato GraphQL ожидает получения этого ключа в HTTP-заголовке.  Ключ не предоставляется в документе JSON, поскольку спецификация GraphQL не включает авторизацию как часть стандарта.  Включение авторизации в документ JSON было бы нарушением спецификации.  API-ключ Cato генерируется через Приложение Управления Cato.  Для получения дополнительной информации о создании ключа API см. Создание API ключей для Cato API.

Следующие несколько строк кода создают в Python словарь, содержащий одну пару ключ/значение.  Значение записи строится с использованием многострочной строки Python, которая определяет запрос, который будет отправлен на сервер GraphQL.

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

Сервер Cato GraphQL интерпретирует эту строку как выполнение функции get_total_admins с двумя аргументами (accountID и type) и возврат только "общее" количество сущностей.  Или, говоря более прямо, "Вернуть общее количество сущностей администраторов, определенных для примера аккаунта # 12345".  Этот конкретный пример вызова API admins иллюстрирует важное преимущество API GraphQL

По сути, вызов admins может вернуть значительно больше данных.  Например, приложение может запросить, чтобы admins вернули сведения о каждом администраторе.  Однако этому приложению нужно знать только общее количество администраторов.  Эта характеристика GraphQL позволяет избежать того, что называется перегрузкой данных и может значительно упростить код, необходимый для реализации приложения.

В этом разделе программы создается объект запроса.  Этот объект будет использован для отправки вызова API на сервер GraphQL с использованием HTTPS. Этому объекту запроса требуется информация, которая предоставляется несколькими другими объектами, которые необходимо создать в первую очередь.   Сначала создается простой строковый объект для содержания URL сервера GraphQL, на который объект запроса отправит запрос.

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

Далее создается словарь, который определяет два заголовка HTTP.  Эти заголовки используются объектом запроса для построения HTTP POST-запроса, который сервер GraphQL примет.  Без этих заголовков HTTP POST-запросы будут отвергнуты сервером.

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

Следующая строка кода создает объект SSL-контекста. Python использует этот объект, чтобы определить, как он должен шифровать HTTP-запросы и отправлять их с использованием Transport Level Security (TLS). Здесь мы создаем объект SSL-контекста, который не проверяет сертификаты. Это было сделано, чтобы избежать ошибок сертификатов в сетях, подверженных инспекции TLS на верхнем уровне.

unverified_ctx = ssl._create_unverified_context()

Следующие две строки кода конвертируют словарь Python, содержащий вызов API Cato, в строку и кодируют эту строку в байты.  Второй шаг необходим, чтобы позволить строку передавать по сети.

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

Наконец, создается объект запроса и программа теперь готова отправить вызов get_total_admins на сервер.

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

Здесь программа отправляет запрос на сервер GraphQL, вызывая функцию urlopen библиотеки urllib.  Вызов этой функции приведет к возврату объекта HTTPResponse.  

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

Объект, возвращаемый функцией urlopen, включает поле body, которое содержит документ JSON, возвращенный сервером.  Это поле можно извлечь из объекта, вызвав его метод read, который возвращает объект байтов.  Этот объект байтов затем преобразуется в строку, вызвав метод decode объекта байтов.

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

Эта декодированная строка содержит документ JSON, который будет выглядеть следующим образом:

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

Как вы увидите, формат возвращаемых данных очень похож на формат запроса, отправленного на сервер.  Это сделано намеренно и является еще одним преимуществом использования спецификации GraphQL для реализации API.  Этот подход упрощает кодирование приложения, сохраняя возвращаемые данные в том же виде, что и запрос.

Последняя строка кода в этом разделе программы использует функцию библиотеки json 'loads' для преобразования возвращенной JSON-строки в вложенный словарь Python.  

get_total_admin_result = json.loads(json_response)

Последние две строки кода извлекают значение из поля total, которое было возвращено сервером, и выводят его на консоль. 

total = get_total_admins_result['data']['get_total_admins']['total']
print('Общее количество администраторов, определенных для вашего аккаунта: {}'.format(total)) 

Вывод будет выглядеть следующим образом:

Общее количество администраторов, определенных для вашего аккаунта: 4