--- title: "主要な概念" url: https://docs.catalyst.zoho.com/ja/cloud-scale/help/api-gateway/key-concepts/ description: "Catalyst API Gatewayを使用すると、アプリの関数やWebクライアントのエンドポイントにアクセスするためのAPIを作成し、高度なAPI管理を実行できます。" last_updated: 2026-08-17T12:16:04Z service: Cloud Scale type: general --- # 主要な概念 API Gatewayのアーキテクチャと実装について学ぶ前に、その基本的な概念を詳しく理解することが重要です。 ### API Gateway対Security Rules Catalyst API Gatewayは、API管理のための追加機能を提供する[Catalyst Security Rules](https://docs.catalyst.zoho.com/ja/serverless/help/security-rules/introduction)の拡張です。 覚えておくべきポイント： * API Gatewayはいつでも有効化または無効化できます。 * API Gatewayが無効の場合、Security Rulesで定義されたCatalyst関数の設定がデフォルトで適用されます。 * CatalystアプリケーションでAPI Gatewayを有効にすると、Security Rulesは自動的に無効になります。 * API Gatewayを有効にすると、関数とWebクライアントのURLは、APIを作成するまで直ちにアクセスできなくなります。そのため、API Gatewayを有効にした場合は、すべての関数とWebクライアントに対してAPIを作成する必要があります。 * [自動作成](https://docs.catalyst.zoho.com/ja/cloud-scale/help/api-gateway/key-concepts/#auto-created-apis-custom-apis-and-the-default-api)を使用して、Security Rules内の関数の設定をAPI Gatewayに移行できます。 Security RulesとAPI Gatewayの違いは以下の通りです：
Security Rules API Gateway
GET、PUT、POST、DELETE、PATCHのHTTPメソッドに対するアクセスを設定可能 GET、PUT、POST、DELETE、PATCHのHTTPメソッドに対するアクセスを設定可能。また、すべてのHTTPメソッドをANYに集約し、単一のAPIを作成することも可能。
リクエストURLとターゲットURLが同一 カスタムのリクエストURLとターゲットURLを個別に設定可能。各URLに対して各リクエストメソッドごとに個別のAPIを作成可能
認証の有効化/無効化と2種類の認証設定が可能：Catalystユーザー認証、およびOAuthベース認証 認証の有効化/無効化と3種類の認証設定が可能：APIキー、Catalystユーザー認証、およびOAuthベース認証
スロットリング機能なし 2種類のスロットリングを設定可能：一般スロットリングとIPベーススロットリング
Webクライアントのルールは設定不可 Webクライアント用のAPIを作成可能
### ルーティング API Gatewayの主な目的は、クライアントを適切なサービスにルーティングすることです。これは、APIの2つの側面であるリクエストとターゲットによって定義されます。特定のリクエストメソッドまたはリクエストURLに対してAPIが設定されていない場合、クライアントはターゲットにアクセスできません。 これらについて詳しく見ていきましょう。 #### リクエストメソッド Catalyst API Gatewayは以下のHTTPリクエストメソッドをサポートしています： * **`GET`** * **`PUT`** * **`POST`** * **`DELETE`** * **`PATCH`** これらすべてのHTTPメソッドをカスタム定義メソッド`ANY`に集約することもできます。これにより、5つのメソッドそれぞれに個別のAPIを作成する代わりに、すべての5つのメソッドをサポートする関数に対して単一のAPIを作成できます。`ANY`は[自動作成とカスタムAPIの作成](https://docs.catalyst.zoho.com/ja/cloud-scale/help/api-gateway/key-concepts/#auto-created-apis-custom-apis-and-the-default-api)の両方で使用できます。 > **注意:** WebクライアントAPIは`ANY`をサポートしていません。Webクライアントには`GET`メソッドのみ選択できます。 #### リクエスト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を作成できます。 > **注意:** API Gatewayは[Cron FunctionsおよびEvent Functions](https://docs.catalyst.zoho.com/ja/serverless/help/functions/event-functions)のクライアントリクエストを処理しません。これらはエンドユーザーが直接実行できないためです。 各ターゲットの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](https://docs.catalyst.zoho.com/ja/serverless/help/security-rules/introduction)でAdvanced I/O FunctionのURLにregexパターンを定義した場合、[自動作成](https://docs.catalyst.zoho.com/ja/cloud-scale/help/api-gateway/key-concepts/#auto-created-apis-custom-apis-and-the-default-api)時に同じパターンがリクエストURLとターゲットURLの両方に追加されます。 ### 認証リクエストプロセッサ リクエストプロセッサはAPIの認証を処理します。認証はAPI Gatewayのオプション機能です。APIの作成時に`No Authentication`を選択すると、ターゲットはすべてのクライアントに対してユニバーサルにアクセス可能になります。 > **注意:** 認証機能はWebクライアントAPIでは利用できません。Basic I/OおよびAdvanced I/O Functionsでのみ利用可能です。 API Gatewayは3つの認証方法をサポートしています。これらの方法のいずれかまたはすべてを有効にできます。 #### APIキー この認証は、Catalystがプロジェクトに対して自動的に生成するAPIキーによって処理されます。APIキーは開発環境のすべてのプロジェクトで共通です。[Catalystプロジェクトを本番環境にデプロイ](https://docs.catalyst.zoho.com/ja/deployment-and-billing/environments/production-environment)すると、Catalystは異なるAPIキーを提供します。そのため、本番環境では各プロジェクトに個別のAPIキーが割り当てられます。 APIキー認証オプションを有効にして、プロジェクト内のBasic I/OまたはAdvanced I/O Functionに対してAPIを[作成](https://docs.catalyst.zoho.com/ja/cloud-scale/help/api-gateway/implementation/#create-an-api)した後、APIキーを取得できます。API詳細セクションで**View API Key**をクリックしてキーにアクセスします。 ![catalyst_apig_api_key](https://catalyst-docs-development.zohostratus.in/images/help/api-gateway/catalyst_apig_api_key.webp) APIキーが表示されるポップアップウィンドウが開きます。 ![catalyst_apig_api_key_2](https://catalyst-docs-development.zohostratus.in/images/help/api-gateway/catalyst_apig_api_key_2.webp) APIキーは2つの方法で渡すことができます： * **リクエストヘッダー** リクエストURLのヘッダーとしてAPIキーを渡すことができます。以下に例を示します： ```bash curl -X POST \ https://shipmenttracking-61317105.catalystserverless.com/CustomerPortal/create \ -H "ZCFKEY: API_KEY" ``` * **クエリ文字列** リクエストURLのクエリパラメータとしてAPIキーを渡すこともできます。以下に例を示します： ```bash POST https://shipmenttracking-61317105.catalystserverless.com/CustomerPortal/ create?ZCFKEY=API_KEY ``` 両方の箇所で`API\_KEY`を実際のAPIキーに置き換えてください。 #### Catalystユーザー認証 この認証方法は、デフォルトで[Catalyst Authentication](https://docs.catalyst.zoho.com/ja/cloud-scale/help/authentication/introduction)の_Users_セクションに追加されたCatalystアプリケーションのすべてのユーザーにアクセスを許可します。Catalystアプリケーションにユーザーサインインフォームを組み込み、ログインセッションを有効にすることで、この認証方法を管理できます。[アプリユーザー](https://docs.catalyst.zoho.com/ja/cloud-scale/help/authentication/user-management/users/introduction/)は、追加のユーザー検証を行うことなく、APIのターゲットに自動的にアクセスできるようになります。 #### OAuthベース認証 この認証方法は、OAuthアクセストークンを持つユーザーにアクセスを許可します。 リクエストURLのヘッダーとしてアクセストークンを渡すことができます。以下に例を示します： ```bash curl -X POST \ https://shipmenttracking-61317105.catalystserverless.com/CustomerPortal/create \ -H "Authorization: Zoho-oauthtoken Zoho-oauthtoken 1000.910*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*16.2f*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*57"" ``` CatalystアプリケーションにOAuth認証を実装するには、[OAuth認証ヘルプドキュメント](https://docs.catalyst.zoho.com/ja/api/oauth2/overview-and-terminology/#OverviewandTerminology)を参照して詳細な手順をご確認ください。 > **注意:** API GatewayアクセスのためにOAuthプロトコルを実装する場合、この動作を認識しておく必要があります。ユーザータイプによって、以下が適用されます： * **認証済みユーザー**は、追加の設定なしに関数に直接アクセスできます。 * **あなたとコラボレーター**は、OAuthトークンの提供に加えて、関数にアクセスするために以下のリクエストヘッダーを含める必要があります： * **キー:** `ZC-OAUTH-USER` * **値:** `ADMIN` ### スロットリング スロットリングを使用すると、クライアントによる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を作成](https://docs.catalyst.zoho.com/ja/cloud-scale/help/api-gateway/implementation/#create-an-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](https://docs.catalyst.zoho.com/ja/cli/v1/project-directory-structure/client-directory/)ファイルで設定された構成に基づいて作成されます。そのファイルで`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](https://docs.catalyst.zoho.com/ja/serverless/help/security-rules/introduction)で関数の定義を設定している場合、自動作成時にAPI Gatewayに自動的に移行されます。定義を設定していない場合は、デフォルトのルールが適用されます。 * 自動作成時に関数に対して作成されるAPIには、Security Rulesで設定されたHTTPメソッドと認証が含まれます。 * **リクエストメソッドとURL:** * Security Rulesで関数に対して5つすべてのHTTPメソッド（`GET`、`PUT`、`POST`、`DELETE`、`PATCH`）が有効になっている場合、関数に対してリクエストメソッド'[ANY](https://docs.catalyst.zoho.com/ja/cloud-scale/help/api-gateway/key-concepts/#routing)'の単一のAPIが自動的に作成されます。 * Security Rulesで関数に対して5つのHTTPメソッドのうち1つ以上が無効になっている場合、他の各メソッドに対して個別のAPIが作成されます。 * 自動作成では、Security RulesでリクエストURLとターゲットURLが同一であるため、関数のリクエストURLはそのデフォルトのターゲットURLまたは[関数URL](https://docs.catalyst.zoho.com/ja/serverless/help/functions/introduction)と同じになります。 * 関数の[リクエストURLにregexパターン](https://docs.catalyst.zoho.com/ja/cloud-scale/help/api-gateway/key-concepts/#routing#)がある場合、同じパターンがターゲットURLに割り当てられます。 * **認証:** * Security Rulesで関数の認証方法が`optional`の場合、自動作成時に関数のAPIの[リクエストプロセッサ](https://docs.catalyst.zoho.com/ja/cloud-scale/help/api-gateway/key-concepts/#authentication-request-processor)は自動的に`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](https://docs.catalyst.zoho.com/ja/cloud-scale/help/web-client-hosting/implementation#host-a-web-application)と同じになります。 * **ハード制限:** 作成可能なAPIのハード制限は1000 API/プロジェクトです。 自動作成を使用して関数とWebクライアントのAPIが作成された後、個々のAPIを[編集](https://docs.catalyst.zoho.com/ja/cloud-scale/help/api-gateway/implementation/#edit-an-api)して必要に応じてデフォルト値を変更できます。 #### カスタムAPI 関数またはWebクライアントに対していつでもカスタムAPIを作成し、APIのパラメータを設定できます。要件に基づいて、リクエストメソッドとURL、ターゲット、認証方法、スロットリングなどを定義できます。カスタムAPIの作成では、Security Rulesからの関数の設定は移行されません。