【Catoクラウド】Cato APIでユーザの一括登録を試してみた！

Catoクラウドでは、管理コンソールであるCMA（Cato Management Application）から各種設定や運用を行うのが一般的ですが、Catoが提供するAPIを利用することでさまざまな操作を自動化することも可能です。

Cato APIでできること

Cato API 概要 

Cato APIの詳細は、Cato Networks GraphQL API Reference から最新情報が確認できます。

しかし、量も膨大でAPIを初めて扱う場合はぱっと見で何が書いてあるかわかりづらいので、この場で概要をまとめたいと思います。

提供されているAPIには大きく、Query（参照系）とMutation（操作系）があります。

種類	個数（※）	役割	必要な権限
Query（参照系）	146	情報を取得	Viewer以上
Mutation（操作系）	357	設定の作成・変更・削除	Editor

※2026年8月時点の個数

CMAでAPIキーの発行時に権限を設定しますが、上記の通り、Viewer権限で作ったキーでは、Mutationは行えませんのでご注意ください。

また、APIは以下のように成熟度に応じたラベル付けがされています。

• GA（General Availability）: 安定版で本番環境対応、長期サポートあり
• Beta: 機能は完成しており本番利用可能だが、変更の可能性あり

APIの領域

Cato APIは、Queryが41個、Mutationが21個の領域に分かれています。
主に以下のような項目があります。

領域	内容
Policy	InternetFWやTLSインスペクション、CASBなど16種類のポリシー操作
Site	サイトの作成、vSocketの追加、ネットワークレンジやスタティックホストの設定、BGPピア設定
Container	FQDNやIPアドレス範囲をまとめた「Container」を管理 CMA上の場所 Resources > Categories > Container
Notification	通知の送信先やWebhook、メーリングリストの設定
PoPLocation	接続先となるCatoのPoP拠点の情報取得や、割り当て設定
Devices	接続されているデバイスの一覧取得や、CSV形式でのエクスポート
User　※本記事の検証で利用	SDPユーザの作成・更新・削除・有効化／無効化
Admin	CMA管理者やService Principalの追加・変更・削除
Licensing	管理アカウントへのライセンス割り当てや、サービスの有効化
Groups	ポリシーで使用するグループの作成・更新・削除

上記の中から「User」の領域ではどのようなAPIがあるのか具体的に見ていきます。

ユーザ管理API

ユーザ領域では以下の7つのAPIが用意されていました。

名称	種別	対応件数	内容
userList	Query	デフォルト50件	ユーザ一覧を取得
createUser	Mutation	1件ずつ	ユーザを作成
updateUser	Mutation	1件ずつ	ユーザ情報を更新
deleteUser	Mutation	最大100件	ユーザを削除
enableUser	Mutation	最大100件	ユーザを有効化
disableUser	Mutation	最大100件	ユーザを無効化
revokeUserSession	Mutation	最大100件	RevokeSessionを実行 （セッションを失効させ再認証を要求）

対応件数に制限があるようで、作成・更新は1件ずつという制限があります。
なお、ユーザ削除や有効化のように、複数ユーザをAPIで一括操作する場合は、1件でも失敗すると全体が実行されないという設定になっています。

さらに深掘りしていきます！

上記の「createUser」では、APIリクエストでどのような情報を渡す必要があるのか見ていきます。
以下、「createUser」の入力項目です。

項目	入力有無	内容
firstName	必須	名
lastName	必須	姓
email	必須	メールアドレス
department	任意	部署
jobTitle	任意	役職
phoneNumber	任意	電話番号

必須項目はCMA上での登録と同様、「名」「姓」「メールアドレス」だけとなっていますね。
また、パスワードやライセンスの項目は存在しないので、API上ではあくまでユーザの作成のみで、
有効化は別途操作が必要ということがわかります。

APIリクエストのイメージ

ここまで、Query（参照系）かMutation（操作系）というところから、APIに渡す具体的な項目まで階層的に見ていきました。

改めてユーザ作成を例に階層構造をまとめると以下のようになります。

