Cato APIのためのPythonスクリプトの説明

このサンプルプログラムは短く、判断ロジックや動作を繰り返すコードを含んでいません。  コードのいくつかの行を1行にまとめることで、さらに短く保つことができました。  説明を容易にするために追加のコード行が含まれています。

# 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

このコード行は、APIキーを環境変数から読み込み、変数に割り当てるためにgetenvライブラリ関数を使用します。

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）を渡し、エンティティの「合計」数のみを返します。  または、より直接的に述べると、「例のアカウント # 12345 に定義された管理者のエンティティの合計数を返す」。  このadmins API呼び出しの具体的な例は、GraphQL APIの重要な利点を示しています

実際には、admins呼び出しはもっと多くのデータを返すことができます。  たとえば、アプリケーションはadminsに各管理者の詳細を返すように要求することが可能です。  しかし、このアプリケーションが必要としているのは管理者の総数を知ることだけです。  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文書を保持するボディフィールドが含まれています。  これは、そのreadメソッドを実行することによってオブジェクトから抽出することができる、バイトオブジェクトを返します。  このバイトオブジェクトは、そのバイトオブジェクトのデコードメソッドを呼び出すことで文字列オブジェクトに変換されます。

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

このデコードされた文字列は、このように見えるJSON文書を含んでいます：

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

ご覧のように、返されたデータの形式は、サーバーに送信されたリクエストの形式と非常によく似ています。  これは意図的なものであり、APIを実装するためのGraphQL仕様を使用する利点の一つです。  このアプローチは、リクエストと同じ形状でデータを返すことで、アプリケーションのコーディングを簡素化します。

プログラムのこのセクションの最後のコード行は、返されたJSON文字列をPythonのネストされた辞書に変換するために json ライブラリ関数 'loads' を使用しています。  

get_total_admin_result = json.loads(json_response)

コードの最後の2行は、サーバーから返された total フィールドの値を抽出し、それをコンソールに出力します。 

total = get_total_admins_result['data']['get_total_admins']['total']
print('The total number of admins defined for your account is: {}'.format(total)) 

出力は次のようになります。

The total number of admins defined for your account is: 4