APIゲートウェイの概念

APIゲートウェイ・サービスでは、APIゲートウェイはリージョナル・サブネットの仮想ネットワーク・アプライアンスです。

APIゲートウェイは、インバウンド・トラフィックを、パブリック、プライベート、パートナのHTTP APIなどのバックエンド・サービスとOCI Functionsにルーティングします。各APIゲートウェイは、パブリックIPアドレスをパブリックAPIゲートウェイとしてオプションで公開できるプライベート・エンドポイントです。

プライベートAPIゲートウェイには、APIゲートウェイのプライベートIPアドレスにルーティングできるリソースのみがアクセスできます。たとえば、同じプライベート・ネットワーク(VCN)内のリソース、またはそのプライベート・ネットワークにピアリングされている別のプライベート・ネットワークまたはオンプレミス・ネットワーク内のリソースによって。APIゲートウェイのVCNにインターネット・ゲートウェイが存在する場合は、パブリックAPIゲートウェイにパブリックにアクセスでき、インターネットからアクセスできます。

高可用性を確保するために、AD固有のサブネットではなくリージョナル・サブネットでのみAPIゲートウェイを作成できます。プライベート・サブネットまたはパブリック・サブネットでプライベートAPIゲートウェイを作成できますが、パブリック・サブネットでのみパブリックAPIゲートウェイを作成できます。API Gatewayサービスは、アベイラビリティ・ドメイン(複数のADリージョン内)およびフォルト・ドメイン(単一のADリージョン内)にわたり、有効範囲が広く、フォルト・トレラントです。複数ADリージョンでは、APIゲートウェイ・サービスは、アクティブな可用性ドメインを自動的に選択してAPIゲートウェイ・エンドポイントを終了します。トラフィックのソースと宛先によっては、トラフィックがアベイラビリティ・ドメインをまたいでルーティングされる場合があります。アベイラビリティ・ドメインまたはフォルト・ドメインに障害が発生した場合、API Gatewayサービスは自動的にフェイルオーバーを処理し、機能しているアベイラビリティ・ドメインまたはフォルト・ドメインにトラフィックをルーティングします。

APIゲートウェイは、特定のVNICにバインドされます。

テナンシのコンパートメント内にAPIゲートウェイを作成します。各APIゲートウェイには、1つのフロント・エンド、ゼロ個以上のバック・エンドがあり、APIデプロイメントとしてデプロイされたAPIがゼロ個以上あります。

APIゲートウェイ・サービスにおけるAPIとは、バックエンド・リソースと、APIクライアントから送信されたリクエストに応じて各バックエンド・リソースで実行できるメソッド(たとえば、GET、PUT)のセットです。

APIゲートウェイを有効にしてAPIリクエストを処理するには、APIデプロイメントを作成することでAPIゲートウェイにAPIをデプロイする必要があります。

APIゲートウェイ・サービスには、APIゲートウェイにAPIをデプロイする場合にAPIリソースを作成するオプションがあります。APIリソースには、そのAPIリソースを定義するAPI記述が含まれます。APIリソースの作成はオプションです。APIゲートウェイ・サービスでは、APIリソースを作成しなくてもAPIゲートウェイにAPIをデプロイできます。

APIゲートウェイ・サービスでは、APIデプロイメントとは、APIゲートウェイにAPIをデプロイするための手段です。APIゲートウェイがAPIへのリクエストを処理するには、APIデプロイメントを作成する必要があります。

APIデプロイメントを作成するときには、APIデプロイメントのプロパティ(APIデプロイメント仕様を含む)を設定します。すべてのAPIデプロイメントには、APIデプロイメント仕様があります。

複数のAPIを同じAPIゲートウェイにデプロイできるため、単一のAPIゲートウェイで複数のAPIデプロイメントをホストできます。

APIゲートウェイ・サービスでは、APIデプロイメント仕様はAPIデプロイメントの一部の側面を示しています。

APIデプロイメントを作成するときには、APIデプロイメントのプロパティ(APIデプロイメント仕様を含む)を設定します。すべてのAPIデプロイメントには、APIデプロイメント仕様があります。APIデプロイメント仕様を作成するには、次を実行します:

• コンソールのダイアログを使用する
• 任意のJSONエディタを使用してJSONファイルを作成する
• (OpenAPI Specificationバージョン3.0などの)サポートされている言語で記述されたAPI記述ファイルからアップロードしたAPI記述を使用する

