API ペイロードと XML のタグ
ファイアウォールの API は、XML ペイロードを使用してデータを送受信します。
API ペイロード
ファイアウォールは設定リクエストに対して、標準の GET、POST、PUT、DELETE メソッドではなく、HTTP POST メソッドを使用します。特定の操作に対して、ペイロード内でカスタム XML タグを使用します。
たとえば、ファイアウォールで新しいオブジェクトを作成する場合は、リクエストの本文に <Set>
タグを含めてオブジェクトの属性と値を指定します。ファイアウォールは、HTTP POST メソッドを使用して送信されるこれらのカスタムタグのみを受け付けます。
ペイロードは、次の URL を使用して送信する必要があります。
https://<ファイアウォールの IP アドレス>:<ポート>/webconsole/APIController
IP アドレスには、Web 管理コンソールの IP アドレスまたはホスト名を使用できます。ポートは、「管理 > 管理の設定」で指定した管理コンソールの HTTPS ポートです。
XML タグ
ファイアウォールでは、次のカスタムタグを使用します。
<Request>
: API にリクエストを送信するには、このタグを使用します。API バージョンはオプションであり、バージョン固有の構文が必要となります。-
<Login>
: このタグを使用して、ファイアウォールで API リクエストを認証します。例
<Request APIVersion="1905.2"> <Login> <Username>username</Username> <Password>password</Password> </Login> </Request>
-
<Set operation="add">
または<Set operation="update">
: Set タグを使用して、追加または更新操作を実行します。-
"add" を使用して、新しいオブジェクト、ルール、ポリシーを作成できます。
-
SSL/TLS インスペクションの設定など、追加できない設定を変更するには "update" を使用します。これらの設定は更新のみ行えます。
"operation" タグを指定しない場合は、追加リクエストと見なされます。SSL/TLS インスペクションの設定など、追加に対応していないオブジェクトの場合、このリクエストはエラーになります。
例
<Request> <Login> <Username>username</Username> <Password>password</Password> </Login> <Set operation="add"> <IPHost> <Name>IPaddress</Name> <IPFamily>IPv4</IPFamily> <HostType>IP</HostType> <IPAddress>1.1.1.1</IPAddress> </IPHost> </Set> </Request>
-
-
<Get>
: このタグを使用して、ファイアウォールからデータを取得します。例
<Request> <Login> <Username>username</Username> <Password>password</Password> </Login> <Get> <IPHost></IPHost> </Get> </Request>
-
<Remove>
: このタグを使用して、ファイアウォールからデータを削除します。SSL/TLS インスペクションの設定などは削除できません。これらの設定は更新のみ行えます。例
<Request> <Login> <Username>username</Username> <Password>password</Password> </Login> <Remove> <IPHost> <Name>CustomName</Name> </IPHost> </Remove> </Request>
-
<Filter>
: このタグを使用して、オブジェクト名などの特定の条件に基づいてファイアウォールからデータを取得します。<key> タグと "name"、"criteria" の属性値を使用して条件を指定します。criteria に指定可能な値: [
=
,!=
,like
]例
Request> <Login> <Username>username</Username> <Password>password</Password> </Login> <Get> <IPHost> <Filter> <key name="Name" criteria="like">IP ホストの名前</key> </Filter> </IPHost> </Get> </Request>
-
<Response>
: このタグには、API リクエストへの応答が含まれます。 <Status>
: このタグは<Response>
タグの一部であり、API リクエストのステータスを示します。-
transactionid
: この属性は、リクエストおよび応答トランザクションの整合性を保証します。これは、<Set> タグに追加可能な属性です。使用する場合は、英数字の値にすることをお勧めします。例
<Request> <Login> <Username>username</Username> <Password>password</Password> </Login> <Set transactionid="xyz123"> <IPHost> <Name>IPaddress</Name> <IPFamily>IPv4</IPFamily> <HostType>IP</HostType> <IPAddress>1.1.1.1</IPAddress> </IPHost> </Set> </Request>
API ヘルプ
API ヘルプでは、ファイアウォールで使用されるタグ、属性、ステータスコードを確認できます。API ヘルプを参照してください。
XML リクエストの表記方法については、API ヘルプの各メニューの設定例を参照してください。
各モジュールの左側のメニューと属性は、Web 管理コンソールの設定項目に対応しています。属性について詳しくは、該当するヘルプページを参照してください。
API リクエストのトラブルシューティング
MFA の設定またはトークンをインポートできません。
空白の <tokenid/>
属性を含める必要があります。
ユーザーを削除できません。
次の構文を使用して、ユーザー名を指定する必要があります。<Name><username></Name>