主要な概念

API Gatewayのアーキテクチャと実装について学ぶ前に、その基本的な概念を詳しく理解することが重要です。

API Gateway対Security Rules

Catalyst API Gatewayは、API管理のための追加機能を提供するCatalyst Security Rulesの拡張です。

覚えておくべきポイント：

• API Gatewayはいつでも有効化または無効化できます。
• API Gatewayが無効の場合、Security Rulesで定義されたCatalyst関数の設定がデフォルトで適用されます。
• CatalystアプリケーションでAPI Gatewayを有効にすると、Security Rulesは自動的に無効になります。
• API Gatewayを有効にすると、関数とWebクライアントのURLは、APIを作成するまで直ちにアクセスできなくなります。そのため、API Gatewayを有効にした場合は、すべての関数とWebクライアントに対してAPIを作成する必要があります。
• 自動作成を使用して、Security Rules内の関数の設定をAPI Gatewayに移行できます。

Security RulesとAPI Gatewayの違いは以下の通りです：

ルーティング

API Gatewayの主な目的は、クライアントを適切なサービスにルーティングすることです。これは、APIの2つの側面であるリクエストとターゲットによって定義されます。特定のリクエストメソッドまたはリクエストURLに対してAPIが設定されていない場合、クライアントはターゲットにアクセスできません。

これらについて詳しく見ていきましょう。

リクエストメソッド

Catalyst API Gatewayは以下のHTTPリクエストメソッドをサポートしています：

• GET
• PUT
• POST
• DELETE
• PATCH

これらすべてのHTTPメソッドをカスタム定義メソッドANYに集約することもできます。これにより、5つのメソッドそれぞれに個別のAPIを作成する代わりに、すべての5つのメソッドをサポートする関数に対して単一のAPIを作成できます。ANYは自動作成とカスタムAPIの作成の両方で使用できます。

リクエストURL

CatalystアプリケーションのURLは次の構造を持ちます：https://project_domain_name.catalystserverless.com。APIを作成する際にリクエストパスを定義すると、このURLに自動的に追加されます。これがリクエストURLになります。

例えば、リクエストパスが_/CustomerPortal/create_の場合、そのプロジェクトのアプリケーションURLに追加され、次のリクエストURLが作成されます：https://shipmenttracking-61317105.catalystserverless.com/CusomerPortal/create。

ターゲット関数やWebクライアントのデフォルトURLの代わりに、この中間リクエストURLをクライアントに提供できます。APIはこのリクエストURLを設定されたターゲットに自動的にルーティングします。

ターゲットとターゲットURL

前述の通り、API Gatewayで設定されたAPIのターゲットコンポーネントは、Basic I/O Functions、Advanced I/O Functions、Webクライアントです。API Gatewayで作成する各APIに対して1つのターゲットを設定できます。異なるリクエストメソッドに対して各ターゲットに複数のAPIを作成できます。

各ターゲットのURL形式は以下の通りです：

• Basic I/O: https://project_domain_name.catalystserverless.com/baas/v1/ project/project_ID/function/function_ID/execute
• Advanced I/O: https://project_domain_name.catalystserverless.com/server/function_name/
• Web Client: https://project_domain_name.catalystserverless.com/app/

Advanced I/O FunctionまたはWebクライアントのターゲットURLにルートを追加して、特定のパスに対するAPIを作成できます。

リクエストURLとターゲットURLでの正規表現（Regex）の使用

Catalystは、リクエストURL内の動的な値を保持するための正規表現をサポートしています。正規表現（regex）は、検索パターンを記述する文字のシーケンスです。リクエストURLにregexパターンを含めると、実行時に入力値が提供された際にパターンマッチングおよび検索と置換のアルゴリズムが実行され、パターンが動的な値に置き換えられます。

リクエストURLにJSON形式でregexパターンを入力し、ターゲットURLにキーを渡すことができます：
リクエストURL: /route/{path:[0-9]+}
ターゲットURL: /route/{path}

例えば、リクエストURLの動的な値が数字の文字列を含む場合、式_[0-9]+を使用できます。これは、動的な値のブラケット内の文字が0〜9の任意の数字の範囲であることを示し、+*は数字の1回以上の出現を示します。したがって、ここでのリクエストURLは次のように設定できます：/CustomerPortal/{portalID:[0-9]+}。Advanced I/O FunctionのターゲットURLにルートを追加して次のようにすると：/server/adIOFunc/CustomerPortal/{portalID}_、ユーザーがアクセス時にリクエストURLで提供したIDが、ターゲットのAdvanced I/O Functionに動的に渡されます。

正規表現でワイルドカードパターンを使用することもできます。例えば.は、ワイルドカードパターンの位置に任意の数のリテラル文字または空文字列を受け入れることを示します。例えば、リクエストURLに次のようなワイルドカードパターンを指定すると：/CustomerPortal/{path:(.*)}、ユーザーはURL内に_/CustomerPortal/johndoe12_、/CustomerPortal/premiumUser/12809021、_/CustomerPortal/xae89013_のような任意の値を動的に入力できます。

