Cato API の利用方法と制限事項

2023.08.08

はじめに

Cato Networks 社が提供する Cato クラウドでは、アカウントの管理者向けに Web ベースで操作できる Cato API が提供されています。

Cato クラウドに限らず、今はクラウドを API で操作して管理することが一般的になってきていますので、Cato API を活用して効率よく確実に Cato クラウドを利用したいと考える方は多いのではないでしょうか。

本記事では、Cato API の具体的な利用方法を中心に解説していきます。

Cato API 概要

Cato API は大きく分けて次の2種類の API として提供されています。

種類 説明
Monitoring API Cato クラウド上のログ、メトリクス、サイトやユーザなどのデータを参照する API
Configuration API Cato クラウドの設定変更を行う API

2023年8月7日時点で合計 28 個の API が用意されています。

いずれも API も GraphQL で実装されており、API の一覧および詳細なリファレンスは Cato Networks GraphQL API Reference に記載されています。”Queries” の操作は参照のみ行う Monitoring API であり、”Mutations” の操作は設定変更を行う Configuration API に該当します。

API の実体は HTTPS でアクセスする Web API であり、リクエスト・レスポンスともに JSON 形式のメッセージとなっています。

行える操作

Monitoring API (Queries)

Monitoring API では、Cato Management Application の画面で閲覧できるデータのうち、次のようなデータを参照できます。

  • Administrators
  • Roles
  • Subdomain (Single Sing-On の中の項目)
  • Users
    • Users Directory 以下の全ユーザ
    • SDP Users Activity のうち現在接続中のユーザのデータ
  • Sites
    • 一覧情報
    • Snapshot
    • Network Analytics
  • App Analytics
  • Events
  • Audit Trail

ここに挙げたものが全てではありませんので、実際にどのデータを参照できるのかは API のリファレンスや実際の動作を確認してください。
なお、本記事執筆時点では、セキュリティに関する設定値を参照するための API は用意されておりません。

Configuration API (Mutations)

Configuration API では、次の設定の作成・変更・削除操作を行えます。

  • Admin ユーザ
  • Site
  • Socket Interface
  • Network Range
  • Static Host

ただし、Site のように多数の設定項目を持っているものについて API で全ての設定変更を行えるわけではありませんので、実際にどの項目を設定できるのかは API のリファレンスを確認してください。

試しに実行する

Cato API には、API を試しに実行するための Web 画面 (GraphQL Playground) が用意されていますので、これを用いて API を試してみましょう。

① API キーの作成

Cato API を利用するには、まずは API キーを作成する必要があります。

API キーは Cato Management Application の “Administation” – “API & Integrations” 画面で作成できます。

Monitoring API だけ利用するのであれば API Permission は “View” でよく、Configuration API も利用するのであれば “Edit” 権限が必要となります。

また、イベント1件1件の詳細なデータを取得したい場合 (eventsFeed APIを利用する場合) は、”Events Integration” タブで “Enable integration with Cato events” を有効にしてください。

② GraphQL Playground で API を実行

次に、Cato API の GraphQL Playground にて、API を試しに実行してみましょう。

ここでは entityLookup API を用いてサイトの一覧を取得してみましょう。

API のリファレンス を見ればどのような Query や Variables を指定すれば良いか確認できます。今回は entityLookup API で参照できる全てのサイト情報を取得することを目標とし、GraphQL Playground の画面で次のように入力してください。

Query (左上のテキストエリア)

query entityLookup($accountID: ID!, $limit: Int, $type: EntityType!) {
  entityLookup(accountID: $accountID, type: $type, limit: $limit) {
    items {
      entity {
        id
        name
        type
      }
      description
      helperFields
    }
    total
  }
}

Variables (左下のタブ)

{
  "accountID": "アカウントID",
  "limit": 1000,
  "type": "site"
}
  • アカウントIDは、Cato Management Application にログインした後にURLに含まれている “/account/数字/” の数字の部分

Headers (左下のタブの2番目)

{
  "x-api-key": "API キー"
}
  • API キーは①で作成したもの

上記を入力後、▶ アイコンの実行ボタンを押せば、API の実行結果が右側に JSON 形式で表示されます。

API を正常に実行できていれば、実行結果の JSON の “data.entityLookup.items” というフィールドに各サイトの情報が配列として格納されています。もしも何らかの理由で API の実行が失敗すると、実行結果にはエラー情報が格納されます。

Query の記法については、GraphQL のドキュメントの次のページも参考になります。

Queries and Mutations | GraphQL
graphql.org