Query / Mutation（参照系か操作系か）
　└ 領域（user）
　　└ 操作(createUserなど）
　　　└ 入力項目(firstNameやemail）

GraphQLのリクエストでは上記の階層構造がそのまま入れ子になっています。

mutation {　　　　　　　　　　　　←Query / Mutation
 user(accountId: "12345") {      ←領域
  createUser(input: {　　　　　　←操作
   firstName: "Taro"　　　　　　 ←入力項目
   lastName: "Yamada"
   email: "taro@example.com"
  }) {
   user { id email }　　　　　　 ←ほしい項目を指定
  }
 }
}

8行目のuser{ id email}という文は作成されたユーザのIDとメールアドレスを返してくださいと指定しており、ここの必要な情報だけを指定できる部分がGraphQLの特徴です。

Cato APIの利用については以下のブログにも詳細が記載されています。必要に応じてご参照ください。

活用ケース

APIの活用シーンについてですが、1つや2つ設定を変えるだけであればやはりCMAに勝るものはないと考えていますが、どうしても大量に設定が必要なケースや定期的に行う一連の作業を自動化する際はAPIが有効だと感じました。

例えば以下のようなケースです。

• ユーザやサイトの一括登録
  組織統合や、新入社員の入社などまとまった人数・拠点数の登録が必要で、かつSCIMやLDAP連携が利用できない場合
• InternetFWなど各種セキュリティポリシールールの一括登録
  検証環境から本番環境への設定移行や、グループ会社間でセキュリティポリシーを統一したい場合
• 定期的なレポート作成
  CMA上で毎月チェックしている項目をQueryで取得して自社専用のレポートを作成したい場合

【実践】APIを使ったユーザ一括登録

いよいよ実践に移ります！ユーザの追加はAPIですと1件ずつしか実行できません。
そのため、APIを使った一回の実行をPythonプログラムで自動で繰り返すといった流れで実装していきます。
まずは1ユーザ分の追加ができるかを試してみます。

APIを用いて1ユーザ分を作成してみる

実行環境はCato APIのGraphQL Playgroundを利用しました。
WindowsのPowerShellからも試しましたが、Playgroundの方が圧倒的に使いやすかったのでこちらを推奨します。

まず、APIを利用するにあたり、事前に以下対応をお願いします。

• APIキーの作成
  CMA の Resources > [Service API keys]または[Admin API keys] > New から作成が可能です。
  今回は、ユーザの作成という”操作”を行うため、Editor権限が必要です。
  設定画面の「Downgrade to View」のチェックをはずすことでEditor権限でAPIキーが作成されます。

 

 

 

• アカウントIDの確認
  CMAの Account > Account Info > Account ID
  からアカウントIDを確認してください。

では、実際に実行していきます。以下のリクエストで織田信長さん（api-test-001@example.com）を追加します。

mutation {
　user(accountId: "アカウントID") {
　　createUser(input: {
　　　firstName: "nobunaga"
　　　lastName: "oda"
　　　email: "api-test-001@example.com"
　　}) {
　　　user {
　　　　id
　　　　email
　　　}
　　}
　}
}

下図は実行画面です。正常にユーザの追加が成功し、出力項目として指定した[id]と[email]が右側の結果欄で確認できます。
ちなみに、下の例で”87″と出ている[id]ですがCatoがバックグラウンドで管理しているもので、CMA上では確認できない値です。
APIでユーザを指定する際はこのidを用います。

CMA上でも追加したユーザが確認できました。設定の反映は非常に早く、実行直後にCMAの画面をリロードするとすぐ反映がされていました。
Sourceは「Manual」で手動登録と同じ扱いになっていました。
実行直後、ライセンスとパスワードは未割り当て状態ですが、自動割り当て設定にしている場合、数分後に割り当てが反映されます。

プログラムから複数ユーザを一括で登録してみる

複数のユーザを一気に登録するには上記で行ったAPIの処理をプログラム上で繰り返す必要があります。
ユーザ一覧が記載されたcsvファイルを読み込んでAPIリクエストを繰り返し送信する形で実装しました。

今回はPythonプログラムを作成し検証してみました。
細かいコードの記述より、ざっくりとした処理の流れをイメージいただければと思います。

プログラムコードの中身は大まかに以下4つが必要です。

1. 接続情報
2. リクエストのクエリ文
3. 上記クエリ文を送信する処理
4. CSVを読み込んで3番を繰り返す処理

1. 接続情報の準備

エンドポイントURL、APIキー、アカウントIDの情報が必要です。
値の取得方法は、環境変数から読み込み、ユーザに入力させるなどあるかと思います。

API_URL = "https://api.catonetworks.com/api/v1/graphql2"
API_KEY = os.environ.get("CATO_API_KEY")
ACCOUNT_ID = os.environ.get("CATO_ACCOUNT_ID")

 

2. リクエストのクエリ文

先程のPlaygroundの左上で書いていたクエリ文を記述します。
1件ごとに中身が変わるので、値は直接書かず、$acc、$inという変数で受け取る形にしています。

CREATE_USER = """
mutation($acc: ID!, $in: CreateUserInput!) {
　user(accountId: $acc) {
　　createUser(input: $in) {
　　　user { id email }
　　}
　}
}
"""

 

3. リクエストを送信する処理

Playgroundの「実行」を押したときの処理をPythonで実装すると以下のようになります。
2番で作成したクエリ文 「CREATE_USER」を3行目で指定しています。

def create_user(row): 
　payload = json.dumps({  
　　"query": CREATE_USER,  
　　"variables": {"acc": ACCOUNT_ID, "in": row},  
　}).encode()   

　req = urllib.request.Request(  
　　API_URL,  
　　data=payload,  
　　headers={"x-api-key": API_KEY, "Content-Type": "application/json"},  
　)  
　with urllib.request.urlopen(req, timeout=30) as res:  
　　return json.loads(res.read())

 

4. CSVを読み込んで3番を繰り返す処理

csvの形式によって読み込みの仕方は調整が必要です。
今回はシンプルに必須3項目のみ記載した以下のようなファイルにしています。

以下コードの7行目では、3番で作成した 「create_user」 関数に、csvから読み込んだ値を入れてリクエストを送信し、それをfor文で繰り返しているという構造です。

# CSVを読み込む
with open(csv_path, encoding="utf-8-sig", newline="") as f:
　rows = [{k: v for k, v in r.items() if v} for r in csv.DictReader(f)]

# 1行ずつ登録する
for i, row in enumerate(rows, 1):
　res = create_user(row)
　print(f"[{i}/{len(rows)}] OK {row['email']}")
　time.sleep(0.5)

では、最後にプログラムの実行に移っていきます。

プログラムの実行

今回作成したプログラムは、上記の4つの処理項目をベースにAIの力を借りてツールっぽく仕上げました。

まず、APIキーとアカウントID、CSVファイルパスの入力が求められます。
入力をした後にEnterを押します。

 

すると読み込んだ内容が表示されるので、
yesを入力して実行すると、3件とも問題なく成功しました。

CMA上で確認してみると、
3ユーザが登録されていることが確認できました。

まとめ

本記事では、Cato APIの概要と実際にユーザ 一括登録を試してみた結果についてご紹介しました。

Cato APIは徐々にできることが増え、活用の幅も広がってきています。
多少とっつきにくさがあると思いますが、やってみると思ったより簡単にできるなという印象でしたので、ぜひ一度Cato APIを試してみてはいかがでしょうか。

また、CatoのAI機能 Ask-AIにAPIでやりたいことを尋ねてみるとクエリを自動で生成してくれますので、こちらもご活用ください。

※Copilotなど外部の生成AIを使う際は機密情報（APIキー、アカウントID）は入力しないよう十分に注意しましょう！

今後もAPIについて大きなアップデートがありましたら、記事にできればと考えています。

最後までお読みいただきありがとうございました！