Security RulesでAdvanced I/O FunctionのURLにregexパターンを定義した場合、自動作成時に同じパターンがリクエストURLとターゲットURLの両方に追加されます。

認証リクエストプロセッサ

リクエストプロセッサはAPIの認証を処理します。認証はAPI Gatewayのオプション機能です。APIの作成時にNo Authenticationを選択すると、ターゲットはすべてのクライアントに対してユニバーサルにアクセス可能になります。

API Gatewayは3つの認証方法をサポートしています。これらの方法のいずれかまたはすべてを有効にできます。

APIキー

この認証は、Catalystがプロジェクトに対して自動的に生成するAPIキーによって処理されます。APIキーは開発環境のすべてのプロジェクトで共通です。Catalystプロジェクトを本番環境にデプロイすると、Catalystは異なるAPIキーを提供します。そのため、本番環境では各プロジェクトに個別のAPIキーが割り当てられます。

APIキー認証オプションを有効にして、プロジェクト内のBasic I/OまたはAdvanced I/O Functionに対してAPIを作成した後、APIキーを取得できます。API詳細セクションでView API Keyをクリックしてキーにアクセスします。

APIキーが表示されるポップアップウィンドウが開きます。

APIキーは2つの方法で渡すことができます：

• リクエストヘッダー
  リクエストURLのヘッダーとしてAPIキーを渡すことができます。以下に例を示します：
  

curl -X POST \
https://shipmenttracking-61317105.catalystserverless.com/CustomerPortal/create \
-H "ZCFKEY: API_KEY"

• クエリ文字列
  リクエストURLのクエリパラメータとしてAPIキーを渡すこともできます。以下に例を示します：
  

POST https://shipmenttracking-61317105.catalystserverless.com/CustomerPortal/
create?ZCFKEY=API_KEY

両方の箇所でAPI_KEYを実際のAPIキーに置き換えてください。

Catalystユーザー認証

この認証方法は、デフォルトでCatalyst Authenticationの_Users_セクションに追加されたCatalystアプリケーションのすべてのユーザーにアクセスを許可します。Catalystアプリケーションにユーザーサインインフォームを組み込み、ログインセッションを有効にすることで、この認証方法を管理できます。アプリユーザーは、追加のユーザー検証を行うことなく、APIのターゲットに自動的にアクセスできるようになります。

OAuthベース認証

この認証方法は、OAuthアクセストークンを持つユーザーにアクセスを許可します。

リクエストURLのヘッダーとしてアクセストークンを渡すことができます。以下に例を示します：

curl -X POST \
https://shipmenttracking-61317105.catalystserverless.com/CustomerPortal/create \
-H "Authorization: Zoho-oauthtoken Zoho-oauthtoken 1000.910*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*16.2f*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*57""

CatalystアプリケーションにOAuth認証を実装するには、OAuth認証ヘルプドキュメントを参照して詳細な手順をご確認ください。

スロットリング

スロットリングを使用すると、クライアントによるAPIの使用を制御するためのレート制限を設定できます。スロットリングはCatalyst API Gatewayのオプション機能です。APIにスロットリングのレート制限を設定すると、CatalystはそのAPIに対するリクエストヒット数を監視します。リクエスト送信がAPIに設定した制限を超えると、API GatewayはHTTPエラーレスポンス429 Too Many Requestsを返します。

API Gatewayには2種類のスロットリングがあります。どちらか一方、または両方の方法を使用できます。

一般スロットリング

一般スロットリングは、時間単位あたりのすべてのユーザーに対するAPIへの最大ヒット数を定義します。APIの作成時にリクエスト制限、そのレート、および時間単位を定義できます。

Catalystはスライディングウィンドウレート制限アルゴリズムを実装しており、ウィンドウは現在の要素から開始し、前のウィンドウのリクエストレートの加重値によってシフトします。例えば、制限を2分間で50リクエストに設定した場合、Catalystは2分間の固定ウィンドウではなく、現在の秒から遡って2分間のAPIヒットを確認してカウントを判定します。

IPベーススロットリング

IPベーススロットリングは、時間単位あたりの特定のIPアドレスからのAPIへの最大ヒット数を定義します。これにより、特定のクライアントアドレスから行えるAPI呼び出しの数が制限されます。一般スロットリングと同様の方法で、リクエスト制限、そのレート、および時間単位を定義できます。

自動作成API、カスタムAPI、およびデフォルトAPI

選択した関数またはWebクライアントに対して、自動作成またはカスタムの2つの方法でAPIを作成できます。

自動作成APIとカスタムAPIについて説明する前に、デフォルトAPIについて理解する必要があります。

デフォルトAPI

API Gatewayは、Catalystプロジェクトでホストされているウェブクライアントに対して、通常のWebクライアントAPIに加えて、Login RedirectというデフォルトAPIを作成します。

Login Redirect APIには以下のルールが適用されます：