プログラムから実行する

GraphQL Playground は API の動作を試してみる目的には良いのですが、API は操作を自動化したり他のソフトウェアと連携したりするためにプログラムから実行したいはずです。

以下のページに API を実行する Python プログラムの例があり、これを参考に前項の API を実行するサンプルプログラムを書くと次のようになります。

import json
import urllib.request

def main():
    query = """
    query entityLookup($accountID: ID!, $limit: Int, $type: EntityType!) {
      entityLookup(accountID: $accountID, type: $type, limit: $limit) {
        items {
          entity {
            id
            name
            type
          }
          description
          helperFields
        }
        total
      }
    }
    """

    variables = {
        "accountID": "アカウントID",
        "limit": 1000,
        "type": "site",
    }

    headers = {
        "x-api-key": "API キー",
        "Content-Type": "application/json",
    }

    # API リクエストを POST メソッドで送信
    request = urllib.request.Request(
        url="https://api.catonetworks.com/api/v1/graphql2",
        headers=headers,
        data=json.dumps(
            {
                "query": query,
                "variables": variables,
            }
        ).encode("ascii"),
    )

    with urllib.request.urlopen(request, timeout=30) as response:
        # レスポンスの JSON を整形して表示
        print(json.dumps(json.loads(response.read()), indent=2))

if __name__ == "__main__":
    main()

API リクエストでは、Query や Variables から生成した JSON をデータとして指定するとともに、リクエストヘッダでは Content-Type として “application/json” を指定する必要があります。

events API の実行例

前項までは entityLookup という比較的シンプルな API を例としていましたが、ここではもう少し複雑な events API を例として解説します。

Cato Management Application の “Events” 画面では Cato クラウドで発生したイベントのログが見れますが、Internet Firewall や WAN Firewall の設定次第で通信ごとにログが生成されることもあり、膨大な量のログが出力されているのではないでしょうか。Cato クラウドの利用状況にもよりますが、ひと月当たり数億～数十億件のイベントログが出力されることもあります。これらのイベントログ全体を取得し、目的のログの集計や抽出を行うというのは、プログラムで行うにしても多くの時間やリソースが必要となってきます。

ただし、イベントログの集計や一部の抽出のみ行えば良いケースも多く、そのようなケースでは events API が役立ちます。この API は、Cato クラウド側でイベントログを集計・抽出してその結果を取得するものであり、数秒で結果が返ってきますので十分活用できます。

events API のリファレンス には次の6つの引数が定義されています。

引数 説明
accountID アカウントID
timeFrame 対象のログの期間
measures 集計対象のフィールドと集計方法
dimensions キーとするフィールド
filters ログの抽出条件
sort 結果のソート方法

この events API は SQL に近い API であり、各引数を SQL の句や関数に対応付けて理解すると扱いやすいかと思います。

  • timeFrame : WHERE 句 (WHERE “時刻フィールド” BETWEEN “期間の開始時刻” AND “期間の終了時刻”)
  • measures : COUNT, SUM, MAX などの集計関数
  • dimensions : GROUP BY 句
  • filters : WHERE 句
  • sort : ORDER BY 句

上記を踏まえて、例えば「2023年7月の Internet Firewall のルールごとのイベント数を降順で取得する」という操作は次のような Query と Variables で実現できます。

Query

query events($accountID: ID!, $timeFrame: TimeFrame!, $measures: [EventsMeasure], $dimensions: [EventsDimension], $filters: [EventsFilter!], $sort: [EventsSort!]) {
  events(
    accountID: $accountID
    timeFrame: $timeFrame
    measures: $measures
    dimensions: $dimensions
    filters: $filters
    sort: $sort
  ) {
    from
    to
    records {
      fieldsMap
    }
  }
}

Variables

{
  "accountID": "アカウントID",
  "timeFrame": "utc.2023-07-{01/00:00:00--31/23:59:59}",
  "measures": [
    { "fieldName": "event_count", "aggType": "sum" }
  ],
  "dimensions": [
    { "fieldName": "rule" }
  ],
  "filters": [
    {
      "fieldName": "event_sub_type",
      "operator": "is",
      "values": [ "Internet Firewall" ]
    }
  ],
  "sort": [
    { "fieldName": "event_count", "order": "desc" }
  ]
}

Headers

{
  "x-api-key": "API キー"
}
実行結果例
{
  "data": {
    "events": {
      "from": "2023-07-01T00:00:00Z",
      "to": "2023-08-01T00:00:00Z",
      "records": [
        {
          "fieldsMap": {
            "event_count": "154473",
            "rule": "Default block for Categories"
          }
        },
        {
          "fieldsMap": {
            "event_count": "22398",
            "rule": "Default prompt for Categories"
          }
        },

        ...

      ]
    }
  }
}

