このトピックでは、APIを作成およびデバッグし、APIにセキュリティ設定を追加する方法について説明します。 APIを作成するには、APIの基本情報、リクエスト情報、バックエンドサービス、およびレスポンス情報を設定する必要があります。 APIがデバッグテストに合格した後、ユーザーが呼び出すAPIを公開できます。
1. APIの設定
API Gatewayコンソールにログインします。 左側のナビゲーションウィンドウで、[APIの管理]> [API] を選択します。 APIページで、[Create API] をクリックしてAPIを作成および設定します。
1.1 基本情報の設定
項目 | 説明 |
APIグループ | APIの基本的な管理単位。 APIを作成する前に、APIグループを作成する必要があります。 グループを選択すると、APIのリージョンが選択されます。 |
API名 | 作成するAPIの名前。 APIグループ内の各API名は一意である必要があります。 |
セキュリティ認証 | 現在、Alibaba Cloudアプリと認証なしがサポートされています。
|
署名アルゴリズム | APIリクエストの署名に使用されるアルゴリズム。 有効な値:
|
説明 | APIの説明。 |
1.2 リクエスト情報の設定
[APIリクエストの定義] ステップで、APIに関するリクエスト情報を設定します。 詳細な設定には、プロトコル、リクエストパス、HTTPメソッド、リクエストモード、リクエストパラメータなどがあります。
項目 | 説明 |
プロトコル | APIリクエストに使用されるネットワークプロトコル。 有効な値: HTTPおよびHTTPS。 |
リクエストパス | サービスホストに対応するAPIリクエストパス。 リクエストパスは、実際のバックエンドサービスパスとは異なる場合があります。 有効で意味的に正確なパスをリクエストパスとして指定する必要があります。 リクエストパスで動的パラメータを設定できます。 これには、リクエストでパスパラメーターを指定する必要があります。 さらに、パスパラメータは、バックエンドサービスによって受信されるクエリおよびヘッダパラメータにマッピングすることができる。 |
HTTPメソッド | 標準のHTTPリクエストメソッド。 有効な値: PUT、GET、POST、DELETE、PATCH、HEAD、OPTIONS、ANY。 |
リクエストモード | リクエストパラメーターが渡されるモード。 有効な値: リクエストパラメータマップ (未知のパラメータをフィルタアウト) 、マップ (パススルー未知のパラメータ) 、およびパススルー。
|
リクエストパラメーターの設定: [リクエストパラメーター] セクションで、APIのリクエストパラメーターを特定の場所に設定します。 次の場所がサポートされています: パラメータパス、ヘッド、およびクエリ。 動的パスパラメーターを設定するときは、動的パラメーターの説明を指定する必要があります。 サポートされているデータ型は、String、Int、およびBooleanです。
すべてのパラメーターの名前は一意である必要があります。
いいえのショートカットキーを使用できます。 列を開き、パラメータの配置順序を変更します。
[操作] 列の [削除] をクリックすると、不要になったパラメーターを削除できます。
リクエストパスで動的パラメーターを設定した場合は、動的パラメーターと同じ名前のパラメーターを定義し、パラメーターの場所をパラメーターパスに設定する必要があります。
パラメーター検証ルールの設定: 検証ルールを設定するパラメーターを見つけて、[操作] 列の [詳細設定] をクリックします。 [詳細設定] ダイアログボックスで、最大長や列挙値などの関連パラメーターを設定します。 API Gatewayは、検証ルールに基づいてリクエストを事前検証します。 パラメーターが無効なリクエストはバックエンドサービスに送信されません。 これにより、バックエンドサービスのワークロードが大幅に削減されます。
1.3 バックエンドサービスの設定
[バックエンドサービスの定義] ステップで、パラメーターのリクエストとレスポンスのマッピングを設定し、バックエンドサービスのAPI設定を指定します。 API Gatewayはリクエストを受信すると、リクエストの形式をバックエンドサービスの設定に基づいてバックエンドサービスで必要な形式に変換します。 その後、API Gatewayはリクエストをバックエンドサービスに転送します。
基本情報の設定: [バックエンドサービスの基本設定] セクションで、バックエンドサービスに関する基本情報を設定します。
項目 | 説明 |
バックエンドサービスタイプ | バックエンドサービスのタイプ。 有効な値: HTTP/HTTPSサービス、VPC、Function Compute、OSS、およびMock。
説明 中国以外のリージョンまたは中国 (香港) リージョンでは、HTTPまたはOSSタイプのバックエンドサービスを作成できません。 |
VPCアクセス名: | バックエンドサービスがVPCにデプロイされている場合は、VPCアクセス許可名を指定します。 |
バックエンドサービスのURL | バックエンドサービスのホストURL。 この値には、ドメイン名またはhttp:// host:portまたはhttps:// host:port形式の値を指定できます。 値はhttp:// またはhttps:// で始める必要があります。 |
バックエンドリクエストパス | バックエンドサーバー上のAPIの実際のリクエストパス。 バックエンドサービスパスで動的パラメーターを受け取る場合は、関連するリクエストパラメーターの場所と名前を指定してパラメーターマッピングを宣言する必要があります。 |
HTTPメソッド | 標準のHTTPリクエストメソッド。 有効な値: PUT、GET、POST、DELETE、PATCH、HEAD、OPTIONS、ANY。 |
バックエンドサービスのタイムアウト期間 | API Gatewayが受信したAPIリクエストをバックエンドサービスに送信し、バックエンドサービスから応答を受信するまでの時間。 応答時間は、API GatewayがバックエンドサービスにAPIリクエストを送信した時点から始まり、API Gatewayがバックエンドサービスから応答を受信した時点で終了します。 応答時間は30秒を超えることはできません。 API Gatewayが30秒以内にバックエンドサービスから応答を受信しない場合、API Gatewayはバックエンドサービスへのアクセスを停止し、エラーメッセージを返します。 |
バックエンドサービスパラメーターの設定: [バックエンドサービスパラメーター] セクションで、パラメーターのリクエストとレスポンスのマッピングを設定します。 名前マッピングと位置マッピングがサポートされています。 API Gatewayは、パス、ヘッダー、クエリ、または本文のリクエストパラメーターを別の場所のレスポンスパラメーターにマッピングできます。 これにより、バックエンドサービスを標準化されたプロフェッショナルなAPIフォームにパッケージ化できます。 この部分は、要求パラメータと応答パラメータの間のマッピングを宣言します。
定数パラメーターの設定: [定数パラメーター] セクションで、定数パラメーターを設定します。 定数パラメーターはユーザーには表示されません。 API Gatewayがリクエストを受信すると、リクエスト内の指定された場所に定数パラメーターを追加し、バックエンドサービスのビジネスニーズに合わせてリクエストをバックエンドサービスに転送します。 API Gatewayがバックエンドサービスに転送する各リクエストにabcパラメーターをアタッチする場合は、abcパラメーターを定数パラメーターとして設定できます。 API Gatewayがリクエストを受信すると、API Gatewayはabcパラメーターを指定された場所に追加し、リクエストをバックエンドサービスに転送します。
システムパラメーターの設定: [システムパラメーター] セクションで、API Gatewayでサポートされているシステムパラメーターを設定します。 デフォルトでは、API GatewayはAPIリクエストにシステムパラメーターを追加しません。 システムパラメータを取得する場合は、それらの場所と名前を設定できます。 次の表に、システムパラメーターを示します。
項目 | 説明 |
CaClientIp | APIリクエストを送信するクライアントのIPアドレス。 Web Application Firewall (WAF) またはContent Delivery Network (CDN) を設定した場合、システムはback-to-origin IPアドレスを記録します。 X-Forwarded-Forには、クライアントの実IPアドレスが記録されます。 |
CaDomain | APIリクエストの送信に使用されるドメイン名。 |
CaRequestHandleTime | UTCでのリクエスト時間。 |
CaRequestId | RequestId |
CaApiName | API 名。 |
CaHttpSchema | APIの呼び出しに使用されるプロトコル。 有効な値: HTTPおよびHTTPS。 |
CaProxy | APIリクエストを処理するために使用されるプロキシ。 値をAliCloudApiGatewayに設定します。 |
CaClientUa | APIリクエストを送信するクライアントのユーザーエージェント。 |
CaCloudMarketInstanceId | 初めて購入されたAlibaba Cloud Marketplace商品に対応するインスタンスのID。 |
CaAppId | APIの呼び出しに使用されるアプリケーションのID。 |
CaAppKey | APIの呼び出しに使用されるアプリケーションのキー。 |
CaAppExtendInfo | アプリケーションの拡張機能。 |
CaStage | APIを呼び出す環境。 有効な値: RELEASE、TEST、およびPRE。 |
CaInstanceId | APIが属するインスタンスのID。 |
CaSourceVpcId | クライアントのIPアドレスが属するVPC。 |
APIグループの詳細ページの [リクエストヘッダーのパススルー設定] セクションで、[ホストヘッダーのパス] を選択します。 [ホストヘッダーを渡す] を選択すると、API Gatewayはリクエスト内のホストヘッダーパラメーターをバックエンドサービスに渡します。 [ホストヘッダーを渡す] を選択しない場合、API Gatewayは指定したホストヘッダーをバックエンドサービスに送信します。 次のコードは例を示しています。
たとえば、APIグループにe xuemeng.XXXX.comホスト名を付与すると、APIグループ内のAPIのバックエンドサービスのホスト名がs apigatewayXXXXXXalicloudapi.com:8080します。 次のコードスニペットは、Pass host Headerを有効にする前と後にバックエンドサービスが受け取るさまざまなホスト名を示しています。
Pass Host Headerが有効になっている場合、次のホスト名が受信されます。
Host: xuemeng.XXXX.com
Pass Host Headerが無効になっている場合、次のホスト名が受信されます。
Host: apigatewayXXXXXXalicloudapi.com:8080
APIのバックエンドサービスのパラメーターを設定するときは、各パラメーターの名前がAPI Gatewayでグローバルに一意であることを確認してください。 これは、動的パスパラメータ、ヘッダパラメータ、クエリパラメータ、非バイナリ本体パラメータ、定数パラメータ、およびシステムパラメータに適用されます。 たとえば、ヘッダーパラメーターとクエリパラメーターの名前としてnameを指定すると、エラーが発生します。
1.4 レスポンス情報の設定
[応答の定義] ステップで、応答ContentType、応答例、エラー応答例、およびエラーコードを設定します。
2. APIのデバッグDebug the API
APIを作成および設定した後、APIデバッグページでAPIをデバッグして、APIが期待どおりに機能することを確認できます。
APIの作成および設定後、APIページにリダイレクトされます。 このページでは、次の操作を実行して、APIを呼び出すことができるかどうか、およびリクエストURLが有効かどうかを確認します。
作成したAPIを検索し、API名をクリックするか、[操作] 列の [管理] をクリックして [定義] ページに移動します。
左側のナビゲーションウィンドウで、[デバッグAPI] をクリックします。
表示されるページで、[リクエストパラメーター] セクションでリクエストパラメーターを指定し、[リクエストの送信] をクリックします。
結果がページの右側に表示されます。
成功応答が返された場合、APIは期待どおりに呼び出されます。
HTTP 4XXまたは5XXステータスコードが返された場合、APIの呼び出し時にエラーが発生しました。 詳細については、「エラーメッセージの取得方法」および「エラーコード」をご参照ください。
3. 次のステップ
APIを設定およびデバッグした後、APIは呼び出しに使用できます。 APIをテスト、ステージング、または本番環境に公開して、さらにデバッグしたり、ユーザーが呼び出すことができます。 APIにセキュリティ設定を追加することもできます。 たとえば、APIの署名を添付できます。 詳細については、「ダイジェスト認証を使用したAPIの呼び出し」をご参照ください。