• このAPIは、CatalystプロジェクトでWebクライアントをホストした後、自動作成またはカスタム方法のいずれかを使用してAPI Gatewayで初めてAPIを作成する際に作成されます。
• Login Redirect APIは、Webクライアント用のclient-package.jsonファイルで設定された構成に基づいて作成されます。そのファイルでlogin_redirectとして設定されたURLが、APIのリクエストURLおよびターゲットURLとして設定されます。login_redirectキーはオプションです。そのため、設定されていない場合は、homepageとして提供されたURLがリクエストURLおよびターゲットURLとして設定されます。
• login_redirectとして設定されたURLが’/‘で始まる場合、Catalystはそれを絶対パスとみなし、ドメインに直接追加します。例えば、login_redirectが’/home.html‘の場合、リクエストURLは次の形式になります：https://project_domain_name.catalystserverless.com/home.html。ただし、login_redirectの値が’/‘で始まらない場合、例えば’home.html‘の場合、リクエストURLは次の形式になります：https://project_domain_name.catalystserverless.com/app/home.html。
• このデフォルトAPIの一般スロットリングとIPベーススロットリングの値はNot configuredに設定され、認証の値はNo authenticationに設定されます。
• Login Redirect APIのリクエストURLには、Catalystアプリケーションのデフォルトのログインリダイレクトページを指定する必要があります。他のURLをその値として指定してはいけません。
• Login Redirect APIが作成された後にclient-package.jsonファイルでlogin_redirectの値を変更した場合、クライアントパッケージをCatalystコンソールにデプロイした際にターゲットURLの値は自動的に変更されます。
• リクエストURL以外のデフォルト値を編集することはできません。ターゲットURL、API名、認証、またはスロットリングパラメータを変更することはできません。
• Login Redirect APIを削除することはできません。
• デフォルトのLogin Redirect APIと通常のWebクライアントAPIの違いは、Login Redirect APIはユーザーがログイン後にリダイレクトされるアプリケーションのデフォルトのログインリダイレクトページ専用であることです。ただし、通常のWebクライアントAPIでは、WebクライアントのターゲットURLにルートを追加して、異なるルートに対するAPIを作成できます。
• CatalystプロジェクトでWebクライアントをホストしていない場合、このAPIは作成されません。

自動作成API

自動作成方法を使用して、選択した関数またはWebクライアントに対してCatalystに自動的にAPIを作成させることができます。APIの自動作成は、API Gatewayで最初のAPIを作成するまでのみ利用可能です。

自動作成は、Catalystプロジェクトに大量の関数が設定されており、それぞれに個別のAPIを作成するのが非常に時間がかかる場合に使用できます。

自動作成を使用してAPIを作成すると、以下のプロトコルが適用されます：

• Security Rulesで関数の定義を設定している場合、自動作成時にAPI Gatewayに自動的に移行されます。定義を設定していない場合は、デフォルトのルールが適用されます。
• 自動作成時に関数に対して作成されるAPIには、Security Rulesで設定されたHTTPメソッドと認証が含まれます。
• リクエストメソッドとURL:
  
  • Security Rulesで関数に対して5つすべてのHTTPメソッド（GET、PUT、POST、DELETE、PATCH）が有効になっている場合、関数に対してリクエストメソッド’ANY‘の単一のAPIが自動的に作成されます。
  • Security Rulesで関数に対して5つのHTTPメソッドのうち1つ以上が無効になっている場合、他の各メソッドに対して個別のAPIが作成されます。
  • 自動作成では、Security RulesでリクエストURLとターゲットURLが同一であるため、関数のリクエストURLはそのデフォルトのターゲットURLまたは関数URLと同じになります。
  • 関数のリクエストURLにregexパターンがある場合、同じパターンがターゲットURLに割り当てられます。
• 認証:
  
  • Security Rulesで関数の認証方法がoptionalの場合、自動作成時に関数のAPIのリクエストプロセッサは自動的にNo Authenticationに設定されます。
  • Security Rulesで関数の認証が有効になっている場合、API Gatewayで関数のAPIに対してCatalystユーザー認証とOAuthベース認証が自動的に有効になります。
• スロットリング: 自動作成時に、関数のAPIの一般スロットリングとIPベーススロットリングの値はデフォルトでNot configuredに設定されます。
• API名: 自動作成で関数に対して作成されるAPIは、_FunctionName_HTTPMethod_の形式で命名されます。自動作成でWebクライアントに対して作成されるAPIは、_WebclientName_の形式で命名されます。
• WebクライアントAPI: Webクライアントの一般スロットリングとIPベーススロットリングの値はNot configuredに設定されます。前述の通り、WebクライアントAPIでは認証は利用できません。WebクライアントのリクエストURLもそのターゲットWebアプリURLと同じになります。
• ハード制限: 作成可能なAPIのハード制限は1000 API/プロジェクトです。

自動作成を使用して関数とWebクライアントのAPIが作成された後、個々のAPIを編集して必要に応じてデフォルト値を変更できます。

カスタムAPI

関数またはWebクライアントに対していつでもカスタムAPIを作成し、APIのパラメータを設定できます。要件に基づいて、リクエストメソッドとURL、ターゲット、認証方法、スロットリングなどを定義できます。カスタムAPIの作成では、Security Rulesからの関数の設定は移行されません。