各APIデプロイメント仕様では、1つ以上のバックエンド・リソース、各バックエンド・リソースへのルート、各リソースで実行可能なメソッド(たとえば、GET、PUT)を記述します。APIデプロイメント仕様では、APIゲートウェイとバック・エンドを統合してそれらのメソッドを実行する方法が示されています。APIデプロイメント仕様には、リクエスト・ポリシーおよびレスポンス・ポリシーを含めることもできます。

APIゲートウェイ・サービスには、APIリソースを作成するオプションがあります。APIリソースとは、APIの設計時表現です。APIリソースを使用して、APIゲートウェイにAPIをデプロイできます。

API記述では、次のようなAPIリソースを定義します:

• 使用可能なエンドポイント
• 各エンドポイントで使用可能な操作
• 各操作で入力および出力できるパラメータ
• 認証方式

APIリソースを使用してAPIゲートウェイにAPIをデプロイする場合、そのAPI記述によってAPIデプロイメント仕様のプロパティの一部が事前に移入されます。

サポートされている言語で記述されたファイル(「API仕様」や「API spec」とも呼ばれる)からAPI記述をインポートします。現在、OpenAPI Specificationバージョン2.0 (以前のSwagger Specification 2.0)およびバージョン3.0がサポートされています。

API記述ファイルからSDKを生成することもできます。

APIゲートウェイ・サービスでのAPIリソースの作成はオプションです。APIゲートウェイ・サービスでは、APIリソースを作成しなくてもAPIゲートウェイにAPIをデプロイできます。また、最初はAPI記述のないAPIリソースを作成し、後からAPI記述を追加することもできます。

APIゲートウェイ・サービスでは、フロント・エンドはリクエストがAPIゲートウェイに流れる手段です。APIゲートウェイには、パブリック・フロント・エンドまたはプライベート・フロント・エンドのいずれかを指定できます:

• パブリック・フロント・エンドでは、パブリックIPアドレス経由でAPIゲートウェイにデプロイされているAPIが公開されます。
• プライベート・フロント・エンドでは、APIゲートウェイにデプロイされているAPIがプライベート・エンドポイント経由でVCNに公開されます。

APIゲートウェイ・サービスでは、バック・エンドは、ゲートウェイでAPIを実装するバックエンド・サービスにリクエストをルーティングする手段です。プライベート・エンドポイント・バック・エンドをAPIゲートウェイに追加する場合、そのプライベート・エンドポイントに関連付けられているVCNへのAPIゲートウェイ・アクセス権を付与します。

また、バック・エンドとして他のOracle Cloud InfrastructureサービスへのAPIゲートウェイ・アクセス権を付与できます。たとえば、OCIファンクションへのAPIゲートウェイ・アクセス権を付与できるため、サーバーレス・ファンクションに連動するAPIを作成およびデプロイできます。

APIプロバイダは、APIを設計、実装、提供および操作する個人またはチームです。これらのユーザーは、Oracle Cloud Infrastructureコンソール、SDK、CLI、Terraformプロバイダなどのインタフェースと対話します。また、APIゲートウェイ・サービスを使用して、APIをデプロイ、モニターおよび操作します。組織によっては、APIプロバイダ・ロールをさらに次のようなセグメントに分けることもあります:

• API開発者: APIの構築およびAPIゲートウェイへのデプロイを担当します
• APIプラン・マネージャ。APIの使用状況の監視および管理を担当します(たとえば、使用プランおよびサブスクライバの定義)。
• APIゲートウェイ・マネージャ。通常は本番環境でのAPIゲートウェイの管理を担当します。

APIコンシューマは、アプリケーションおよびサービス(APIクライアント)を構築し、APIプロバイダにより提供された1つ以上のAPIを利用しようとする個人またはチームです。APIコンシューマは通常、APIプロバイダとOracle Cloud Infrastructureテナンシを共有していません。APIコンシューマはAPIプロバイダのカスタマです。

APIクライアントは、APIコンシューマによって作成されたアプリケーションまたはデバイスです。APIクライアントは、APIがデプロイされたAPIゲートウェイにリクエストを送信することで、実行時にAPIを呼び出します。APIクライアントは、HTTPS (HTTP/2を含む)を介してAPIゲートウェイと通信します。APIクライアントは、通常はOAuth、Basic Auth、mTLSを使用してAPIで認証し、場合によっては測定や収益化のためにAPIキーなどの他のトークンを使用することもあります。

