Cato 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('The total number of admins defined with your account is: {}'.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 문서에 인증을 포함시키는 것은 사양의 위반이 될 것입니다.  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에 정의된 관리자 엔티티의 총 수를 반환합니다."  이 관리자 API 호출의 특정 예시는 GraphQL API의 중요한 장점을 보여줍니다.

사실, 관리자 호출은 훨씬 더 많은 데이터를 반환할 수 있습니다.  예를 들어, 애플리케이션이 각 관리자에 대한 세부 정보를 반환하도록 관리자를 요청할 수 있습니다.  그러나 이 애플리케이션은 관리자 수만 알고 있으면 충분합니다.  GraphQL의 이러한 특성은 과도한 가져오기로 언급되며 애플리케이션을 구현하는 데 필요한 코드가 크게 간소화될 수 있습니다.

프로그램의 이 부분에서는 요청 객체가 구성됩니다.  이 객체는 HTTPS를 사용하여 GraphQL 서버로 API 호출을 보내는 데 사용됩니다. 이 요청 객체는 먼저 생성해야 하는 여러 다른 객체가 제공하는 정보를 요구합니다.   먼저, 요청 객체가 쿼리를 보낼 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 함수가 반환한 객체에는 서버가 반환한 JSON 문서를 포함한 body 필드가 있습니다.  이것은 바이트 객체를 반환하는 read 메소드를 실행하여 객체에서 추출할 수 있습니다.  이 바이트 객체는 bytes 객체의 decode 메소드를 호출하여 문자열 객체로 변환됩니다.

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

이 디코딩된 문자열은 다음과 같은 JSON 문서를 포함합니다.

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

보시는 것처럼 반환된 데이터의 형식은 서버에 전송된 요청의 형식과 매우 유사합니다.  이것은 의도된 것으로, API를 구현할 때 GraphQL 사양을 사용하는 또 다른 장점입니다.  이 접근 방식은 반환된 데이터를 요청과 동일한 모양으로 유지하여 애플리케이션의 코딩을 단순화합니다.

프로그램의 이 섹션의 마지막 코드 줄은 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