【Catoの利用方法】CatoのネットワークメトリクスをZabbixで収集する - GraphQL APIを curl で呼び出す方法

この連載では、CATOの提供するGraphQL APIを利用し、自社のネットワークの情報を取得してZabbixに連携する方法について解説していきます。

今回は、GraphQL APIを curl で呼び出す方法について焦点を当てます。

CATO は、Cato Networks 社が提供するクラウド型ネットワークサービスで、SASE（Secure Access Service Edge）ソリューションの 1 つです。
ゼロトラストを実現するための要素を統合的に管理できるサービスで、CATO のグローバルバックボーンに接続した企業等の拠点・利用するクラウドサービス・接続するユーザ等を管理し、安全な接続を提供するためのプラットフォームです。
　◆Cato SASEクラウドプラットフォームの機能：https://www.catonetworks.com/ja/platform/

参考コラム：いま注目のCato（ケイト）とは？概要やトライアルの際の注意点を解説

参考コラム：【Catoの利用方法】vSocketを利用してCatoへ接続するには？Microsoft Azureを利用した方法を紹介

CATO は、管理者向けに GraphQL API を提供しており、API 経由でネットワークの各種の情報を取得することができます。
　◆Cato Networks GraphQL API Reference：https://api.catonetworks.com/documentation/

連載を通して、「サイト」と呼ばれる、CATO のネットワークに接続するエッジルータのトラフィック関連のメトリクスをZabbixに連携してみようと思います。

GraphQLは近年よく使われるAPIのスタイルです。

クライアントは単一のエンドポイントに対して取得したいデータの内容をクエリ言語で指定し、サーバはそのクエリに応じたデータを返します。
また、一度の問い合わせで、複数の種別のデータを取得する事もできます。
少ないリクエストで必要なデータのみを取得することができる、効率の良いAPIです。

通常、GraphQL APIへのリクエストは、HTTPのPOSTメソッドを使い、ボディにクエリを含めて送信します。
クエリはJSON形式で記述し、必要に応じて変数を含めることもできます。
例として、「ユーザ情報を取得する」クエリを考えてみましょう。

POST /api/graphql
Content-Type: application/json

{
  "query": "query GetUserInfo($userId: ID!) { user(id: $userId) { name, email } }",
  "variables": {
   "userId": "12345"
  }
}

上記は、「ユーザIDが12345のユーザについて、名前と E メールアドレスを取得する」というリクエストです。
レスポンスは下記のようになるでしょう。

{
  "data": {
   "user": {
    "name": "Taro Yamada",
    "email": "taro.yamada@example.com"
   }
  }
}

このように、レスポンスにはクライアントが要求したフィールドのみが含まれるため、効率的に必要なデータのみを取得することができるのです。

curlを使う理由

さて、このシリーズでは、このようなGraphQL APIを監視用途で呼び出すにあたり、curlコマンドを採用して実装しています。
Python等で実装する例が多く見られますが、監視用途のようなシンプルな取得であればcurlだけでも十分に対応できます。
curlは多くのLinux環境でデフォルトで利用可能なため、多くの環境でそのまま利用できる点を大きなメリットと見ています。

次回以降、curlで取得したレスポンスの加工に一部 jq コマンドを利用しますが、jq も多くの環境で手軽にインストール可能です。

監視用サーバ等の長期運用が求められる環境を想定し、追加のコマンドやそれが依存するライブラリ等をなるべく小さく保つことに重点を置いています。
また、curlは運用を行う管理者やインフラエンジニアにとって馴染み深いツールであり、スクリプトのメンテナンスがしやすいことも特徴となるでしょう。

それでは、実際にCATOのGraphQL APIをcurlで呼び出してみましょう。

具体的な実装例として、様々の種別のデータを一覧で取得できる ”entityLookup” というクエリを利用して、前述の「サイト」の一覧を取得するスクリプトを示します。

#!/usr/bin/env bash

ACCOUNT_ID="${CATO_ACCOUNT_ID:?}"
API_KEY="${CATO_API_KEY:?}"
_query=$(cat <<'___EOL___'
query query(
  $accountID: ID!
  $type: EntityType!
  $limit: Int
) {
  entityLookup(
   accountID: $accountID
   type: $type
   limit: $limit
) {
items {
    entity {
     id
     name
    }
   }
   total
  }
}
___EOL___
)
_variables=$(cat <<___EOL___
{
  "accountID": "${ACCOUNT_ID}",
  "type": "site",
  "limit": 50
}
___EOL___
)
curl -fsSL 
-X POST "https://api.catonetworks.com/api/v1/graphql2" 
-H "X-Api-Key: ${API_KEY}" 
-H "Content-Type: application/json" 
-d @- <<___EOL___
{"query":"$(echo ${_query})","variables":${_variables}}
___EOL___

下記の環境変数を設定し、スクリプトを実行してみましょう。
　- 環境変数：CATO_ACCOUNT_ID
　- CATO管理画面の「Account > Account Info」より確認できます
　- 環境変数：CATO_API_KEY
　- CATO管理画面の「Resources > API Keys」より発行できます

実行結果は下記となりました。（JSON は整形しています）

{
  "data": {
    "entityLookup": {
     "items": [
      {
      "entity": {
        "id": "100100",
        "name": "Tokyo-HeadOffice"
      }
    },
    {
      "entity": {
        "id": "100101",
        "name": "Osaka-BranchOffice"
        }
      }
     ],
     "total": 2
   }
  }
}

各サイトの拠点名と ID が取得できていることが確認できました。

今回は、GraphQL APIをcurlで呼び出し、データを取得する基本的な手順や実装について解説しました。

次回は、Zabbixのローレベルディスカバリについての紹介と、CATOとの組み合わせについてご紹介する予定です。
ご期待下さい。