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

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

# Importировать библиотечный код 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)

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

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

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

import os

import urllib.request

import ssl

import json

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

cato_api_key = os.getenv("CATO_API_KEY")

The Cato GraphQL server expects to receive this key in a nHTTP header.  Ключ не предоставляется в документе JSON, так как спецификация GraphQL не включает авторизацию как часть стандарта.  Включение авторизации в документ JSON было бы нарушением спецификации.  Ключ API Cato генерируется через Приложение Управления Cato.  Для получения дополнительной информации о создании ключа API, см. Генерация API-ключей для API Cato.

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

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

Сервер Cato GraphQL интерпретирует эту строку следующим образом: выполните функцию get_total_admins, передавая ей два аргумента (accountID и тип) и возвращая только число сущностей "всего".  Или, выражаясь более прямо, "Верните общее количество сущностей администраторов, определенных для учетного примера # 12345".  This specific example of the admins API call  illustrates an important advantage of a GraphQL API

Фактически, вызов 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 запросы и отправлять их с использованием Транспорт {Слоя Безопасности (TLS)}. Здесь мы создаем объект контекста SSL, который не проверяет сертификаты. Это сделано для избежания ошибок сертификата в сетях, подверженных инспекции TLS.

unverified_ctx = ssl._create_unverified_context()

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

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