エンド・ユーザーはAPIクライアントのユーザーであり、認可の観点から「リソース所有者」と呼ばれることもあります。エンド・ユーザーは、APIクライアントを使用してAPIと対話するのみで、通常はAPI自体を意識することはありません。エンド・ユーザーはAPIコンシューマのカスタマです。

APIゲートウェイ・サービスでは、APIプラン・マネージャは、使用プラン・リソースおよびサブスクライバ・リソースを定義することで、APIの使用状況を管理および監視できます。

使用プラン・リソースは権限で構成されます。各権限は次を指定します。

• レート制限: 1秒当たりに許可されるAPIリクエストの最大数。
• 割当て: 特定の期間(1分から1か月)に許可されたAPIコールの合計数。
• 1つ以上のターゲットAPIデプロイメント。使用プランをサブスクライブするAPIデプロイメントには、アクセス権が付与されます。

1つのAPIデプロイメントを、異なる使用プランの複数の資格のターゲットとして指定できますが、同じ使用プランの複数の資格に指定することはできません。権限には、様々なAPIゲートウェイからのAPIデプロイメントを含めることができます。

APIプラン・マネージャとして使用プランを使用すると、顧客(APIコンシューマ)とそのAPIクライアントが使用できるAPIアクセスを制御できます。特定の顧客のニーズに合せて調整されたレート制限および割当て制限に従ってAPIアクセスを行うことができ、様々な顧客に対して異なるアクセス層を設定できます。

サブスクライバ・リソースは次のもので構成されます。

• 単一のAPIコンシューマ。
• APIコンシューマによって作成されたAPIクライアントを一意に識別するためのクライアント名およびクライアント・トークン。
• APIコンシューマおよびそのAPIクライアントがサブスクライブされる使用プラン。

APIプラン・マネージャとして、顧客(APIコンシューマ)のサブスクライバを作成して、APIクライアントにAPIへのアクセス権を付与する使用プランを指定できます。

APIデプロイメントを使用プランに含めることができるようにするには、リクエストに渡されるクライアント・トークンの場所を指定します。APIデプロイメントを使用プランに含めると、APIデプロイメントにアクセスするには、リクエストにこの場所にクライアント・トークンを含める必要があります。APIデプロイメント仕様の使用プラン・リクエスト・ポリシーでクライアント・トークンの場所を指定します。(サブスクライバ・リソースで定義するクライアント・トークンは、使用プランの報告のみを目的としており、クライアントの認証および認可のためではありません。)

APIゲートウェイ・サービスでは、ルートはパス、1つ以上のメソッド、およびバックエンド・サービス間のマッピングです。ルートはAPIデプロイメント仕様で定義されます。

APIゲートウェイ・サービスには、様々なタイプのポリシーがあります:

• リクエスト・ポリシーでは、APIクライアントから受信したリクエストをバックエンドに送信する前に実行するアクションを記述します
• レスポンス・ポリシーでは、バックエンドから返されたレスポンスをAPIクライアントに送信する前に実行するアクションを記述します
• ロギング・ポリシーでは、APIゲートウェイを経由するリクエストおよびレスポンスに関する情報と、APIゲートウェイ内での処理に関する情報を格納する方法を記述します

リクエスト・ポリシーまたはレスポンス・ポリシー(あるいはその両方)は、次の目的で使用できます:

• バックエンド・サービスに送信するリクエスト数を制限します
• CORS (Cross-Origin Resource Sharing)サポートを有効にします
• 認証および認可を提供します
• リクエストをバックエンド・サービスに送信する前に検証します
• 受信リクエストおよび送信レスポンスを変更します
• サブスクライバ・アクセスを監視および管理する使用プランにAPIデプロイメントを含めることを許可する

APIデプロイメント仕様のすべてのルートにグローバルに適用されるポリシーをAPIデプロイメント仕様に追加できます。また、特定のルートのみに適用されるポリシーを追加することもできます。

APIゲートウェイ・ポリシーは、Oracle Cloud Infrastructureリソースへのアクセスを制御するIAMポリシーとは異なることに注意してください。