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

はじめに
Cato API 概要
行える操作
1. Monitoring API (Queries)
2. Configuration API (Mutations)
試しに実行する
1. ① API キーの作成
2. ② GraphQL Playground で API を実行
プログラムから実行する
events API の実行例
API 利用の注意点
まとめ

はじめに

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” 画面で作成できます。

参考：Generating API Keys for the Cato API

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 を試しに実行してみましょう。

参考：Connecting to the Cato API Server from the GraphQL Playground

ここでは 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

A query language for your API — GraphQL provides a complete description of the data in your API, gives clients the power...

プログラムから実行する

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

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

参考：Example Scripts: Using the Cato API with Python

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 実行のレート制限に関して記載されています。

参考：Understanding Cato API Rate Limiting

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

取得できるデータの遅延

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

参考：Running API Calls with the Cato Cloud

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

取得できる期間の制限

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

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

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

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

entityLookup API : 1000件 (Cato API – EntityLookup に記載)
accountMetrics API : 100000アイテム (Cato API – AccountMetrics に記載)
- アイテム数の計算方法についてはドキュメントを参照
events API : 5000件 (ドキュメントに記載なし)
auditFeed API : 1000件 (Cato API – AuditFeed に記載)
eventsFeed API : 1000件 (Cato API – EventsFeed (Large Scale Event Monitoring) に記載)
- ただし、実際には3000件まで同時に取得できている

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

まとめ

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

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

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