API エクスプローラ

REST API について学習するには、API エクスプローラを使用します。さまざまなメソッドやそれらが正しく構成されていることを確認するためのリソースをテストすることもできます。出発点として JSON モデルをコピーし、コードに貼り付けることができます。


ヒント


API エクスプローラの目的は、API についての学習を手助けすることです。API エクスプローラ経由の呼び出しのテストでは、通常の操作を妨げる可能性があるアクセス ロックの作成が必要です。非実稼働デバイスで API エクスプローラを使用することをお勧めします。


API エクスプローラを開く

API エクスプローラでは、プログラムで使用可能なすべてのリソースおよび JSON オブジェクトが説明されます。エクスプローラは各オブジェクトの属性と値のペアについて詳細情報を提供するため、さまざまな HTTP メソッドを試して各リソースに必要なコーディングを理解することができます。

手順


ステップ 1

ブラウザを使用して、システムのホームページ(https://ftd.example.com など)を開きます。

ステップ 2

Device Manager にログインします。

ステップ 3

(6.4 以前)。/#/Api-explorer を指すように URL を編集します(たとえば、https://ftd.example.com/#/api-explorer)。

ステップ 4

(6.5 以降)。[詳細オプション(More options)] ボタン([その他のオプション(More options)] ボタン。)をクリックし、[APIエクスプローラ(API Explorer)] を選択します。

ブラウザの設定に応じて、API エクスプローラが別のタブまたはウィンドウで開きます。


API エクスプローラでの方法の検索

API エクスプローラを開始すると、リソース グループの一覧が表示されます。これらのグループには、API で利用可能なリソースが含まれます。次の図は、小さなリストの例を示しています。


API エクスプローラのリソース リスト。

これらのグループ名はリンクです。リンクをクリックしてグループを開くと、グループのリソースで使用できるメソッドを確認できます。各グループの右側には次のコマンドも含まれています。

  • [表示/非表示(Show/Hide)] ではグループが開閉します。これは、グループ名をクリックするのと同じです。展開すると最初は単にメソッドを示します([操作の一覧表示(List Operations)] と同じ)が、システムは(閉じる前の)最後の展開状態を記憶するため、同じ展開レベルで再度開きます。

  • [操作の一覧表示(List Operations)] は、グループの各リソースで利用可能な HTTP メソッドを示します。情報には、リソースごとのユニバーサル リソース ロケータ(URL)テンプレートの相対パスが含まれます。パス変数は、標準の規則によって示されます:{variable} 。カッコを含む {variable} は適切な値に置き換える必要があります。この相対パスにベース URL を追加する必要があります。API のベース URLを参照してください。

    そのメソッドの完全なドキュメントを参照するには、操作の URL テンプレートをクリックします。

  • [操作の展開(Expand Operations)] では、グループ内の利用可能なすべての HTTP メソッドおよびリソースが開きます。

一部のグループには、多数の子リソースがあります。たとえば、DataInterface ManagementAccess グループには、/devicesettings/default/managementaccess に対する GET、POST、および DELETE 操作、/devicesettings/default/managementaccess/{objId} に対する GET および PUT 操作が含まれます。


API エクスプローラでのカテゴリのリソース一覧。

リソースに関するドキュメントの表示

各リソースの属性は API エクスプローラに記載されています。

手順


ステップ 1

関心のある特定のリソースおよびメソッドまでドリル ダウンします。

ステップ 2

[応答クラス(Response Class)] セクションで、[モデル(Model)] タブをクリックします。

モデルには、属性が説明およびデータ型とともにリストされます。GET の場合、ページング オプションも返される可能性があります。応答で返されたより多くのオブジェクトが存在する場合は、次および前のオブジェクトの集合への URL が取得されます。

たとえば、次のグラフィックは POST /object/tcpports のメソッドおよびリソースを示しており、[モデル(Model)] タブが選択されています。デフォルトでは [サンプル値(Example Value)] タブが選択されているため、ドキュメンテーションを表示するためには常に [モデル(Model)] をクリックする必要があります。


API エクスプローラ内の POST object/tcpports ドキュメンテーション。


オブジェクト ID(objId)と親 ID の検索

一部のリソースでは、URL に次のようなオブジェクト ID または関連する親オブジェクト ID が必要です。

  • PUT /object/networks/{objId}

  • GET /policy/intrusionpolicies/{parentId}/intrusionrules

ほとんどの場合、リソース階層の 1 レベル上で GET メソッドを使用すると、オブジェクトまたは親 ID を入手できます。オブジェクト/親 ID は、与えられたオブジェクトの id パラメータの UUID です。

たとえば、GET /object/networks は、現在定義されているすべてのネットワーク オブジェクトのリストを返します。場合によっては、目的のオブジェクトに到達するまでリスト中のページに複数のコールを実行したり、limit クエリパラメータを含めてコールで返されるオブジェクト数を増加させたりする必要があります。各オブジェクトは次の形式であり、オブジェクト ID は強調表示しています。


{
      "version": "9bbb9e5d-8115-11e7-8cb4-772d7eb1894d",
      "name": "any-ipv4",
      "description": null,
      "subType": "NETWORK",
      "value": "0.0.0.0/0",
      "isSystemDefined": true,
      "id": "9bbbc56e-8115-11e7-8cb4-01865c95f930",
      "type": "networkobject",
      "links": {
        "self": "https://ftd.example.com/api/fdm/[最新(latest)]/object/networks/
9bbbc56e-8115-11e7-8cb4-01865c95f930"
      }


(注)  


いくつかのケースでは、{objId} は階層のトップレベルで発生します。これらのケースでは、オブジェクト ID に任意の値を入力し、同じ結果が得られることがあります。他のケースでは、有効なオブジェクトのタイプに関する情報をオブジェクト モデル ドキュメントで確認します。ID は有効なタイプの 1 つです。これらは常に GET コールです。たとえば、GET /operational/systeminfo/{objId} や GET /operational/featureinfo/{objId} です。


エラーカタログの表示とエラーメッセージの評価

REST API として、存在しないオブジェクトに対して GET を実行した場合は、404 などの標準の HTTP エラーコードが返されます。

また、エラーをより具体的に説明するエラーメッセージがいくつかシステムに組み込まれています。API コールでエラーが発生した場合は、応答本文にこれらの具体的なメッセージが含まれる可能性があります。

たとえば、次のネットワークオブジェクトについて POST /object/networks を実行しようとすると、エラーが発生します。この場合、ネットワークを指定しようとしていますが、ネットマスクを含めることを忘れています(つまり、値を 10.10.10.0/24 または 10.10.10.0/255.255.255.0 のいずれかにする必要があります)。


{
  "name": "test-network",
  "subType": "NETWORK",
  "value": "10.10.10.0",
  "type": "networkobject"
}

結果として、422 の HTTP 応答コードと、特定のエラーメッセージを含む応答本文が表示されます。


{
  "error": {
    "severity": "ERROR",
    "key": "Validation",
    "messages": [
      {
        "description": "The type Network requires a netmask. To specify a single host, either use the type Host, or use {0}/255.255.255.255.",
        "code": "networkWithoutNetmask",
        "location": "value"
      }
    ]
  }
}

次の手順では、応答本文で返される可能性のあるエラーメッセージのリストを表示する方法について説明します。

手順


ステップ 1

Device Manager で [詳細オプション(More options)] ボタン([その他のオプション(More options)] ボタン。)をクリックし、[APIエクスプローラ(API Explorer)] を選択します。

ステップ 2

目次の [エラーカタログ(Error Catalog)] をクリックします。

メッセージには次のコンポーネントがあります。

  • [カテゴリ(Category)]:メッセージの一般タイプ。この値は、エラー応答本文の key 属性に表示されます。カテゴリには、検証(Validation)、一般(General)、展開(Deployment)などがあります。

  • [コード(Code)]:エラーメッセージを識別する固有の文字列。この値は、エラー応答本文の code 属性に表示されます。ブラウザの [ページで検索(Find On Page)] 機能を使用して、この値を使用しているカタログ内のメッセージを検索できます。

  • [メッセージ(Message)]:エラーを説明する具体的なメッセージ。この値は、エラー応答本文の description 属性に表示されます。メッセージ内の変数は、{0}、{1} などと示されます。