すべてのプロダクト
Search
ドキュメントセンター

API Gateway:APIの作成

最終更新日:Nov 25, 2024

このトピックでは、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アプリと認証なしがサポートされています。

  • Alibaba Cloud App: 認証を受けたアプリケーションを呼び出し元が使用できるようにします。

  • No Authentication: APIのリクエスト定義に精通しているすべてのユーザーがリクエストを開始できます。 API Gatewayは、呼び出し元のIDを確認せずに、リクエストをバックエンドサービスに直接転送します。 セキュリティ認証を [認証なし] に設定しないことを推奨します。

署名アルゴリズム

APIリクエストの署名に使用されるアルゴリズム。 有効な値:

  • HMAC_SHA256

  • HMAC_SHA1およびHMAC_SHA256: パラメーターをこの値に設定すると、両方のアルゴリズムがサポートされます。

説明

APIの説明。

1.2 リクエスト情報の設定

[APIリクエストの定義] ステップで、APIに関するリクエスト情報を設定します。 詳細な設定には、プロトコル、リクエストパス、HTTPメソッド、リクエストモード、リクエストパラメータなどがあります。

項目

説明

プロトコル

APIリクエストに使用されるネットワークプロトコル。 有効な値: HTTPおよびHTTPS。

リクエストパス

サービスホストに対応するAPIリクエストパス。 リクエストパスは、実際のバックエンドサービスパスとは異なる場合があります。 有効で意味的に正確なパスをリクエストパスとして指定する必要があります。 リクエストパスで動的パラメータを設定できます。 これには、リクエストでパスパラメーターを指定する必要があります。 さらに、パスパラメータは、バックエンドサービスによって受信されるクエリおよびヘッダパラメータにマッピングすることができる。

HTTPメソッド

標準のHTTPリクエストメソッド。 有効な値: PUT、GET、POST、DELETE、PATCH、HEAD、OPTIONS、ANY。

リクエストモード

リクエストパラメーターが渡されるモード。 有効な値: リクエストパラメータマップ (未知のパラメータをフィルタアウト) 、マップ (パススルー未知のパラメータ) 、およびパススルー。

  • Map (未知のパラメータをフィルタアウト): クエリ、パス、および本文フォームパラメータのリクエストとレスポンスのマッピングを設定する必要があることを指定します。 API Gatewayは、設定されたパラメーターのみをバックエンドサービスに透過的に渡します。 他のパラメータは除去される。

  • Map (パススルー不明パラメーター): クエリ、パス、および本文フォームパラメーターのリクエストとレスポンスのマッピングを設定する必要があることを指定します。 API Gatewayは、設定されたリクエストパラメーターのみをマップおよび検証し、不明なパラメーターをバックエンドサービスに透過的に渡します。

  • パススルー: リクエストにクエリと本文のフォームパラメーターを設定する必要がないことを指定します。 ただし、パスパラメーターを設定する必要があります。 API Gatewayは、クライアントからバックエンドサービスに送信されるすべてのパラメーターを透過的に渡します。

リクエストパラメーターの設定: [リクエストパラメーター] セクションで、APIのリクエストパラメーターを特定の場所に設定します。 次の場所がサポートされています: パラメータパス、ヘッド、およびクエリ。 動的パスパラメーターを設定するときは、動的パラメーターの説明を指定する必要があります。 サポートされているデータ型は、String、Int、およびBooleanです。

  • すべてのパラメーターの名前は一意である必要があります。

  • いいえのショートカットキーを使用できます。 列を開き、パラメータの配置順序を変更します。

  • [操作] 列の [削除] をクリックすると、不要になったパラメーターを削除できます。

説明

リクエストパスで動的パラメーターを設定した場合は、動的パラメーターと同じ名前のパラメーターを定義し、パラメーターの場所をパラメーターパスに設定する必要があります。

パラメーター検証ルールの設定: 検証ルールを設定するパラメーターを見つけて、[操作] 列の [詳細設定] をクリックします。 [詳細設定] ダイアログボックスで、最大長や列挙値などの関連パラメーターを設定します。 API Gatewayは、検証ルールに基づいてリクエストを事前検証します。 パラメーターが無効なリクエストはバックエンドサービスに送信されません。 これにより、バックエンドサービスのワークロードが大幅に削減されます。

1.3 バックエンドサービスの設定

[バックエンドサービスの定義] ステップで、パラメーターのリクエストとレスポンスのマッピングを設定し、バックエンドサービスのAPI設定を指定します。 API Gatewayはリクエストを受信すると、リクエストの形式をバックエンドサービスの設定に基づいてバックエンドサービスで必要な形式に変換します。 その後、API Gatewayはリクエストをバックエンドサービスに転送します。

基本情報の設定: [バックエンドサービスの基本設定] セクションで、バックエンドサービスに関する基本情報を設定します。

項目

説明

バックエンドサービスタイプ

バックエンドサービスのタイプ。 有効な値: HTTP/HTTPSサービス、VPC、Function Compute、OSS、およびMock。

  • HTTP/HTTPS: このオプションはデフォルトで選択されています。 API GatewayがHTTPまたはHTTPS経由でバックエンドサービスにアクセスすることを示します。 API Gatewayがバックエンドサービスと直接通信できる場合は、このオプションを選択します。 バックエンドサービスとしてHTTPSサービスを使用する場合は、HTTPSサービスのSSL証明書を設定する必要があります。

  • Function Compute: Function Computeをバックエンドサービスとして使用する場合は、事前に次の操作を実行します。function Computeコンソールで関数を作成し、サービス名と関数名を指定してから、Function ComputeのロールのAlibaba Cloud Resource name (ARN) を取得します。

  • VPC: バックエンドサービスが仮想プライベートクラウド (VPC) にデプロイされている場合、このオプションを選択します。

  • OSS: OSS (Object Storage Service) がバックエンドサービスの場合、このオプションを選択します。

  • モック: HTTPまたはHTTPSバックエンドサービスの期待される結果をシミュレートする場合は、このオプションを選択します。

説明

中国以外のリージョンまたは中国 (香港) リージョンでは、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が有効かどうかを確認します。

  1. 作成したAPIを検索し、API名をクリックするか、[操作] 列の [管理] をクリックして [定義] ページに移動します。

  2. 左側のナビゲーションウィンドウで、[デバッグAPI] をクリックします。

  3. 表示されるページで、[リクエストパラメーター] セクションでリクエストパラメーターを指定し、[リクエストの送信] をクリックします。

結果がページの右側に表示されます。

成功応答が返された場合、APIは期待どおりに呼び出されます。

HTTP 4XXまたは5XXステータスコードが返された場合、APIの呼び出し時にエラーが発生しました。 詳細については、「エラーメッセージの取得方法」および「エラーコード」をご参照ください。

3. 次のステップ

APIを設定およびデバッグした後、APIは呼び出しに使用できます。 APIをテスト、ステージング、または本番環境に公開して、さらにデバッグしたり、ユーザーが呼び出すことができます。 APIにセキュリティ設定を追加することもできます。 たとえば、APIの署名を添付できます。 詳細については、「ダイジェスト認証を使用したAPIの呼び出し」をご参照ください。