API GatewayサービスはAPI GatewayでサービスするAPIを管理する単位です。 API Gatewayサービスごとに1つのAPIリソースと複数のステージを管理でき、ダッシュボードからAPI指標を確認できます。
API Gatewayサービス情報を入力した後、作成ボタンを押すとAPI Gatewayサービスが作成されます。
[参考] API Gatewayサービス作成数制限
API Gatewayサービスはプロジェクトごとに最大10個まで作成できます。
[注意] API Gatewayサービスを削除できない場合
API Gatewayサービスのステージと接続された使用量計画が存在する場合はAPI Gatewayサービスを削除できません。
リソースはAPI Gatewayを通してサービスするAPIを設計する画面です。 すべてのAPIリクエストクライアントはAPI Gatewayリソースに定義されたAPIに対してリクエストできます。 リソースはAPIのリソースパスとメソッドを管理します。
Swagger v2.0 OpenAPI Specification形式のファイルでリソースでインポートできます。 1. リソースインポートボタンをクリックします。 2. Swaggerファイル選択ボタンをクリックしてファイルを選択するか、Swaggerの内容を直接入力します。 3. 適用ボタンをクリックします。
[注意]リソースのインポートを行うと、既存リソースとモデルを上書き
リソースをインポートすると、既存のリソースは削除され、インポートしたリソースで上書きされます。 リソースをインポートすると、該当サービスに作成されていた既存のモデルは全て削除され、インポートしたモデルで上書きします。[参考] 2021-11-23以前ステージエクスポート(Export)ファイルのインポート失敗
2021-11-23以前にステージのエクスポートを行ってダウンロードしたファイルでリソースのインポートを行うと、失敗する可能性があります。 ステージエクスポートを行って新しく作成されたファイルを利用してリソースのインポートを行うか、次の操作で既存ファイルを変更してください。 変更作業 1. ファイル内x-api-nhn-apigateway > pluginsのプラグイン設定文字列をJSONオブジェクトに変換する必要があります。 2. ファイル内リソースメソッド > x-api-nhn-apigateway > pluginsにCORSプラグイン設定文字列が存在する場合は削除する必要があります。リソースメソッドにはCORSプラグインを設定することができず、その上位のリソースパスにCORSプラグインが設定されている場合、リソースのインポート時に自動的に追加されます。 ガイドの内容で解決しない場合はサポートへお問い合わせください。
- [例1]インポート失敗：2021-11-23以前のステージエクスポートファイルは、pluginsのプラグイン設定値がJSON形式の文字列で構成されています
{
...
"x-nhncloud-apigateway": {
"plugins": {
"HTTP": "{\"frontendEndpointPath\":\"/{proxy+}\",\"backendEndpointPath\":\"/anything/${request.path.proxy+}\"}",
}
}
...
}
- [例1]インポート成功：pluginsのプラグイン設定値でJSON形式の文字列をJSONオブジェクトに修正したステージエクスポートファイル
{
...
"x-nhncloud-apigateway": {
"plugins": {
"HTTP": {
"frontendEndpointPath": "/{proxy+}",
"backendEndpointPath": "/anything/${request.path.proxy+}"
}
}
}
...
}
- [例2]インポート失敗：2021-11-23以前のステージエクスポートファイルは、リソースパスにCORSプラグインが設定されている場合、サブリソースメソッドにCORSプラグイン設定値が含まれています
{
...
"paths": {
"/anything": {
"get": {
...
"x-nhncloud-apigateway": {
"plugins": {
"MOCK": {
"statusCode": 200
},
"CORS": {
"allowedMethods": ["GET", "POST", "DELETE", "PUT", "OPTIONS", "HEAD", "PATCH"],
"allowedHeaders": ["*"],
"allowedOrigins": ["*"],
"exposedHeaders": [],
"maxCredentialsAge": null,
"allowCredentials": false
}
}
}
},
"options": {
"summary": "CORS",
...
},
"x-nhncloud-apigateway": {
"plugins": {
"CORS": {
"allowedMethods": ["GET", "POST", "DELETE", "PUT", "OPTIONS", "HEAD", "PATCH"],
"allowedHeaders": ["*"],
"allowedOrigins": ["*"],
"exposedHeaders": [],
"maxCredentialsAge": null,
"allowCredentials": false
}
}
}
}
}
...
}
- [例2]インポート成功：リソースメソッドにCORSプラグイン設定値を削除したステージエクスポートファイル
{
...
"paths": {
"/anything": {
"get": {
...
},
"options": {
"summary": "CORS",
...
},
"x-nhncloud-apigateway": {
"plugins": {
"CORS": {
"allowedMethods": ["GET", "POST", "DELETE", "PUT", "OPTIONS", "HEAD", "PATCH"],
"allowedHeaders": ["*"],
"allowedOrigins": ["*"],
"exposedHeaders": [],
"maxCredentialsAge": null,
"allowCredentials": false
}
}
}
}
}
...
}
バックエンドエンドポイントタイプ：ユーザー定義レスポンス
プラグイン：選択されたパスに追加されたプラグインを作成されたメソッドにも追加するにはチェックします。
[参考]リソースメソッド作成制限数
メソッドはすべてのリソースパスを含めて最大100個まで作成可能です。
[参考] CORSプラグインにより登録されたOPTIONSメソッドの修正
CORSプラグインにより登録されたOPTIONSメソッドは修正できません。
[注意]リソースパス削除
リソースパスを削除すると、選択されたリソースのパスの下位リソースパスとメソッドが全て削除されます。[参考] CORSプラグインにより登録されたOPTIONSメソッドの削除
CORSプラグインにより登録されたOPTIONSメソッドは削除できません。
リソースを変更した後、変更されたリソースをステージに適用するにはステージリソース適用を行う必要があります。
[注意]ステージリソース適用
- ステージリソースを適用するには1つ以上のステージが存在する必要があります。 - ステージにリソースが適用された後は元に戻せません。 - すでにステージに最新リソースが適用されている場合、ステージリソースの適用ができません。
プラグインを通してAPI Gatewayで提供する付加機能を追加できます。
[注意]プラグイン追加後、変更事項を保存
プラグインを追加した後、変更事項保存ボタンを押すと設定が保存されます。
リソースメソッド別リクエストパラメータとレスポンス形式、コンテンツタイプの設定を行います。 設定した内容はAPI説明書に適用されます。
HTTPレスポンスステータスコード別ヘッダとリクエスト本文項目とコンテンツタイプを設定します。 設定した内容はAPI説明書に適用されます。
リソースのメソッド作成およびプラグイン設定時に、以下に定義された変数を使用できます。
| コンテキスト変数 | 説明 |
|---|---|
| ${request.clientIp} | リクエストクライアントのIP |
| ${request.path.variable-name} | リソースで宣言した単一パス変数{variable-name}値 |
| ${request.path.variable-name+} | リソースで宣言したサブパスを含むパス変数{variable-name+}値 |
| ${request.host} | リクエストHostヘッダ(例：kr1-example.api.nhncloudservice.com) |
| ${request.uri} | リクエストURI(例：https://kr1-example.api.nhncloudservice.com/users/userId1) |
| ${request.uriPath} | リクエストパス(例：/users/userId1) |
| ${request.uriPattern} | リクエストがマッピングされたURIパターン(例：/users/{userId}) |
| ${request.scheme} | リクエストスキーム(http/https) |
| ${request.httpMethod} | リクエストHTTPメソッド(GET, POST ...) |
| ${request.timestamp} | リクエスト時間(Timestamp) |
| ${request.queryString.QUERY_STRING_NAME} | リクエストクエリパラメータ |
| ${request.header.HEADER_NAME} | リクエストヘッダ |
| ${response.httpStatus} | レスポンスHTTPステータスコード |
| ${error.resultCode} | エラーコード |
| ${error.resultMessage} | エラーメッセージ |
[注意]パス変数
選択されたパスと上位パスに宣言されたパス変数のみ使用できます。[参考]コンテキスト変数の使用
${CONTEXT_VARIABLE}または$!{CONTEXT_VARIABLE}形式で使用可能で、CONTEXT_VARIABLEには定義されたコンテキスト変数のみ使用できます。 ${CONTEXT_VARIABLE}で使用すると、コンテキスト変数の値がない場合、${CONTEXT_VARIABLE}文字列が置換されません。 $!{CONTEXT_VARIABLE}のように$!で使用すると、コンテキスト変数の値がない場合、空の文字列に置き換えられます。[参考] queryString, headerの複数の値を持つ場合にバックエンドエンドポイントへの伝達
同じ名前を持つクエリパラメータとヘッダに対して複数の値が存在する場合、コンマ(,)で値として統合されます。 例: /users?id=user1&id=user2 → /users/id=user1,user2
Cross-Site方式内でXMLHttpRequest APIを呼び出せるようにします。
[注意] CORSプラグイン
- CORSプラグインを登録すると、選択されたパスのメソッドにOPTIONSメソッドが登録されます。 下位パスとメソッドに上書きオプションをチェックした場合は下位パスにも登録されます。 OPTIONSメソッドがすでに登録されている場合、 CORSにより自動作成されるOPTIONSメソッドに変更されます。 - CORSプラグインを通して登録されたOPTIONSメソッドはリソースツリーから選択できず、修正と削除ができません。 - CORSプラグインを削除するとCORSプラグインにより自動作成されたOPTIONSメソッドは一括で削除されます。
リクエストヘッダを追加または変更します。
[参考]リクエストヘッダ追加と変更
- 原本リクエストにないヘッダは追加されます。 - 原本リクエストにあるヘッダはリクエストヘッダ変更プラグインに設定されたヘッダ値に変更されます。 - 原本リクエストにあるヘッダの削除はできません。
クライアントリクエストのヘッダから指定されたヘッダを削除した後、バックエンドにリクエストします。
[参考]リクエストヘッダ変更と削除設定
リクエストヘッダ変更とリクエストヘッダ削除プラグインを同時に設定した場合、リクエストヘッダ変更適用後、リクエストヘッダ削除が適用されます。
レスポンスヘッダ変更プラグインはバックエンドレスポンスにヘッダを追加または変更します。
[参考]レスポンスヘッダ追加と変更
- バックエンドエンドポイントのレスポンスにないヘッダは追加されます。 - バックエンドエンドポイントのレスポンスにあるヘッダはリクエストヘッダ変更プラグインに設定されたヘッダ値に変更されます。
バックエンドの応答ヘッダで指定されたヘッダを削除した後、クライアントにレスポンスします。
[参考]レスポンスヘッダの変更と削除設定
レスポンスヘッダ変更とレスポンスヘッダ削除プラグインを同時に設定した場合、レスポンスヘッダ変更適用後、レスポンスヘッダ削除が適用されます。
バックエンドエンドポイントリクエストにクエリ文字列パラメータを追加します。
例：パラメータ名と値をname、valueに設定すると、name=valueクエリ文字列パラメータがバックエンドエンドポイントをリクエストする時に追加されます。
[参考]リクエストクエリ文字列パラメータ
- 「原本リクエストのクエリ文字列パラメータ」のようなキーを持つ「リクエストクエリ文字列パラメータ」は、「原本リクエストのクエリ文字列」を代替せずに追加されます。 - クエリ文字列パラメータの値はエンコードされてバックエンドエンドポイントに伝達されます。
ステージはリソースを配布する段階です。
[参考]ステージ
- ステージを作成するにはリソースメソッドが1つ以上登録されている必要があります。 - ステージはAPI Gatewayサービスごとに最大10個まで作成できます。 - API Gatewayに受信したリクエストをバックエンドエンドポイントへ伝達する時、基本的にステージに定義されたバックエンドエンドポイントURLにリクエストを伝達します。
[注意]ステージ配布
修正されたバックエンドエンドポイントURLをAPI Gatewayサービスに適用するにはステージを配布する必要があります。
[注意]ステージ削除
- サービスで使用中のステージを削除すると、API Gatewayにリクエストが入らなくなります。 - 削除されたステージは復旧できないため、必ずサービスで使用中ではないか確認してから削除を行ってください。 - ステージに接続された使用量計画が存在する場合はステージを削除できません。
リソースを変更した後、変更されたリソースをステージに適用するには、ステージ管理画面でリソースのインポートを進行します。
[注意]リソースのインポート
- ステージにリソースが適用された後は元に戻せません。 - リソースに変更された事項がない場合は、リソースのインポートボタンが無効になります。
ステージに設定されたリソースと設定をAPI Gatewayサービスに適用するには、ステージを配布する必要があります。
ステージ配布後、配布された履歴を確認できます。以前の配布設定でステージを復元できます。
[注意]以前の配布履歴でステージを復元する
- ステージの復元を行う時、これをAPI Gatewayサービスに適用するには、ステージを配布する必要があります。
ステージ配布を行って配布された形状をAPI説明書で確認できます。 詳細はAPI説明書を参照してください。
IP ACLを使って、指定したクライアントIPに対してAPI Gatewayリクエストを許可/拒否できます。
[参考] IP ACL登録数制限およびクライアントIPチェック
- IP ACLのIPアクセス対象は最大100個まで入力できます。 - ネットワークアドレス変換(NAT：Network Address Translation)によりクライアントのSource IPが変更された場合、変更されたIPを基準にIP ACLをチェックするため、注意してください。
HMAC認証を使用すると、API Gatewayに受信したリクエストが途中で攻撃者により改ざんされることを防止し、リクエスト有効時間を設定してReply Attack攻撃を予防します。
[参考] HMAC認証失敗レスポンス
HMAC認証失敗時、401 Unauthorizedレスポンスが返されます。[注意]リクエスト有効時間
- 0秒に設定すると、リクエスト有効時間をチェックしません。この場合はReply Attack攻撃に弱くなります。 - 有効時間をあまりにも短く設定すると、APIGatewayがリクエストを検証する前に有効期限が切れてリクエストが拒否されることがあります。期待するリクエスト有効時間より10秒以上長く設定することを推奨します。 - APIクライアントは時間同期化設定NTP (Network Time Protocol, NTP)が有効かを必ず検証してください。同期化されていない時間情報によりリクエストが拒否されることがあります。[参考]必須検証ヘッダ
必須検証ヘッダを設定した場合、APIリクエスト検証時に必須検証ヘッダがリクエストに含まれているか、signatureにも該当ヘッダが含まれる値かを検証します。 設定時、必須検証ヘッダがリクエストとsingature作成時に含まれていたかを確認してください。
HMAC認証を行うにはAPIリクエストクライアントは次の認証ヘッダとリクエスト時間ヘッダを含めてリクエストする必要があります。
| ヘッダ名 | ヘッダ値 |
|---|---|
| Authorization | hmac algorithm="<encrypt_algorithm>", headers="<validation_headers>", signature="<base64_digest>" |
| x-nhn-date | ISO8601形式の時間 |
[参考] x-nhn-dateのISO8601形式
- UTC表記：yyyy-MM-dd'T'HH:mm:ssZ - UTC基準タイムオフセット表記：yyyy-MM-dd'T'HH:mm:ss±hh:mm
Authorizationまたはx-nhn-dateヘッダがリクエストに含まれていない場合、HMAC認証に失敗します。
Authorizationヘッダ値は次のように作成します。
| Credential名前 | 値 |
|---|---|
| algorithm | HmacSHA256またはHmacSHA1 |
| headers | HMAC認証時に検証するヘッダリスト コンソールでHMAC必須検証ヘッダに登録したヘッダは必ず含める必要があります。 |
| signature | SiginToString文字列を暗号化した後、Base64エンコードした値 |
[HTTP Method]\n
[Request URL]\n
[Request datetime]\n
[header1-name]:[value1]\n
[header2-name]:[value1,value2...]\n
...
GET /members?isEnable=false&type=public HTTP/1.1
Host: http://kr1-example.api.nhncloudservice.com
x-nhn-date: 2021-02-23T00:00:00+09:00
x-nhn-client-id: nhn
x-nhn-client-ip: 10.0.0.1,10.0.0.2
GET
/members?isEnable=false&type=public
2021-02-23T00:00:00+09:00
host:kr1-example.api.nhncloudservice.com
x-nhn-client-id: nhn
x-nhn-client-ip: 10.0.0.1,10.0.0.2
String secretKey = "HMACに設定した秘密鍵";
// 暗号化アルゴリズムHmacSHA1またはHmacSHA256
SecretKeySpec signingKey = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(signingKey);
String message = "StringToSign";
byte[] rawHmac;
rawHmac = mac.doFinal(message.getBytes());
String authorization = new String(Base64.encodeBase64(rawHmac));
Authorization:hmac algorithm="HmacSHA256", headers="host,x-nhn-client-id,x-nhn-client-ip" , signature="V5Dye9kgG3tvZOOZertd5LXE0q8CcJGXCxEFCR71hUE="
x-nhn-date:2021-02-23T00:00:00+09:00
[注意] SignToString作成注意事項
- SignToStringの各フィールドは改行文字(\n)で区切ります。 - headersに定義されたヘッダはSignToString作成時に含まれている必要があります。 - headersに定義したヘッダがない場合、[header name]と[header value]はSignToStringの作成に含めません。 - headersに定義したヘッダ順序通りにSignToStringを作成する必要があります。 - 例：headers="header1,header2"の場合、SignToStringを作成する時もheader1, header2の順序でヘッダを追加する必要があります。 - SignToStringのヘッダ名は英字小文字(lowercase)で統一して作成します。 - 例：X-NHN-Header → x-nhn-header - ヘッダ値が複数の場合、カンマ(,)で区切ってヘッダ値を作成します。 - 例：header1-name:header1-value1,header1-value2 - ヘッダ名と値はコロン(:)で区切ります。値を区切る時にスペースを含めません。
JWTトークンの署名とクレームを検証します。ユーザーサービスではトークンを検証せずにトークン値を使用できます。
| ヘッダ名 | ヘッダ値 |
|---|---|
| Authorization | Bearer "<jwt-token>" |
[参考] JWTトークン認証失敗レスポンス
JWTトークンの認証失敗時、401 Unauthorizedレスポンスが返されます。 詳細についてはエラーコード文書を参照してください。[参考] JWTトークン作成
API GatewayはJWTトークンの署名とクレーム条件が一致するかだけを検証します。JWTトークンはユーザーのアプリケーションまたは認証サービスプロバイダーを通して作成する必要があります。 開発およびテスト目的のJWTトークンの作成はJWTトークンのデバッグを参照してください。[参考] JWKS(JSON Web Key Set) URIの説明と注意事項
JWKSはAPI Gatewayがトークンの署名を検証するために必要なJWK(Json Web Key)暗号化キーのJSONデータです。 JWKの詳細な内容と仕様はRFC7515文書を参照してください。 設定されたJWKS URIはAPI Gatewayがアクセスできるように公開されている必要があり、ネットワーク、ファイアウォールなどにより遮断されないようにします。 設定されたJWKS URIは、API Gatewayが常にアクセスができるように運用されている必要があります。 JWKS URIにポートを直接指定する場合は80、443、10000～12000ポートのみ使用できます。[注意] JWKSキャッシュ
API Gatewayは、JWKS URIのレスポンスを5分間キャッシュします。 API GatewayのキャッシュによりJWKSの変更事項がAPI Gatewayに反映されるまで最大5分以上かかることがあります。
API GatewayのアクセスログをLog & Crash Searchサービスに保管できる機能です。
アクセスログはLog & Crash Searchサービスで確認できます。
logType: "NHN Cloud-APIGateway"| フィールド | 説明 |
|---|---|
| longRequestTime | リクエスト日時のタイムスタンプ |
| requestPath | リクエストパス |
| resourcePath | リクエストがマッピングされたリソースパス |
| requestHttpMethod | リクエストHTTPメソッド |
| clientIp | リクエストクライアントIP |
| responseHttpStatus | レスポンスHTTPステータスコード |
| body | {clientIp} - [{requestTime}] "{requestHttpMethod} {requestPath}" {responseHttpStatusCode}形式の文字列 |
| host | リクエストホスト：ステージURLのドメイン |
| logType | ログタイプ：「NHN Cloud-APIGateway」固定値 |
| logLevel | ログレベル：レスポンスステータスコードが400未満の場合は「INFO」、400以上の場合は「ERROR」 |
| errorCode | API Gatewayでエラーが発生した場合は、ゲートウェイエラーコード。エラー未発生時は空の値 |
| errorMessage | API Gatewayでエラーが発生した場合はゲートウェイエラーメッセージ。エラー未発生時は空の値 |
[参考]Log & Crash Search利用料金案内
アクセスログはLog & Crash Searchサービスに保存され、Log & Crash Searchサービス利用料金が別途請求されます。 Log & Crash Searchサービス紹介と利用料金は以下のリンクを参照してください。 Log & Crash Searchサービス紹介へ Log & Crash Search利用料金へ[注意]アクセスログ機能利用中におけるLog & Crash Searchサービス無効化時の注意事項
アクセスログ機能利用中にLog & Crash Searchサービスを無効化すると、アクセスログは保存されなくなり、アクセスログ機能は自動的に無効になります。 再度アクセスログ機能を利用するには、 Log & Crash Searchサービスを有効にした後、アクセスログ機能を再度有効にしてください。
事前呼び出しAPIは、バックエンドエンドポイントを呼び出す前にユーザーが指定したAPIを呼び出して、呼び出しのレスポンスコードに応じてバックエンドエンドポイントを呼び出すかどうかを決定します。 API Gatewayを介して入ったリクエストヘッダを含めて事前呼び出しAPIを呼び出し、事前呼び出しAPIは渡されたヘッダの内容に基づいてレスポンスコードを返します。
事前呼び出しAPIのレスポンスコードが200の場合、バックエンドエンドポイントを呼び出し、レスポンスコードが200ではない場合、事前呼び出しAPIのレスポンス結果を返します。 事前呼び出しAPIの呼び出しに失敗するとエラーを返します。
バックエンドエンドポイントを呼び出す前に別途APIを呼び出して認証が必要な場合や、先に呼び出す必要があるAPIが存在するなどの場合に活用できます。
[参考]事前呼び出しAPIのレスポンス結果のキャッシュ
事前呼び出しAPIのレスポンス結果コードが200の場合にのみレスポンス結果がキャッシュされます。 レスポンス結果コードが200ではない場合、キャッシュの有効時間が設定されていてもレスポンス結果がキャッシュされません。
API Gatewayに受信したリクエストをバックエンドエンドポイントへ伝達する時、基本的にステージに定義されたバックエンドエンドポイントURLへリクエストを伝達します。 特定パスまたはメソッドに対してバックエンドエンドポイントURLを再定義するには、バックエンドエンドポイントURLの再定義を設定します。
リクエスト数制限を利用してAPI Gatewayに受信するリクエストの毎秒リクエスト数を調節できます。これを利用してバックエンドエンドポイントを保護できます。
[参考]リクエスト数制限レスポンス
毎秒リクエスト数を超過すると、429 Too Many Requestsレスポンスが返されます。[注意]リクエスト制限キー
リクエスト制限キーを使用する場合、リクエストに指定したキーが含まれている必要があります。例えばリクエスト制限キーにヘッダを選択し、X-NHN-CLOUD値を入力した場合、リクエストヘッダにはX-NHN-CLOUDが含まれている必要があります。 リクエストにリクエスト制限キーが見つからない場合、リクエスト数制限が適用されません。[注意]毎秒リクエスト数の正確度
- 設定された毎秒リクエスト数と許可される実際のリクエスト数は、リクエストがAPI Gatewayに受信する時間、リクエスト処理時間およびその他の要因によって正確に一致しないことがあります。
登録されたリクエスト制限ポリシーをステージリソースパスまたはメソッドに適用します。 詳細はリクエスト制限ポリシーを参照してください。
API GatewayにAPIリクエストする時、指定されたAPI Keyのみリクエストできるように制限します。
[参考] API Key失敗レスポンス
API Key値がリクエストヘッダに含まれていないか、有効ではない、もしくは使用量限度を超過する場合にAPIリクエストが拒否されます。 詳細な内容はエラーコード文書を参照してください。 1. ステージタブでステージを選択します。 2. 設定タブを選択します。 3. ステージツリー画面でAPI Keyを有効にするパスまたはメソッドを選択します。 - パスで設定したAPI Keyはサブ定義されたすべてのサブパスとメソッドの呼び出しに対して適用されます。 4. API Keyを有効化(on)します。 5. ステージを配布します。 6. APIリクエスト時にx-nhn-apikeyヘッダにAPI Key値を追加してリクエストします。
| ヘッダ名 | ヘッダ値 |
|---|---|
| x-nhn-apikey | <primary api keyまたはsecondary api key> |
API Gatewayリソースに設定されたリクエストパラメータ設定に基づいてクライアントリクエストの有効性を検証します。 有効性検証に失敗した場合はエラーレスポンスを返し、リクエストをバックエンドエンドポイントに転送しません。
リクエストパラメータに検証するリクエストパラメータの情報を設定します。有効性検証がサポートされるパラメータタイプと検証方式は下記の内容を参照してください。
クエリ文字列
ヘッダ
フォームデータ
application/x-www-form-urlencodedの場合にのみフォームデータを検証します。 リクエスト本文
application/jsonの場合にのみリクエスト本文を検証します。コンテンツタイプ
*/*に設定されている場合にはコンテンツタイプを検証しません。ステージにリソース適用をクリックしてステージにリソースを適用します。
[注意]フォームデータとリクエスト本文設定
フォームデータとリクエスト本文は同時に設定できません。 同じリソースにContent-Typeでapplication/x-www-form-urlencodedとapplication/jsonを同時にサポートできないため、コンテンツタイプに応じてリソースを分離する必要があります。
モデルを定義してリクエストパラメータとレスポンスで使用できる本文の形態を指定できます。
リクエスト制限ポリシーは、リクエストのパス変数またはリクエストヘッダの値によってIP ACLとリクエスト数の制限を設定できる機能です。
[参考]リクエスト制限ポリシー作成数制限
リクエスト制限ポリシーはAPI Gatewayサービスごとに最大10個まで作成可能です。
リクエスト制限ポリシー名、基本毎秒リクエスト制限数、残りトークン数レスポンスの有無を修正できます。 リクエスト制限キータイプとリクエスト制限キーは修正できません。
[参考]リクエスト制限ポリシー削除不可
削除するリクエスト制限ポリシーがステージに設定されているか、配布されたステージに含まれている場合は削除ができません。 削除するにはステージに設定されたリクエスト制限ポリシーを削除し、ステージを配布した後に削除してください。
リクエスト制限ポリシーの制限キーの値を作成します。制限キーの値に基づいてIP ACLとリクエスト数制限を別々に設定できます。
1秒あたりのリクエスト数制限、 IPアクセス制御タイプとIPアクセス対象を修正します。 リクエスト制限キーの値は修正ができません。
ゲートウェイで定義されたエラーレスポンス設定をユーザーが再定義できます。
[参考]ゲートウェイレスポンスの適用
変更されたゲートウェイレスポンスは、ステージ配布後に配布時点の形状で適用されます。
curl --request GET 'https://kr1-xxxxx-test.api.nhncloudservice.com/example'[注意]ステージ配布
APIを呼び出すには配布成功状態の配布されたステージが必要です。[参考] API呼び出しが正常に行われない場合
- 404 NotFound HTTPステータスコードが返される場合 1. ステージを配布状態が配布成功状態になっているかを確認します。 2. リクエストメソッドとステージURLおよびパスが正しいか確認します。 3. バックエンドエンドポイントサービスからバックエンドエンドポイントURLパスに対するリクエストURLが存在するかを確認します。 - その他のエラーコードはエラーコード文書を参照します。[注意] API呼び出し制約事項
- GatewayクライアントからAPI Gatewayへリクエストするサイズ制限は最大10MBです。この値は調整できません。 - API GatewayからGatewayクライアントへのレスポンスサイズ制限は最大10MBです。この値は調整できません。 - リクエストに対するレスポンスタイムアウトは最大60秒です。バックエンドエンドポイントサービスでレスポンスが遅延する場合はタイムアウトが発生することがあります。[注意] API Gatewayリクエスト遮断ポリシー
- API Gatewayサービスとバックエンドエンドポイントサービスを保護する目的でバックエンドエンドポイントサービスが応答しなかったり、レスポンス遅延(60秒以上)が持続的に発生する場合、該当バックエンドエンドポイントサービスに対するリクエストを一時的に拒否します。 - バックエンドエンドポイントサービスの内部エラー(4xx, 5xxなど)では遮断されません。 - 正常に稼働中の状態ではないか、レスポンス遅延(Timeout)が60秒以上発生するバックエンドエンドポイントは連携しないことを推奨します。
API説明書を利用するとAPI Gatewayに登録されたAPIの仕様をWebページ文書で管理できます。
API説明書を掲示するための手順を案内します。
[参考]ステージ配布とAPI説明書掲示
- API説明書は、最初のステージ配布以降に掲示され、最初の掲示タイプは非公開に設定されます。 - API説明書はステージ配布時に配布される形でアップデートされます。[注意]掲示されたAPI説明書でAPI呼び出しテスト時のCORS設定
- 掲示されたAPI説明書ドメインアドレスと呼び出すAPIのドメインアドレスが異なるため、API説明書内で呼び出しをテストしたい場合はCORS設定が必要な場合があります。 - 例： Access-Control-Allow-Origin: https://kr1-docs-apigw.api.nhncloudservice.com Access-Control-Allow-Method: GET, POST, DELETE, PUT, PATCH, HEAD, OPTIONS Access-Control-Allow-Headers: Authorization, x-nhn-apikey, x-nhn-date
ダッシュボードを通してAPI Gatewayサービス、API KeyごとにAPI統計指標を確認できます。
リソースパスとHTTPメソッドごとに区切られた詳細な統計指標を確認できます。
API Keyごとに呼び出し数を日単位グラフで確認できます。
使用量計画のステージに接続されたAPI KeyのみステージAPIをリクエストできるように制限することができ、使用量制御設定を行って接続されたAPI Keyごとに共通使用量制限を適用できます。
使用量計画作成 -> 使用量計画にステージ接続 -> 使用量計画が接続されたステージにAPI Key接続 -> ステージ設定でAPI Keyを有効化[参考]リクエスト割り当て量限度の再設定
リクエスト割り当て量は毎月1日(月別期間)、毎日(日別期間) UTC 00:00:00に再設定されます。
[注意]使用量計画リクエスト制御設定の修正
使用量計画で毎秒リクエスト数制限、リクエスト割り当て量を修正する場合、別途の配布手順を踏まなくても接続されたAPIに反映されます。 割り当て量期間の単位を「日」または「月」に修正すると、接続されたAPI Keyリクエスト割り当て量の使用量は維持されます。リクエスト割り当て量の限度を下げると使用量が超過することがあります。 割り当て量期間の単位を「なし」に修正すると、接続されたAPI Keyのリクエスト割り当て量使用量は初期化されます。
[参考]接続されたステージがある場合は使用量計画の削除不可
使用量計画と接続されたステージを全て解除した後、使用量計画を削除できます。
API Keyがリクエスト可能なステージを定義するために使用量計画にステージを接続します。
[参考]すでに接続されたステージ
すでに接続されたステージは選択リストに表示されません。
[参考]接続されたAPI Keyがある場合はステージ解除不可
使用量計画に接続されたステージを解除するにはステージに接続されたすべてのAPI Keyを解除する必要があります。
使用量計画に接続されたステージのAPIを呼び出すためにAPI Keyを接続します。
[参考]他の使用量計画の同じステージに接続されたAPI Keyは選択できるリストに表示されず、接続できません。
[参考]選択したステージが接続された他の使用量計画にのみ変更できます。
[注意]使用量計画変更時、API Keyリクエスト割り当て量の使用量初期化
割り当て量期間の単位が「日」または「月」の使用量計画に変更すると、接続されたAPI Keyリクエスト割り当て量の使用量は維持されます。リクエスト割り当て量の限度が低い使用量計画に変更すると、使用量が超過することがあります。 割り当て量期間の単位が「なし」の使用量計画に変更すると、接続されたAPI Keyリクエスト割り当て量の使用量は初期化されます。
[注意]ユーザー定義Primary/Secondary API Key
ユーザー定義Primary/Secondary API Keyは最低10文字以上の英数字で構成された文字列で作成します。 API Gateway全体サービスで一意である必要があります。 外部へ公開されないように注意する必要があり、複雑に構成することを推奨します。
登録したAPI KeyをCSV形式のファイルにエクスポートできます。 1. API Keyリストページでエクスポートボタンをクリックします。 2. CSVファイルをダウンロードします。
[参考] API Keyリストに照会されたAPI Keyのみファイルとしてエクスポートします。
CSV形式のファイルでAPI Keyをインポートできます。 1. API Key一覧ページでインポートボタンをクリックした後、ファイル選択ボタンをクリックしてインポートするCSVファイルを選択します。 2. CSVファイルを基準に登録されたAPI Keyの一覧が画面に表示されます。 - インポートしたデータに修正が必要な部分がある場合は、データをインポートできません。 3. インポートボタンをクリックします。
[参考]API Keyが重複した場合、インポートに失敗します。
重複したPrimary API Key、Sencondary API Keyが存在すると、すべてのAPI Keyのインポートに失敗します。重複したAPI Keyを修正した後、インポートを再試行してください。
[注意] API Keyの状態変更
API Keyの状態をINACTIVEに変更すると、該当API Keyを使用できません。
[参考]接続された使用量計画、ステージがある場合は削除不可
接続された使用量計画、ステージがある場合はAPI Keyを削除できません。
APIリクエスト時にAPI Key値として使用されるPrimary API Key、Secondary API Keyは再発行できます。
デフォルトのステージドメインは{Region}-{ServiceId}-{StageName}.api.nhncloudservice.com形式でランダムに発行されます。 ユーザー指定でランダムに発行されたドメインの代わりに、ユーザーがドメインのPrefixを指定して{CustomDomainPrefix}.capi.nhncloudservice.com形式のドメインを作成することができます。
[注意]ユーザー指定ドメイン
ユーザー指定ドメインは、最小2文字、最大50文字の英小文字、数字、 -で構成された文字列で作成します。 API Gateway全体サービスで一意である必要があります。
[注意]ユーザー指定ドメインの削除不可
ステージに接続されたユーザー指定ドメインは削除できません。 ステージでユーザー指定ドメインを接続解除した後、削除してください。
[注意]ステージ接続解除すると、ユーザー指定ドメインでAPI呼び出し不可
ユーザー指定ドメインのステージ接続解除を行うと、ユーザー指定ドメインでステージAPIを呼び出すことができなくなります。 ユーザー指定ドメインを利用してAPIを呼び出すクライアントがないことを必ず確認してから接続を解除してください。
API Gatewayが位置するリージョンに障害が発生すると、当該リージョンのAPI Gatewayは正常に運営されない場合があります。 特定のリージョン障害の影響を受けずにAPI Gatewayサービスを運営するには、複数のリージョンにAPI Gatewayを冗長化することで回避できます。 次は、運営中の韓国(パンギョ)リージョンと新規に韓国(ピョンチョン)リージョンにAPI Gatewayを構成してリージョンを冗長化するシナリオです。
[参考]リソース > リソースインポート時のステージプラグイン設定 Swaggerファイルでリソースをインポートする時、ステージに設定されたプラグインはインポートされません。必要なプラグインはステージ設定で別途追加してください。
このガイドではNHN Cloud DNS PlusサービスのGSLBを利用します。 GSLB設定の詳細は、DNS Plusコンソール使用ガイドを参照してください。
サービスゲートウェイを利用すると、NHN Cloud内部でクライアントとAPI Gatewayが通信する際、外部インターネットを経由せず、内部ネットワークで通信できます。 API Gatewayサービスゲートウェイを連動する方法は、次のガイドを参照してください。
[参考]/etc/hostsファイル修正
/etc/hostsファイルを修正しないと、ステージURLでAPI呼び出しができません。 1つのサービスゲートウェイIPで複数のAPI Gatewayステージドメインを登録し、使用できます。