また、各イベントには一意なIDフィールド “internalId” があることを利用し、それを dimensions で指定すれば、一定の範囲内でイベントログの元データを取得することもできます。

例えば「2023年7月の各サイトの Socket のアップグレード履歴を時刻の昇順で取得する」という操作は次のような Variables に変更すれば実現できます。(Query は前記のものと同じです。)

Variables

{
  "accountID": "アカウントID",
  "timeFrame": "utc.2023-07-{01/00:00:00--31/23:59:59}",
  "measures": [
    { "fieldName": "time", "aggType": "any" },
    { "fieldName": "src_site", "aggType": "any" },
    { "fieldName": "action", "aggType": "any" }
  ],
  "dimensions": [
    { "fieldName": "internalId" }
  ],
  "filters": [
    {
      "fieldName": "event_sub_type",
      "operator": "is",
      "values": [ "Socket Upgrade" ]
    }
  ],
  "sort": [
    { "fieldName": "time", "order": "asc" }
  ]
}

ただし、events API は1度に5000件の結果しか取得できず、ログ期間は1時間単位であるため、その期間・件数に収まる範囲でしか正しい結果を取得できないという点に注意してください。

API 利用の注意点

Cato API は無制限に利用できるわけではなく、次のような制限が設けられています。

API 実行のレート制限

以下のページに、API 実行のレート制限に関して記載されています。

1つのプログラムで API を1つずつ順に実行するだけならレート制限を超えることはないでしょうが、複数のプログラムやスレッドで並列に実行するとレート制限を超える可能性は十分にありそうです。

取得できるデータの遅延

以下のページに、一部の API において最新のデータを取得できるようになるまでの遅延について記載されています。

またこれ以外に、イベントに関するデータは取得できるようになるまでに数分の遅延があることが確認できていますので、一定の遅延があることを考慮して利用する必要があります。

取得できる期間の制限

Cato クラウド側ではイベントログやトラフィックデータは180日間 (あるいは90日間) しか保存されていないため、API でそれより前のデータを取得することはできません。また、eventsFeed API では7日より前のデータを取得することはできません。

一度に取得できる件数の制限

API にもよりますが、一度に取得できるデータの件数には制限が設けられています。

例えば、次の API の件数制限は次のようになっています。

なお、auditFeed API や eventsFeed API には marker という仕組みが用意されており、3000件取得したあと、それより後の3000件をさらに取得するといった操作が可能となっています。

まとめ

本記事では Cato API の概要、実行方法、注意点などについて解説しました。

記事執筆時点では、API は Cato Management Application で行える操作のうち一部しか対応しておりませんが、サイトや Admin ユーザの管理に関する操作の自動化であれば API で実現できそうです。また、イベントログの分析やネットワークのメトリクスデータの取得も API で行えますので、定常的な運用にも活用できそうです。

セキュリティ関連の設定変更や設定値の取得が行えるようになれば API の活用範囲はさらに広がりますし、Cato クラウドは毎週多数のアップデートが行われておりますので、将来そのような API も実装されるのではないでしょうか。弊社の FAQ サイトでは Cato クラウドのアップデート情報を日本語で翻訳した内容を公開しておりますので、アップデート情報をチェックする際はそちらも参照いただけると幸いです。

よくあるご質問 | Cato Cloud ケイトクラウド - SCSK
Cato SASE Cloud Platform. powered by SCSK
cato-scsk.dga.jp

また、弊社の Cato クラウドのマネージドサービスの一部では実際に API を活用しておりますので、API の利活用でお困りのお客様がいらっしゃいましたら、弊社の担当のものに気軽にご相談ください。

著者について
山下雅喜

システムのインフラ・運用領域のソフトウェアエンジニアです。
通信周りがメインです。

山下雅喜をフォローする

クラウドに強いによるエンジニアブログです。

SCSKでは、自社クラウドと３大メガクラウドの強みを活かし、ハイブリッドクラウド／マルチクラウドのソリューションを展開しています。業界の深い理解をもとに、お客様の業務要件に最適なアーキテクチャをご提案いたします。サービスサイトでは、お客様のDX推進をワンストップで支援するサービスの詳細や導入事例を紹介しています。

Cato Cloudクラウドソリューション運用・監視
Cato
シェアする
TechHarmony
タイトルとURLをコピーしました