Public APIとOAuthトークン

外部のシステムからNinjaOneの情報を取得したり、操作したりする仕組みです。定型の連携では対応できない要件を実現します。

APIを使う場面

用意されている連携で足りる場合、APIを使う必要はありません。次のような要件で検討します。

要件	例
独自のシステムと連携したい	社内の資産管理システムへデータを送る
定型の連携先に含まれない製品と連携したい	業界固有のシステム
大量のデータを一括処理したい	数千台分の情報を一度に取得する
独自の集計や可視化を行いたい	社内のダッシュボードに表示する
定型作業を自動化したい	入社処理と連動してデバイスを登録する

認証情報の管理画面

AdministrationのApps配下にあるAPIで管理します。

タブは3つあります。

タブ	用途
Client app IDs	アプリケーション単位の登録。現在の推奨方式
OAuth tokens	発行済みトークンの管理
Legacy API keys	旧方式のキー

新規に連携を作る場合はClient app IDsからAdd client appで登録します。

Legacy API keysは旧方式です。既に使っているものがあれば、Client app IDsへの移行を検討してください。旧方式は将来的に利用できなくなる可能性があります。

一覧にはName、Client ID、Scopesが表示されます。Scopesで許可されている操作の範囲が確認できるため、棚卸しの際はこの列を見てください。

クライアントアプリの登録

Add client appで登録します。指定するのは次の項目です。

項目	内容
名前	用途が分かる名称
スコープ	許可する操作の範囲
権限	読み取りのみか、書き込みも許可するか

【注意】 発行された認証情報は、発行時にしか表示されない場合があります。安全な場所に保管してください。紛失した場合は再発行が必要です。また、この情報が漏れると第三者がテナントの情報にアクセスできます。ソースコードに直接書き込まないでください。

スコープと権限の設計

必要最小限の権限だけを与えてください。

用途	適切な権限
情報を取得して表示する	読み取りのみ
資産情報を同期する	該当範囲の読み取りと書き込み
デバイスを操作する	慎重に判断。原則として避ける

3番目は影響が大きい権限です。APIから再起動やスクリプト実行ができる状態は、認証情報が漏れた場合の被害が深刻になります。

用途ごとに別のトークンを発行してください。1つのトークンを複数の用途で使い回すと、必要な権限が広くなり、漏えい時の影響も大きくなります。

取得できる主な情報

APIで扱える対象は多岐にわたります。

対象	用途の例
デバイス	一覧の取得、詳細情報の参照
Organization / Location	構造の取得
アラート	検知の状況を外部で集計する
チケット	他システムとの連携
Custom Fields	値の取得と更新
ソフトウェア情報	ライセンス管理システムへの連携

Custom Fieldsの更新は、外部システムからデータを流し込む用途で有効です。人事システムから利用部署を同期する、といった使い方ができます。

利用時の制限

APIには利用回数の制限があります。短時間に大量の要求を送ると、一時的に受け付けられなくなります。

対策としては次の方法があります。

1. 要求の間隔を空ける
2. 一度に取得する件数を調整する
3. 差分だけを取得する
4. 実行の頻度を見直す

3番目が効果的です。毎回全件を取得するのではなく、前回から変更があったものだけを取得する設計にしてください。

開発と運用の注意点

注意点	内容
認証情報の管理	ソースコードに書かない。設定ファイルや環境変数を使う
エラー処理	失敗したときの動作を定義する
記録	実行の履歴を残す
検証環境での確認	本番データで最初のテストをしない
権限の定期見直し	不要になったトークンを削除する

4番目を守ってください。書き込み権限を持つプログラムの初回テストを本番環境で行うと、誤って大量のデータを変更する可能性があります。

トークンの棚卸し

発行したトークンは、定期的に確認してください。

確認内容	対応
使われていないトークン	削除する
用途が不明なトークン	調査するか削除する
権限が過剰なトークン	必要最小限に絞る
退職者が発行したトークン	引き継ぐか削除する

四半期ごとの確認を推奨します。使われていないトークンを残すと、不正利用の経路になります。

【運用のポイント】 トークンの一覧と用途を、別途の管理表に記録してください。NinjaOne上では「誰が発行したか」は分かりますが、「何のために使っているか」は分かりません。担当者の交代時に判断できなくなります。