解释一个针对卡托 API 的 Python 脚本

此示例程序简单，不包括任何决策逻辑或代码来重复操作。  通过将一些代码行合并到单行中，可以使其更短。  额外的代码行被包含以便于解释正在发生的事情。

# 导入 Python 库代码
import os
import urllib.request
import ssl
import json

# 从环境变量中获取 Cato API 密钥
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 服务器期望在 nHTTP 头中接收此密钥。  由于 GraphQL 规范不将授权作为标准的一部分，因此密钥未在 JSON 文档中提供。  在 JSON 文档中包含授权将违反规范。  Cato API 密钥通过 Cato 管理应用程序生成。  有关创建 API 密钥的更多信息，请参见生成 Cato API 的 API 密钥。

接下来的几行代码创建一个包含一个键/值对的 Python 目录。  条目值是使用定义将发送到 GraphQL 服务器的查询的 Python 多行字符串构建的。

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

Cato GraphQL 服务器将解读此字符串为：执行函数get_total_admins，向其传递两个参数（accountID 和 type）并且仅返回实体的"total"数量。  或者更直接地说，“返回为示例账户 #12345 定义的管理员实体总数”。  这个特定的admins API 调用示例说明了 GraphQL API 的一个重要优势

事实上，admins调用可以返回更多数据。  例如，应用程序可以请求admins返回有关每个管理员的详细信息。  然而，此应用程序只需知道管理员的总数。  GraphQL 的这一特性避免了所谓的过度获取，并且可以大大简化实现应用程序所需的代码。

在程序的这一部分构建了请求对象。  这个对象将用于通过 HTTPS 发送 API 调用给 GraphQL 服务器。 此请求对象需要的信息由一些需要首先创建的其他对象提供。   首先，构建一个简单的字符串对象来包含请求对象将发送查询的 GraphQL 服务器 URL。

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

然后创建一个字典，该字典定义了两个 HTTP 头。  这些头用于由请求对象构建 GraphQL 服务器将接受的 HTTP POST 请求。  没有这些头，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()

接下来的两行代码将包含 Cato API 调用的 Python 字典转换为字符串并将该字符串编码为字节。  第二步是允许字符串通过网络传输。

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)

这里程序通过调用 urllib 库的urlopen函数发送请求到 GraphQL 服务器。  调用此函数将导致返回一个 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