SecurityGatewayには、Webインターフェースを介さずに外部アプリケーション、スクリプト、プロビジョニングシステムからプログラムでSecurityGatewayを管理できるREST APIが含まれています。RESTエンドポイントのルートはhttps://<server>:<port>/api/v1です（既定のHTTPSポートは4443です）。すべてのリクエストはAPIキーによる認証が必要です。成功したレスポンスは一貫して{"success": true, "data": ...}の形式になり、ページ分割されたリスト結果にはmetaブロックが追加されます。失敗したリクエストは、error、errorCode、statusCodeを含むJSON本文とともに、HTTPエラーステータスを返します。このAPIは、Webインターフェースで管理できるほとんどのオブジェクトに加え、読み取り専用のパフォーマンスカウンターも対象としています。現行リリースのREST APIは、ユーザー、ドメイン、ドメインエイリアス、管理者、APIキー、サーバー/ドメイン/ユーザー設定、許可リスト、拒否リスト、ドメインメールサーバー、ユーザー検証ソース、DKIMセレクター、アーカイブストア、Sieveコンテンツフィルタスクリプト、IP Shieldエントリ、動的スクリーニングエントリ、Webhookサブスクリプションを対象としています。今後のバージョンでは、さらに多くのエンドポイントと機能が追加される予定です。旧来のXML-RPC APIも引き続き利用できますが、新規の統合には今後REST APIを使用することをお勧めします。
プログラムによるリソースリクエストにはAuthorization: Bearer <key>を使用します。APIキーページ（設定/ユーザー > アカウント > APIキーにあります）で、この目的で使用するキーを作成および管理します。
APIキーの一覧
APIキーページには、アクセス可能なすべてのキーが一覧表示され、キーの作成と管理を行うためのツールバーオプションが用意されています。この一覧には7つの列があり、それぞれの列に対応するボタンで表示/非表示を切り替えることができます。
•名前 - キーを作成した際に付けられた、用途を識別するためのわかりやすい名前です。
•所有者 - キーの作成対象となったユーザーで、そのユーザーのメールアドレスとして表示されます。
•キープレフィックス - キーの先頭の数文字で、キー全体を表示しなくても（アプリケーションの設定などで）特定のキーを識別できるように表示されます。キーの残りの部分は、作成後は二度と表示されません。
•ステータス - キーが有効か無効かを示します。無効化されたキーは削除されずに残り、後で再度有効にできますが、無効な状態でAPIリクエストに使用すると拒否されます。
•作成日 - キーが作成された日付です。
•最終使用日 - キーが最後にAPIリクエストの認証に成功した日付です。一度も使用されていない場合は"Never"と表示されます。
•有効期限 - 作成時に有効期限が設定されている場合、キーが使用できなくなる日付です。有効期限のないキーには"Never"と表示されます。
キーの作成
新しいキーを生成するための、以下で説明するAPIキーの作成ダイアログを開きます。
無効
選択したキーを無効化します。無効化されたキーはこのリストに残り、いつでも再度有効にできますが、無効な間はAPIリクエストの認証に使用できません。
有効
選択したキーを再度有効にし、APIリクエストの認証に使用できる状態に戻します。
削除
確認を求めた後、選択したキーを完全に削除します。キーを無効化する場合と異なり、この操作は元に戻せません。削除されたキーは復元したり再度有効にしたりすることはできず、代わりに新しいキーを作成する必要があります。
誰がどのキーを見られるか
このページに表示される内容は、ご自身の管理者レベルによって異なります。グローバル管理者はシステム内のすべてのAPIキーを閲覧でき、特定のドメインやユーザーに絞り込んで表示することもできます。ドメイン管理者は、自身が管理するドメインに属するユーザーのキーに加えて、自分自身の個人用キーを閲覧できます。管理していないドメインに属するキーや、他のグローバル管理者が所有するキーを閲覧することはできません。グローバル管理者およびドメイン管理者は、メイン > マイアカウント > 設定ページで自分自身のキーを管理できます。
[キーの作成]をクリックすると、以下のオプションを含むダイアログが開きます。
名前
キーの必須項目であるわかりやすい名前です（例：「Provisioning Script」や「Monitoring Integration」など）。後でキーを区別できるようにするためのものです。これは、APIキーの一覧の"名前"列に表示される値と同じです。
有効期限
キーが使用できなくなる日付を任意で指定できます。キーを無期限にしたい場合は、このフィールドを空欄のままにしてください。
権限
このセクションは、直接設定する項目ではなく、情報表示のみを目的としています。新しいAPIキーは、常にそれを作成したアカウントと同じアクセス権で作成されます。グローバル管理者の場合、キーはグローバル管理者権限を持ちます。それ以外の場合、キーは自分のアカウントと同じ権限を持ちます。自分のアカウントが現在持っている権限より狭い、または広い権限を持つキーを作成するオプションはありません。
|
キーのアクセス権は、使用されるたびに所有ユーザーの現在の権限に照らしてチェックされます。キー作成時点でのユーザーの権限ではありません。後でキーの所有者を昇格・降格させたり、管理者権限を制限したり、管理するドメインを変更したりすると、そのユーザーが所有するすべてのAPIキーに直ちにその変更が反映されます。所有ユーザーのアカウントを無効化すると、キー自体が"有効"のままであっても、そのユーザーが所有するすべてのAPIキーがブロックされます。アカウントを削除すると、そのアカウントが所有するすべてのAPIキーも削除されます。 管理者のIP制限は、Webログインの場合と同様にAPIキーにも適用されます。キーの所有ユーザーがIPアドレス制限を設定された管理者である場合、許可されていないIPアドレスからそのキーを使用して行われたリクエストは、Webログインの試行と同様に拒否されます。 |
保存
キーの名前と有効期限を設定したら、[保存]をクリックすると、コピー用のキーが表示されます。
あなたのAPIキー
[保存]をクリックすると、SecurityGatewayはキーを生成し、二度と表示できなくなる旨の警告とともに、そのキーを一度だけ表示します。[コピー]をクリックしてクリップボードにコピーしてください。その後、安全な場所に保管することをお勧めします。コピーせずにダイアログを閉じると、後でキーを取得する方法がないため、SecurityGatewayは確認を求めます。閉じた後は、APIキーの一覧にはプレフィックスのみが表示されたままになります。キーを紛失した場合、アクセスを回復する唯一の方法は、新しいキーを作成し、古いキーを使用していたアプリケーションを更新することです。このダイアログには、認証ヘッダーでキーを使用する際に必要な形式も表示されます。プログラムによるリソースリクエストにはAuthorization: Bearer <key>を使用します。成功したレスポンスには通常dataが含まれますが、deleteなどの一部の成功した変更操作では、それを含まないメッセージが返されます。
APIドキュメント
完全なREST APIリファレンスは、スタートガイドおよび従来のXML-RPCドキュメントとともに、SecurityGatewayのインストールディレクトリ内のDocs\APIフォルダにローカルインストールされています。閲覧するために、稼働中のサーバーへのネットワークアクセスは必要ありません。
README.md
ベースURL、認証、レスポンスおよびエラーの形式について説明するクイックスタートガイドです。既存のXML-RPC統合向けの移行ガイドも含まれており、メソッドとエンドポイントの対応表や、ドメインの作成、ユーザーの更新、設定の読み書きに関する実例を掲載しています。
api_openapi.html
完全なAPIリファレンスを閲覧できる、人が読みやすい形式のコピーです。
api_openapi.json
そのリファレンスの基になる、機械可読なOpenAPI仕様です。Postmanなどのツールへのインポートや、OpenAPI対応のコードジェネレーターでの使用に適しています。これは、/api/v1/openapiで提供されているものと同じファイルです。
XMLRPC
既存のXML-RPC統合を保守している管理者のために残されている、旧来のXML-RPC API用のリファレンスドキュメントと動作するコードサンプル（PowerShellおよびPython）です。XML-RPCは非推奨であり、新規の統合は、READMEの移行ガイドを出発点として、上記で説明したREST APIを基に構築する必要があります。
