ADC

API 仕様のインポート

API 仕様は、エンドポイント、メソッド、パラメータ、データ形式を含む API の設計を定義します。API 仕様のインポート機能により、REST API を記述するために一般的に使用されるオープン API 仕様をインポートできます。 Web App Firewall は、API ベースの Web サービスに対するユーザーのリクエストを検証チェックするときに、その Web サービスの API 仕様ファイルに指定されているスキーマと照合してリクエストを検証します。 NetScalerはREST APIのスキーマ検証をサポートしています。ペイロードはアプリケーションJSONで、gRPC APIリクエストの場合はProtoBufです。

NetScalerは次の仕様形式をサポートしています:

  • Open API - Swagger 2.0, OAS 3.0,3.1
  • ProtoBuf - v3 and v2

API 仕様ファイルの管理

受信APIトラフィックをインポートされたAPI仕様に照らして検証するには、それをプロファイルに割り当て、トラフィックをブロックまたは許可する緩和ルールを設定します。インポートした API 仕様をポリシー表現の作成に使用することもできます。API 仕様のインポートは、次の 2 つのステップで構成されます:

  1. API仕様のインポート-URLまたはシステムからAPI仕様をNetScalerにインポートします。
  2. API仕様をNetScalerに追加-API仕様をNetScalerに追加すると、ファイルが検証され、内部形式に変換され、API仕様エンティティが作成されます。作成された API 仕様エンティティは、ポリシー式と Web App Firewall プロファイルで使用されます。

注:

アップロードした Open API Swagger 2.0、OAS 3.0、3.1 仕様ファイルに、外部ファイルへの参照が含まれていないことを確認してください。外部ファイルの詳細を使用する必要がある場合は、オープンソースツールを使用して情報を 1 つのファイルに統合してからアップロードしてください。

CLI を使用して API 仕様ファイルを管理する

CLI コマンドでは、次のパラメータが使用されます:

  • 名前-アップロードされた API 仕様ファイルの名前。
  • ソース- インポートされた仕様ファイルを保存する場所の URL (プロトコル、ホスト、パス、名前)。
  • 仕様名 - アップロードされた API 仕様から作成されたエンティティの名前。
  • タイプ-API 仕様の入力形式。 デフォルト値:OAS

API 仕様ファイルをインポートするには、次のように入力します:

import api specFile <name> <src>

例:
import apispec testapispec.json http://www.example.com/testapispec.json

API 仕様ファイルを追加するには、次のように入力します:

add api spec <Name> -File <string> -Type <string>

例:
add api spec testapispec -File testapispec.json -Type OAS

API 仕様ファイルを更新するには、更新が必要な新しい仕様ファイルをインポートします。

コマンドプロンプトで入力します:

update api spec <specName> -File <string> -Type <string>

例:
update api spec testapispec -File testapispec.json -Type OAS

注:

type 属性が指定されていない場合、OAS がデフォルトのタイプです。

すべてのエンドポイントを表示するには、次のように入力します:

show api spec <specName>

例:

show api spec testapispec

API 仕様を削除するには、次のように入力します:

rm api spec <specName>

例:

rm api spec testapispec

注:

API 仕様を削除する前に、その仕様がどのプロファイルまたはポリシーでも使用されていないことを確認してください。

GUI を使用して API 仕様ファイルを管理

  1. [ **セキュリティ] > [NetScaler Web App Firewall] **[インポート] に移動します。
  2. インポート 」ページで、「 API 仕様インポートページ 」タブを選択し、「 追加」をクリックします。
  3. API 仕様のインポートオブジェクトページで 、Import From パラメータに以下のオプションのいずれかを選択します:
    1. URL: アプライアンスにアクセスできる Web サイト上のウェブ URL。
    2. ファイル: ローカルまたはネットワークに接続されたハードディスク、またはその他のストレージデバイス上のファイル。
  4. [続行] をクリックします。
  5. API 仕様インポートオブジェクトページで 、次の詳細を入力します:
    1. API 仕様名 — アップロードされた API 仕様から作成されたエンティティの名前。 注:入力する API ファイル名と API 仕様名は同じでなければなりません。
    2. API 仕様タイプ — 仕様のタイプを選択します。

      タイプ:REST (OpenAPI/Swagger)、gRPC (PROTO)。

      Default Type: REST (OpenAPI/Swagger)

    3. [完了] をクリックします。

新しく追加されたエンティティは、「 API仕様インポートページ」タブの「インポート」ページに表示されます。

API 仕様と API エンドポイントの統計を表示する

すべての API 仕様と API エンドポイントについて、以下の統計情報を表示できます:

  • API 仕様ヒット-API 仕様の任意のエンドポイントと一致するリクエスト。
  • API 仕様の検証成功-API 仕様の任意のエンドポイントと一致し、API スキーマに準拠しているリクエスト。
  • API 仕様が一致しないリクエスト-API 仕様のどのエンドポイントとも一致しないリクエスト。
  • API エンドポイントのヒット数-特定のエンドポイントに一致するリクエスト。
  • API エンドポイントの検証成功-特定のエンドポイントと一致し、API スキーマに準拠しているリクエスト。

CLI を使用して API 仕様と API エンドポイントの統計情報を表示する

コマンドプロンプトで入力します:

stat apispec <apispec name>

stat apispec testapispec

GUI を使用して API 仕様と API エンドポイントの統計情報を表示する

  1. [ **セキュリティ] > [NetScaler Web App Firewall] **[インポート] に移動します。
  2. 「インポート」ページで、「 API 仕様のインポート」タブを選択し、「 統計」をクリックします。

    API 仕様の概要が表示されます。

  3. エンドポイントの概要を表示するには、いずれかの API 仕様をクリックします。

    選択した API 仕様の API エンドポイントの概要が表示されます。

API 仕様のインポート