API を作成するとき、API の基本情報を入力し、API リクエスト情報、API バックエンドサービス、レスポンス情報を定義する必要があります。次に、API をデバッグし、セキュリティを設定します。API をテストした後、正常に動作する場合は、ユーザーの本番環境に公開できます。
API の定義
API Gateway コンソール の [API リスト] ページで、[API の作成] をクリックして API の作成と定義に進みます。
API の基本情報
API の基本情報には、API グループ、API 名、セキュリティ認証方式、公開/非公開のタイプ、および説明が含まれます。
- グループ:API はグループ単位で管理されます。API を作成する前に、まずグループを作成する必要があります (API グループの詳細は、「API の公開」をご参照ください)。
- API 名:API の名前です。グループ内の一意の識別子でもあります。
セキュリティ認証:API リクエストの認証方法です。利用可能な方法は、[Alibaba Cloud アプリ]、[OpenID Connect]、[OpenID Connect および Alibaba Cloud アプリ]、[証明書なし] の 4 つです。
- Alibaba Cloud アプリ:リクエスターがこの API を呼び出すとき、このアプリの ID 認証を通過する必要があります。
- OpenID Connect:OAuth 2.0 に基づく軽量標準。RESTful API を介した ID 相互作用のフレームワークを提供します。OpenID Connect を使用して、独自のアカウントシステムにシームレスに接続できます。詳細は、「OpenID Connect 認証」をご参照ください。
- OpenID Connect および Alibaba Cloud アプリ:OpenID Connect と Alibaba Cloud アプリ認証。
- 証明書なし:この API のリクエスト定義を知っているユーザーは、 リクエストを開始できます。API Gateway は ID を検証せず、リクエストをバックエンドサービスに直接転送します (この方法を使用しないことを強く推奨します)。
公開/非公開:[公開] または [非公開]。
- 公開 API:すべてのユーザーは、API Gateway コンソールの [公開された API] ページで API の情報セクションを確認できます。
- 非公開 API:ユーザーが非公開 API を呼び出す場合、そのユーザーに手動で許可を付与する必要があります。
- 説明:API の機能の説明。
API リクエストの定義
ここでは、関連するプロトコル、リクエストパス、HTTP メソッド、リクエストモード、入力パラメーター定義など、ユーザーが API にリクエストを送信する方法を定義します。
- プロトコル:[HTTP] と [HTTPS] をサポートします。
- リクエストパス:対応するサービスホストの API リクエストパス。リクエストパスは、実際のバックエンドサービスパスとは異なる場合があります。有効、かつユーザーにとって意味の分かりやすいパスを記述できます。リクエストパスに動的パラメーターを設定できます。ユーザーは、Path フィールドにパラメーターを入力する必要があります。同時に、バックエンドサービスは Path からパラメーターを受け取ります。このパラメーターは Query、Header など、他の位置にマップされます。「API Gateway への API の公開」には、詳細な例と操作のスクリーンショットがあります。
- HTTP メソッド:標準の HTTP メソッドをサポートします。PUT、GET、POST、DELETE、PATCH、HEAD を選択できます。
- リクエストモード:入力パラメーターの処理モード。[リクエストパラメーターをマッピング] または [リクエストパラメーターをパススルー] があります。
- リクエストパラメータをマッピング:API Gateway が API のリクエストを受信したとき、マッピング関係を使用して、バックエンドサービスで必要とされる形式にリクエストを変換します。[リクエストパラメータをマッピング] モードの機能:
- 定義方法:この API を定義するとき、フロントエンドとバックエンドのパラメーターマッピング関係を追加する必要があります。
- シナリオ:
- 同じインターフェイスの場合、API Gateway に異なる API を定義して、区別されたサービスをユーザーに提供します。
- API Gateway を使用して、レガシーシステムのインターフェイスを標準化します。
- 機能:
- フロントエンドからバックエンドへの完全なマッピング、つまりパラメーターシャッフルを設定できます。たとえば、API ユーザーに対して Query フィールドへのパラメーターの入力をリクエストし、バックエンドはその情報を Header フィールドで受信するように設定することができます。パラメーター名の変換とパラメーター位置の変換をサポートします。
- パラメーター検証ルールを定義して、 リクエストパラメーターを事前に検証し、バックエンドで処理される無効なパラメーターの量を減らすことができます。長さの検証、パラメーター値の検証、パラメーターの正規表現の検証、パラメーターの JSON スキーマの検証をサポートします。
- リクエストパラメータをパススルー:API Gateway が API リクエストを受信した後 、リクエストを処理せず、直接バックエンドサービスに転送します。このモードでは、
- パラメーターの検証を実装できません。
- 詳細な API 呼び出しドキュメントを生成できません。
- 自動生成された SDK には、リクエスト入力パラメーターは含まれません。
- リクエストパラメータをマッピング:API Gateway が API のリクエストを受信したとき、マッピング関係を使用して、バックエンドサービスで必要とされる形式にリクエストを変換します。[リクエストパラメータをマッピング] モードの機能:
- 入力パラメーター定義:このセクションでは、パラメーター名、パラメーター位置、タイプ、必須かどうか、デフォルト値、例、説明などの API リクエスト入力パラメーターを定義できます。[リクエストパラメーターをパススルー] モードでは、パラメーターを入力する必要はありません。
- パラメーター名:ユーザーに表示されるパラメーター名。
- パラメーター位置:Head、Query、Parameter Path を含む、リクエストに記載されているパラメーターの位置。
注:Path に動的パラメーターを設定した場合、パラメーターの位置は Parameter Path としても定義されます。
- タイプ:フィールドタイプ。オプションの値: String、Int、Long、Float、Double、Boolean。
- 必須:必須パラメーターかどうかを示します。[はい] に設定すると、このパラメーターがユーザーリクエストに含まれているかどうかが検証されます。このパラメーターのないリクエストは、拒否されます。
- デフォルト値:このオプションは、[必須] が [いいえ] に設定されている場合に適用されます。対応するパラメーターがユーザーリクエストに含まれていない場合、リクエストがバックエンドサービスに転送される前に自動的にデフォルト値が追加されます。
- 例:パラメーターの定義例。
- 説明:パラメーターの簡単な説明と、使用時に考慮すべき点を記述します。
- パラメーター検証ルール:[詳細] をクリックして、文字列の長さ、最小値と最大値、列挙、正規表現、JSON スキーマ、その他の属性など、パラメーター値の検証ルールを設定します。API Gateway は検証ルールを使用して、リクエストの事前チェックを行います。入力パラメーターが無効の場合、 リクエストはバックエンドサービスに送信されません。これは、バックエンド処理の負荷を軽減するためです。
APIバックエンドサービスの定義
ここでは、主にフロントエンドとバックエンド間のパラメーターマッピングを定義します。これは、バックエンドサービスアドレス、バックエンドパス、バックエンドタイムアウト、パラメーターマッピング、定数パラメーター、システムパラメーターなどの API バックエンドサービス設定です。ユーザーリクエストが API Gateway に到達すると、リクエストがバックエンドサービスに転送される前に、バックエンド設定に従って、受信したリクエストをバックエンドサービスで必要とされる形式にマッピングします。
- バックエンドサービスタイプ:HTTP/HTTPS と Function Compute をサポートしています。
- HTTP/HTTPS:サービスが HTTP/HTTPS サービスの場合、このオプションを選択します。
注:HTTPS サービスを使用している場合、バックエンドサービスには SSL 証明書が必要です。
- Function Compute:バックエンドサービスに Function Compute を選択した場合、まず Function Compute コンソールで関数を作成し、その関数のサービス名と関数名を入力し、Function Compute のロール Arn を取得します。
- HTTP/HTTPS:サービスが HTTP/HTTPS サービスの場合、このオプションを選択します。
- バックエンド VPC アクセス:バックエンドサービスが VPC ネットワークにある場合、[有効] を選択する必要があります。使用方法は、「VPC環境での API の公開」をご参照ください。
- バックエンドサービスアドレス:バックエンドサービスのホスト。これはドメイン名で、’http(s)://host:port’ の形式でもかまいません。この値は “http://“ または “https://“ で始まる必要があります。
- バックエンドリクエストパス:このパスは、バックエンドサーバー上の API サービスの実際のリクエストパスです。バックエンドパスが動的パラメーターを受け取る場合、呼び出し元が入力する必要のあるパラメーターの位置と名前を指定します。これは、対応するマッピング関係を宣言します。
- バックエンドタイムアウト:API Gateway が、呼び出した API のバックエンドサービスからレスポンスを受け取る必要がある最大時間です。この期間は、API Gateway がバックエンドサービスにリクエストを送信したときに開始し、バックエンドサービスからレスポンス結果を受け取ったときに終了します。単位:ミリ秒。この値は 30 秒を超えることはできません。レスポンス時間がこの値を超えると、 API Gateway はリクエストを中断し 、対応するエラーメッセージをユーザーに返します。
- 定数パラメーター:定数パラメーターを設定できます。これらのパラメーターは、ユーザーには見えません。ただし、リクエストが API Gateway を通過するとき、リクエストがバックエンドサービスに転送される前に、リクエスト内の指定された位置にこれらのパラメーターが追加されます。これは、バックエンドサービスの特定のビジネスニーズに対処するために使用されます。たとえば、API Gateway からバックエンドサービスに送信されるリクエストが、毎回 aligateway キーワードを含む必要がある場合、aligateway を定数パラメーターとして設定し、受信する位置を指定できます。
システムパラメーター:API Gateway のシステムパラメーターです。デフォルトでは、システムパラメーターはユーザーに送信されません。ただし、システムパラメーターを取得するには、API で位置と名前を設定します。次の表にそれぞれの内容を示します。
パラメーター 説明 CaClientIp リクエスト送信元クライアントの IP アドレス CaDomain リクエスト送信元ドメイン名 CaRequestHandleTime リクエスト時間 (GMT) CaAppId リクエストアプリケーションの ID CaRequestId RequestId CaApiName API 名 CaHttpSchema ユーザーが API の呼び出しに使用するプロトコル:HTTP または HTTPS。 CaProxy プロキシ (AliCloudApiGateway) 注:Path パラメーター、Headers パラメーター、Query パラメーター、Body パラメーター (非バイナリ)、定数パラメーター、システムパラメーターなど、すべてのパラメーターの名前はグローバルに一意でなければなりません。Headers フィールドと Query フィールドに name というパラメーターを同時に指定した場合、エラーが報告されます。
パート 4:レスポンスの定義
返される ContentType、レスポンス例、エラーレスポンス例、およびエラーコード定義を入力します。
API のデバッグ
API を正しく定義したら、API のデバッグページでデバッグし、正確性と有用性を検証できます。
API を作成し、定義した後、作成された API が使用可能で、リクエストチェーンが正しいかどうかをテストできます。
- API 名または [管理] ボタンをクリックして、[API 定義] ページに移動します。
- 左側のナビゲーションペインで [API のデバッグ] をクリックします。
- リクエストパラメーターを入力し、[リクエスト送信] をクリックします。ページの右側に、返された結果が表示されます。正しい結果が返された場合、API を使用できることを示します。4XX または 5XX エラーコードが返された場合、リクエストエラーが発生したことを示します。詳細は、「エラーメッセージの取得方法」と「エラーコード一覧」をご参照ください。
次のステップ
API 定義と事前デバッグが終了したら、API の作成は完了です。デバッグを続行するため、または他のユーザーが使用するために、[テスト]、[ステージング]、[本番] 環境で API を公開できます。署名鍵を API にバインドし、スロットリングやその他のセキュリティ設定を行うこともできます。