- 印刷する
- PDF
My Products
- 印刷する
- PDF
最新のコンテンツが反映されていません。早急にアップデート内容をご提供できるよう努めております。最新のコンテンツ内容は韓国語ページをご参照ください。
Classic/VPC環境で利用できます。
My Productsメニューでは、複数の APIを Productにグループ化して管理し、REST APIとこれに関連したリソースとメソッドを定義して認証方式を設定できます。APIを掲載し、Productを使用している API Keyでユーザーのアプリケーションを識別したり、使用量を制限できます。
My Products画面
API Gatewayを利用するための My Productsメニューの基本的な説明は、次の通りです。
領域 | 説明 |
---|---|
① メニュー名 | 現在確認中のメニュー名、運用中の Product数 |
② 基本機能 | Productの作成、API Gateway詳細情報の確認、My Products画面の更新 |
③ 作成後の機能 | 運用中 Productの変更、削除 |
④ Productリスト | 運用中の Productリストと情報を確認 |
⑤ 検索ボックスとフィルタ | リストで Productを検索、フィルタ機能を利用して条件に該当する Productを確認 |
Productリストの確認
作成して運用中の Productリストで Product別情報を確認できます。
Product作成方法については、API Gateway を開始するをご参照ください。
作成した Productの情報を確認する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストが表示されたらサマリー情報を確認するか、対象 Productをクリックして詳細情報を確認します。
- Product ID : Productの固有 IDであり、Product作成時に自動設定
- Product名 : Productの作成時に設定した Productの名前
- 説明 : Productの作成時に設定した、当該 Productについての説明
- サブスクリプション方式 : Productの作成時に設定した APIのサブスクリプション方式
- 状態 : APIの掲載有無の表示
- Catalog : 掲載された APIに対する Overviewとご利用ガイド(Swagger)を確認
- 掲載 : をクリックして API掲載画面に移動
- API Keys : Productに繋がった API Keyのステータス別の状況。 をクリックして API Keyの確認、追加、状態変更と Usage Planの確認、変更画面に移動
- APIs : Productに作成され APIリストと状況。 をクリックして API管理画面に移動
- API名 : API名をクリックして、当該 API管理画面に移動
- 定義されたメソッド : API別に定義されたメソッド数
- Stage Document : Stage名をクリックして、当該 APIのご利用ガイド(Swagger)画面に移動
Product変更
Productを変更する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで変更する Productのチェックボックスをクリックして選択した後、 [変更] ボタンをクリックします。
- Productの変更画面で Product情報を変更した後、 [Product変更] ボタンをクリックします。
- 名前 : Product名を表示
- 説明 : Productについての説明を変更・入力
- サブスクリプション方式 : Productのサブスクリプション方式を選択
- 公開 - 自律サブスクリプション : Productの APIを誰でも使用できる
- 保護 - 承認が必要 : Productの APIを使用するためには掲載者の承認が必要
- Productの変更ポップアップで [確認] ボタンをクリックします。
Product削除
Productを削除する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストから削除する Productをクリックして選択した後、 [削除] ボタンをクリックします。
- 削除のポップアップで内容を確認し、 名前 に削除する Product名を入力した後、 [削除] ボタンをクリックします。
API登録
APIを作成・管理して関連リソースとメソッドを管理できます。また、APIのユーザーが参照できる、定義された API明細と Overviewを管理でき、ステージを活用して同一の APIを様々なバージョンで運用できます。バックエンドサービスの安定化のために、ステージ別にキャッシュ使用、Throttlingポリシー、IP ACLなどを設定できます。
API作成
作成した Productに複数の APIを作成できます。
APIを作成する方法は、次の通りです。
NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
My Products メニューをクリックします。
Productリストで APIを作成する Productの APIs 列の をクリックします。
APIリスト画面で [API作成] ボタンをクリックします。
API作成画面の API作成 項目で作成方法を選択します。
APIの作成方法に応じて設定情報を入力します。
- APIの作成方法で 新しい API を選択した場合、以下の項目を設定
- API名 : 作成する API名を入力。APIの名前は API Gatewayの呼び出し URLのパスに含まれる
- 説明 : 作成する APIの説明を入力
- APIの作成方法で APIコピー を選択した場合、以下の項目を設定
- API名 : 作成する API名を入力。APIの名前は API Gatewayの呼び出し URLのパスに含まれる
- 説明 : 作成する APIの説明を入力
- APIをコピー : コピーする APIがある Productを選択し、コピーする APIを選択
- APIの作成方法で Swaggerからインポート を選択した場合、以下の項目を設定
- API名 : 作成する API名を入力。APIの名前は API Gatewayの呼び出し URLのパスに含まれる
- 説明 : 作成する APIの説明を入力
- Swaggerからインポート 領域
- [Swagger] タブ: 外部に保存された Swaggerファイルをインポートして APIを作成
- Drop files here or click to upload. : 外部に保存された Swaggerファイルをドラッグするか、領域をクリックしてエクスプローラー画面で Swaggerファイルを選択
- 警告失敗 : Swaggerファイルのインポート時にエラーまたは警告が発生すると、インポートを中止
- 警告無視 : Swaggerファイルのインポート時に発生するエラーまたは警告に関係なくインポート
- [プレビュー] タブ: Swaggerの設定状態をプレビュー
- [Swagger] タブ: 外部に保存された Swaggerファイルをインポートして APIを作成
- APIの作成方法で APIのユースケース を選択した場合、以下の項目を設定
- API名 : 作成するユースケース API名を入力。APIの名前は API Gatewayの呼び出し URLのパスに含まれる
- 説明 : 作成するユースケース APIの説明を入力
- APIのユースケース : 作成するユースケース APIの詳細情報を表示
- APIの作成方法で 新しい API を選択した場合、以下の項目を設定
[API作成] ボタンをクリックします。APIの作成方法が APIコピー の場合、[APIコピー] ボタンをクリックします。
APIの作成成功ポップアップで [確認] ボタンをクリックします。
APIの作成に成功した後の APIリスト画面についての説明は、次の通りです。
領域 | 説明 |
---|---|
① API名 | 当該 Productに作成されている APIリスト。クリックすると、使用可能な機能と詳細情報が画面右側に表示される。 |
② APIの変更、リリース、削除 | API説明を変更、Stageに APIリリース、API削除 |
③ Resources | |
④ Stages | Stage作成と管理 |
⑤ Gateway Responses | API Gatewayで発生したゲートウェイレスポンスの定義。変更事項を適用するには、APIをリリースする必要がある |
⑥ Models | リクエストとレスポンスのボディモデルの定義。変更時の変更事項を適用するには、APIをリリースする必要がある |
⑦ Overview | APIご利用ガイドの Overview作成 |
API変更
APIについての説明を変更する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- Productリストで変更する APIがある Productの APIs 列の をクリックします。
- APIリストで変更する APIをクリックします。
- [変更] ボタンをクリックします。
- APIの変更画面の 説明 項目に設定内容を追加または変更した後、 [保存] ボタンをクリックします。
API削除
APIを削除する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- Productリストで削除する APIがある Productの APIs 列の をクリックします。
- APIリストで削除する APIをクリックします。
- [削除] ボタンをクリックします。
- 削除のポップアップで削除する APIの名前を入力し、 [削除] ボタンをクリックします。
リソース管理
APIを使用するために必要なリソースを作成して管理できます。
[Resources] タブメニューについての説明は、次の通りです。
領域 | 説明 |
---|---|
① リソース作成 | APIに新規リソース作成 |
② リソースを見る | リソース CORS有効化有無の設定 |
③ リソース削除 | 不要なリソース削除 |
④ APIをインポートする | Swaggerファイルをインポートしてリソースを作成(APIをインポートするを参照) |
⑤ ルートリソースのパス | APIの作成時にデフォルトで作成されるルートリソース(/ で表示) |
⑥ リソース名(パス) | リソース作成時に設定した API URLのパス |
⑦ メソッド | メソッド作成機能でリソースに追加したメソッド |
⑧ OPTIONSメソッド | CORSを有効化した後に自動で作成されたメソッド(リソース作成の7番手順またはリソースの CORS設定を参照) |
⑨ メソッド作成 | リソースにメソッド作成
|
⑩ メソッドリスト | リソースに追加されたメソッドリスト(カードタイプ)でそのリソースの設定情報を確認 |
リソース作成
リソースを作成する方法は、次の通りです。
NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
My Products メニューをクリックします。
Productリストでリソースを作成する Productの APIs 列の をクリックします。
- 詳細情報の APIs リストにある API名をクリックして当該 APIが選択された APIリスト画面に移動します。
APIリストでリソースを作成する APIをクリックします。
[Resources] タブをクリックします。
[リソース作成] ボタンをクリックします。
- 既に作成済みリソースの下位にリソースを追加するには、そのリソースを選択した後 [リソース作成] ボタンをクリックします。
- 既に作成済みリソースのうち、パスが
{variable+}
のように+
が含まれていてサブリソースを含むリソースには、サブリソースを作成できません。
リソースリスト右側に表示されたリソースの作成項目に情報を入力した後、 [作成] ボタンをクリックします。
リソースパス : API URLのパスとして使用する値を入力
- 括弧を使用してリソースをパス変数に指定できます。
- 例1)
{variable}
: 現在のパスを変数として使用 - 例2)
{variable+}
: サブリソースを含むパスを変数として使用
- 例1)
- パス変数は、エンドポイントのパスにパラメータとして使用できます。
参考Endpointで Cloud Functionsの Web Actionを使用すると、
{type}
変数は予約語として処理されます。- 括弧を使用してリソースをパス変数に指定できます。
{type}
変数は、Cloud Functionsで Web actionの Content extensionsを定義するための予約語です。
したがって、Cloud Functionsの Web Actionを Endpointとして使用する APIリソースに {type}
変数が存在する場合、その値を Cloud Functionsの extension変数 {type}
に使用し、当該変数に対する定義がなければ空値として処理します。
:::
有効化 CORS : CORS(Cross-Origin Resource Sharing)の有効化有無の選択。有効化を選択すると追加項目の設定が必要。
- Access-Control-Allow-Method : クライアントリクエスト(リソースアクセス)時に許可するメソッドを設定
- Access-Control-Allow-Headers : クライアントリクエスト(リソースアクセス)時に許可するヘッダを設定
- Access-Control-Allow-Origin : クライアントリクエスト(リソースアクセス)に全てのドメインを許可(
*
)、または選別的に許可を設定 - Access-Control-Expose-Headers : クライアントリクエスト(リソースアクセス)に包含可能なユーザー定義ヘッダ
- Access-Control-Max-Age : クライアントが Preflightリクエスト結果を保存する期間。この時間中は Preflightリクエストを再度行わない
- Access-Control-Allow-Credentials : クライアントリクエスト(リソースアクセス)の認証情報モード(Request.credentials)が
include
の場合にレスポンスの表示有無を設定。必要な場合はtrue
(唯一の値)に設定、不要な場合はヘッダを入力しない
- [Resources] タブのリソースリストに作成されたリソースが表示されるか確認します。
- 有効化 CORS 項目を有効化した場合、API Gatewayで CORSリクエストを処理するために OPTIONSメソッドが作成され、そのリソースリストに表示されます。ただし、OPTIONSメソッドは変更できません。
リソースの CORS設定
リソースの CORSの有効化有無を設定し、有効時の追加項目を設定できます。
リソースの確認と CORS設定を変更する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの APIs 列の をクリックします。
- 詳細情報の APIs リストにある API名をクリックして当該 APIが選択された APIリスト画面に移動します。
- APIリストで、確認・設定するリソースがある APIをクリックします。
- [Resources] タブをクリックします。
- リソースリストで、確認・設定するリソースをクリックして選択した後、 [リソースを見る] ボタンをクリックします。
- CORS(デフォルト値: 無効化)を設定するには、 有効化 CORS をクリックして有効化した後、追加ヘッダ項目を設定します。
- 追加ヘッダ項目に関する詳細は、リソース作成の7番手順をご参照ください。
- [変更] ボタンをクリックします。
- CORS有効化に設定した場合、OPTIONSメソッドが作成され、リソースリストに表示されます。
リソース削除
リソースを削除する方法は、次の通りです。
OPTIONSメソッドは削除できません。リソースの CORSを無効化すると、自動で削除されます。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの APIs 列の をクリックします。
- 詳細情報の APIs リストにある API名をクリックして当該 APIが選択された APIリスト画面に移動します。
- APIリストで削除するリソースがある APIをクリックします。
- [Resources] タブをクリックします。
- リソースリストで、削除するリソースをクリックして選択した後、 [リソース削除] ボタンをクリックします。
- 削除のポップアップで内容を確認し、 [削除] ボタンをクリックします。
APIをインポートする
APIの構成関連文書の Swaggerファイルを利用して APIリソースをインポートできます。
外部から APIリソースをインポートする方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの APIs 列の をクリックします。
- 詳細情報の APIs リストにある API名をクリックして当該 APIが選択された APIリスト画面に移動します。
- APIリストで対象 APIをクリックします。
- [Resources] タブをクリックします。
- リソースリストで、対象リソースをクリックして選択し、 [APIをインポートする] ボタンをクリックします。
- APIのインポートを実行すると現在保存されているリソースは削除され、インポートされた API情報が新しいリソースとして保存されます。
- 外部に保存された Swaggerファイルを Drop files here or click to upload。 領域にドラックまたは領域をクリックしてエクスプローラー画面で Swaggerファイルを選択します。
- APIをインポートする際に発生し得るエラーまたは警告の処理方法を選択します。
- 警告失敗 : Swaggerファイルのインポート時にエラーまたは警告が発生すると、インポートを中止
- 警告無視 : Swaggerファイルのインポート時に発生するエラーまたは警告に関係なくインポート
- JSON形式の API定義の詳細を確認・変更し、 [APIをインポートする] ボタンをクリックします。
- 設定した内容を予め確認するには、 [プレビュー] タブをクリックします。
- APIのインポートポップアップで内容を確認し、 [はい] ボタンをクリックします。
- エラーが発生すると、エラー内容を確認して変更し、再試行してください。
メソッド管理
APIリソースにメソッドを作成・設定し、テストできます。
メソッド作成
リソースにメソッドを作成する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの APIs 列の をクリックします。
- 詳細情報の APIs リストにある API名をクリックして当該 APIが選択された APIリスト画面に移動します。
- APIリストで対象 APIをクリックします。
- [Resources] タブをクリックします。
- リソースリストでメソッドを作成するリソースをクリックします。
- リソースリスト右側に表示された [メソッド作成] ドロップダウンメニューで、作成するメソッドの種類を選択します。
- [Settings] タブをクリックして設定情報を入力し、[保存] ボタンをクリックします。
- 説明 : メソッドの説明を入力
- エンドポイント : サービスを提供するエンドポイントを設定。エンドポイントの種類に応じてメソッドの設定項目が異なります。
MOCK : API Gatewayで設定した値を返す
- Status Code : リクエストに対するレスポンスコードを設定
- Header : リクエストに対するヘッダを入力
- Response : リクエストに対するボディを入力
HTTP(S) : HTTP(S)のエンドポイントの呼び出し結果を返す
Stream : ファイルアップロードのようなリクエストの場合、有効化
- Streamをオフにした場合、レスポンス時間は30秒、最大リクエストサイズは10MBに制限
- Streamをオンにした場合、レスポンス時間は5分、最大リクエストサイズは100MBに制限
メソッド : バックエンドサーバにリクエストするメソッドを選択
URLパス : バックエンドサーバにリクエストするドメインを除く URLを入力(エンドポイントとして呼び出す URLパス)
参考- リソースパスの変数とリクエストパラメータで定義したクエリ文字列、ヘッダをパラメータとして使用できます。
- パラメータは括弧を使用して定義します。
NAVER Cloud Platform Service : NAVERクラウドプラットフォームで提供されるサービス(例) Cloud Functions)を利用
- サービス : サービスを選択
- リージョン : サービスサポートリージョンを選択
- アクション : 当該サービスに設定されたアクションを選択
- API Keyの要否 : API Keyの使用有無を選択
- API Keyを使用しない場合、Productのサブスクリプション方式と Usage Planが適用されない
- 認証 : 認証方法を設定
- NONE : 認証を使用しない
- IAM : NAVERクラウドプラットフォームが提供する IAM認証を使用
- 既に作成した Authorizerを使用(Authorizerを参照)
- 有効性検査 : 有効性検査スコープを選択
- NONE : 有効性検査を実行しない
- Query Strings & Headers : クエリ文字列とヘッダに対して有効性検査を実行。有効性検査は、Parametersタブで定義した API明細を参照
メソッド設定
作成したメソッドの設定を変更する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの APIs 列の をクリックします。
- 詳細情報の APIs リストにある API名をクリックして当該 APIが選択された APIリスト画面に移動します。
- APIリストで対象 APIをクリックします。
- [Resources] タブをクリックします。
- リソースリストで設定するメソッドが含まれている上位リソースをクリックします。
- 設定するメソッドをクリックします。
- または、上位リソースのメソッドリストで当該メソッドの [見る] ボタンをクリックします。
- [Settings] と [Parameters] タブをクリックして各項目を設定します。
- [Settings] タブの設定情報は、メソッド作成をご参照ください。
- [Parameters] タブの設定情報は、API明細の定義をご参照ください。
- 設定の変更後にメソッドをテストする方法は、APIテストをご参照ください。
メソッド削除
作成したメソッドを削除する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの APIs 列の をクリックします。
- 詳細情報の APIs リストにある API名をクリックして当該 APIが選択された APIリスト画面に移動します。
- APIリストで対象 APIをクリックします。
- [Resources] タブをクリックします。
- リソースリストで削除するメソッドが含まれている上位リソースをクリックします。
- メソッドリストで削除するメソッドの [削除] ボタンをクリックします。
- メソッドの削除ポップアップで [削除] ボタンをクリックします。
API明細の定義
API明細(リクエスト/レスポンスパラメータ)を定義できます。定義された API明細は Swagger UIの作成に利用されます。
API明細を定義する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの APIs 列の をクリックします。
- 詳細情報の APIs リストにある API名をクリックして当該 APIが選択された APIリスト画面に移動します。
- APIリストで対象 APIをクリックします。
- [Resources] タブをクリックします。
- リソースリストで、対象リソースのメソッドをクリックして選択し、右側画面に表示された詳細情報で [Parameters] タブをクリックします。
- リクエストとレスポンスパラメータを設定します。
リクエスト の領域: リクエストに対する明細を定義
クエリ文字列 : リクエストのクエリ文字列を定義。エンドポイントとして呼び出す URLパスを定義する際に、リソースパス変数のように変数として使用可能。
- 名前 : クエリ文字列の名前を入力
- 説明 : クエリ文字列に対する説明を入力
- 変数のタイプ: クエリ文字列の変数タイプ( string 、 boolean 、 integer 、 long 、 float 、 double )を選択
- Array : 有効化すると、重複した名前で複数のクエリ文字列を作成
- Required : 有効化すると、有効性検査対象に含める
- 項目を追加するには、設定項目を入力して [追加] ボタンをクリックします。
- 既に追加された項目を削除するには、当該項目 [削除] ボタンをクリックし、クエリ文字列の削除ポップアップの [削除] ボタンをクリックします。
ヘッダ : リクエストのヘッダを定義。エンドポイントとして呼び出す URLパスを定義する際に、リソースパス変数のように変数として使用可能。
- 名前 : ヘッダの名前を入力
- 説明 : ヘッダに対する説明を入力
- 変数のタイプ: クエリ文字列の変数タイプ( string , boolean , integer , long , float , double )を選択
- Array : 有効化すると、重複した名前で複数のヘッダを作成
- Required : 有効化すると、有効性検査対象に含める
- 項目を追加するには、設定項目を入力して [追加] ボタンをクリックします。
- 既に追加された項目を削除するには、当該項目 [削除] ボタンをクリックした後、ヘッダの削除ポップアップの [削除] ボタンをクリックします。
フォームデータ : リクエストのフォームデータを定義
- 名前 : フォームデータの名前を入力
- 説明 : フォームデータに対する説明を入力
- 変数のタイプ: フォームデータの変数タイプ( string , boolean , integer , long , float , double , file )を選択
- Array : 有効化すると、重複した名前で複数のクエリ文字列を作成
- Required : 有効化すると、有効性検査対象に含める
- 項目を追加するには、設定項目を入力して [追加] ボタンをクリックします。
- 既に追加された項目を削除するには、当該項目の [削除] ボタンをクリックした後、フォームデータの削除ポップアップの [削除] ボタンをクリックします。
ボディ : リクエストのボディを定義
- 名前 : ボディの名前を入力
- 説明 : ボディに対する説明を入力
- モデル : ボディのモデルを定義。ボディのモデルは、APIリストの [Models] タブに定義されたモデルを使用(リクエストとレスポンスのボディモデルの定義を参照)
- リクエストのボディを定義するには、設定項目を入力して [保存] ボタンをクリックします。
- 保存された項目を削除するには、当該項目の [削除] ボタンをクリックした後、ボディの削除ポップアップの [削除] ボタンをクリックします。
コンテンツタイプ : リクエストボディのコンテンツタイプを定義
- コンテンツタイプを追加するには、入力欄にリクエストのコンテンツタイプを入力し、 [追加] ボタンをクリックします。
- 既に追加された項目を削除するには、当該項目の [削除] ボタンをクリックした後、コンテンツタイプの削除ポップアップの [削除] ボタンをクリックします。
参考application/x-www-form-urlencoded
、multipart/form-data
は定義されたフォームデータを利用してリクエストのボディを作成します。その他のコンテンツタイプはボディを使用してください。
レスポンス の領域: レスポンスに対する明細を定義
- [追加] : 新しいレスポンスコードの作成と定義
- [変更] : 定義されたレスポンスコードを変更
- [削除] : レスポンスコードを削除
- ヘッダ (レスポンスコードの選択時): レスポンスのヘッダを定義
- ボディ (レスポンスコードの選択時): レスポンスのボディを定義
- コンテンツタイプ : レスポンスボディのコンテンツタイプを定義
APIのテスト
登録した APIをリリースする前に、リソースのメソッドが正常に動作するかテストできます。
テストに認証や使用計画は適用されません。
APIをテストする方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの APIs 列の をクリックします。
- 詳細情報の APIs リストにある API名をクリックして当該 APIが選択された APIリスト画面に移動します。
- APIリストで対象 APIをクリックします。
- [Resources] タブをクリックします。
- リソースリストで、当該リソースのメソッドをクリックして選択した後、右側画面に表示された詳細情報で [Test] タブをクリックします。
- エンドポイント 領域で URLパス を確認して Client Certificate を選択します。
- Client Certificateに関する詳細は、Client Certificatesをご参照ください。
- リクエストパラメータ 領域でテストパスを設定し、リクエストパラメータの設定情報を確認します。
- [Test] ボタンをクリックします。
- [Test] ボタン下段に表示されるテストの結果内容を確認します。
Stage管理
Stageを活用して APIを様々なバージョンでリリース・運用できます。バックエンドサービスの安定化のために、ステージ別にキャッシュ使用、Throttlingポリシー、IP ACL、Content Encodingなどを設定できます。
[Stages] タブメニューについての説明は、次の通りです。
領域 | 説明 |
---|---|
① Stage作成 | Stage作成 |
② Stage削除 | Stage削除 |
③ Canaryの有効化 | API明細を Stageにリリースする前に、Canary環境を作って運用環境でテストできる機能を有効にする
|
④ 作成された Stageリスト | 作成した Stageリストとパス情報 |
⑤ 設定と情報 | Stageリストで Stage名、ルートリソース(/)、リソース、メソッドを選択する際に表示される設定項目と情報の領域 |
Stageリストで Stage名、ルートリソース(/)、リソース、メソッドを選択する際に表示される情報は、次の通りです。
Stage名を選択した際
領域 説明 ① Invoke URL リリースした APIを呼び出せる URL - の構成形式:
https://{product-id}.apigw.ntruss.com/{api-name}/{stage-name}
- アドレスをクリップボードに保存するには、[アドレスコピー] ボタンをクリック
② Settings Stageの設定を確認 ③ Export Stageをエクスポートする ④ Deployment History Stageにリリースされた APIバージョンを管理。Canary環境では表示しない ⑤ Usage Plans API使用量を制御。Canary環境では表示しない ⑥ Document Stage情報を Swagger形式で確認 - の構成形式:
ルートリソース(
/
)を選択した際
領域 説明 Invoke URL リリースした APIを呼び出せる URL - の構成形式:
https://{product-id}.apigw.ntruss.com/{api-name}/{stage-name}
- アドレスをクリップボードに保存するには、[アドレスコピー] ボタンをクリック
- の構成形式:
リソースパス(名前)を選択した際
領域 説明 ① Invoke URL リリースした APIを呼び出せる URL - の構成形式:
https://{product-id}.apigw.ntruss.com/{api-name}/{stage-name}
- アドレスをクリップボードに保存するには、[アドレスコピー] ボタンをクリック
② メソッドリスト Stageにリリースされた APIリソースのメソッドリスト(カードタイプ) - [見る]: 当該 Stageのメソッド情報を見る
- の構成形式:
メソッドを選択した際
領域 説明 ① Invoke URL リリースした APIを呼び出せる URL - の構成形式:
https://{product-id}.apigw.ntruss.com/{api-name}/{stage-name}
- アドレスをクリップボードに保存するには、[アドレスコピー] ボタンをクリック
② Target エンドポイントドメインのサービス名 ③ Stage設定に従う Stage設定に応じた APIキャッシュ、Throttling値の実行 - このページでの設定変更は不可
④ メソッドを設定する APIキャッシュ、Throttlingの値をメソッドに直接設定。項目を選択すると、以下の APIキャッシュ、Throttling項目の設定可能 ⑤ APIキャッシュ APIキャッシュ(Cache) TTLを設定 ⑥ Throttling 登録したメソッド別に1秒当たりのリクエスト数を制限してバックエンドサーバを保護 - の構成形式:
Stage作成
作成・設定を行った APIをリリースするには、まず Stageを作成する必要があります。
Stageを作成する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの APIs 列の をクリックします。
- 詳細情報の APIs リストにある API名をクリックして当該 APIが選択された APIリスト画面に移動します。
- APIリストで Stageを作成する APIをクリックします。
- [Stages] タブをクリックします。
- [Stage作成] ボタンをクリックします。
- Stageの作成情報を入力し、 [作成] ボタンをクリックします。
- Stage名 : Stageの名前を入力。Stageの名前は API Gatewayの呼び出し URLのパスに含まれる
- Endpointドメイン : バックエンドサーバのドメインを入力。APIのリソースパス(Resource Path)と結合して、バックエンドサーバに呼び出す APIパスになる
- Certificate名 : Client Certificates証明書を選択(証明書の有効期間は証明書の作成日から1年)
- APIキャッシュ : キャッシュ(Cache)を設定。設定の選択時に TTL 項目が表示される。
- TTL : キャッシュを維持する秒数(sec)を入力
- Throttling : 登録したメソッド別に1秒当たりのリクエスト数を制限してバックエンドサーバを保護
- IP ACL : IPアドレスに応じて APIリクエストを制御
- メンテナンス : 全ての APIが定義されたステータスコードとレスポンスを返すように設定
- Content Encoding : リクエスト、レスポンスに送信するデータの圧縮とエンコードを設定
- Stageの作成成功ポップアップで [確認] ボタンをクリックします。
- Stageが作成されると、定義された APIが新しい Stageにリリースされます。
Stage設定
Stageの設定を変更する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの APIs 列の をクリックします。
- 詳細情報の APIs リストにある API名をクリックして当該 APIが選択された APIリスト画面に移動します。
- APIリストで設定する Stageがある APIをクリックします。
- [Stages] タブをクリックします。
- Stageリストで、設定する Stageの名前をクリックします。
- Stageリストの右側に表示された詳細情報画面で [Settings] タブをクリックします。
- 設定項目を変更し、 [保存] ボタンをクリックします。
- Stageの設定項目についての説明は、Stage作成をご参照ください。
- APIキャッシュ の TTL値が設定されている場合、これを初期化するには [初期化] ボタンをクリックし、キャッシュの初期化ポップアップで [削除] ボタンをクリックします。その後、初期化成功のポップアップで [確認] ボタンをクリックします。
- 変更のポップアップで [変更] ボタンをクリックします。
- 変更成功のポップアップで [確認] ボタンをクリックします。
Stage削除
Stageを削除する方法は、次の通りです。
削除した Stageは復旧できません。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの APIs 列の をクリックします。
- 詳細情報の APIs リストにある API名をクリックして当該 APIが選択された APIリスト画面に移動します。
- APIリストで削除する Stageがある APIをクリックします。
- [Stages] タブをクリックします。
- Stageリストで、削除する Stageの名前をクリックします。
- [Stage削除] ボタンをクリックします。
- 削除のポップアップで削除する Stageの名前を入力した後、 [削除] ボタンをクリックします。
Stageをエクスポートする
Stageにリリースされた APIを Swagger JSON 2.0、Open API JSON 3.0、Java SDK形式でダウンロードできます。
リリースされた API Swaggerファイルをダウンロードする方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの APIs 列の をクリックします。
- 詳細情報の APIs リストにある API名をクリックして当該 APIが選択された APIリスト画面に移動します。
- APIリストで対象 APIをクリックします。
- [Stages] タブをクリックします。
- Stageリストで、エクスポートする Stageの名前をクリックします。
- Stageリスト右側に表示された詳細情報画面で [Export] タブをクリックします。
- プラットフォーム 項目で、エクスポートするファイル形式を選択した後、[エクスポート] ボタンをクリックします。
- Java SDK を選択した場合、必要に応じて追加項目を設定します。
リリース履歴の確認と管理
Stageの APIリリース履歴を確認し、履歴のダウンロード、以前のバージョンでリリース、履歴を削除できます。
リリース履歴を確認して管理する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの APIs 列の をクリックします。
- 詳細情報の APIs リストにある API名をクリックして当該 APIが選択された APIリスト画面に移動します。
- APIリストで対象 APIをクリックします。
- [Stages] タブをクリックします。
- Stageリストで APIリリース履歴を確認する Stage名をクリックします。
- Stageリスト右側に表示された詳細情報画面で [Deployment History] タブをクリックします。
- リリース履歴を確認したり、以前のリリース版をダウンロード、リリース、削除します。
- リリース日時 : APIを当該 Stageにリリースした日時(UTC基準)
- 説明 : APIリリース時に入力した説明
- リリースされた Stage : 現在 Stageにリリースされた項目に を表示
- エクスポートする : 以前のリリース版を Swagger JSON 2.0形式でダウンロード
- リリース : 以前のリリース版でリリースする
- 削除 : リリース履歴を削除
Usage Plansの変更
Stageの API基本リクエスト処理量と、リクエスト処理限度を設定でき、Usage Plansメニューで作成した Usage Planを関連付けて管理することができます。
Stageで Usage Plansの設定を変更する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの APIs 列の をクリックします。
- 詳細情報の APIs リストにある API名をクリックして当該 APIが選択された APIリスト画面に移動します。
- APIリストで対象 APIをクリックします。
- [Stages] タブをクリックします。
- Stageリストで Usage Planを変更する Stage名をクリックします。
- Stageリスト右側に表示された詳細情報画面で [Usage Plans] タブをクリックします。
- Usage Plansを確認し、必要に応じて変更します。
- Default Usage Plan : リクエスト処理量と、リクエスト処理制限を確認・設定。 [変更] ボタンをクリックして設定を変更可能。
- リクエスト処理量(Rate) : 1秒当たりのリクエスト数を設定
- リクエスト処理限度(Quota) : 日別、月別 API使用量を設定
- 使用量は、日/月の初めを基準にカウントされます。
- エンドポイントのレスポンスコードに応じて使用量をカウントします。
- [Usage Plan関連付け] / [関連付けの解除] : Usage Plans メニューで作成した Usage Planを関連付けまたは解除
- リスト: 当該 Stageに関連付けられた Usage Plan項目
- 検索: 検索する Usage Planの名前を入力した後、をクリックして検索
- ソート: リストのページごとに表示する Usage Plan数を設定
- Usage Plansに関する詳細は、Usage Plansをご参照ください。
- Default Usage Plan : リクエスト処理量と、リクエスト処理制限を確認・設定。 [変更] ボタンをクリックして設定を変更可能。
Documentの確認
現在 Stageにリリースされている API文書を確認できます。
API文書を確認する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの APIs 列の をクリックします。
- 詳細情報の APIs リストにある API名をクリックして当該 APIが選択された APIリスト画面に移動します。
- APIリストで対象 APIをクリックします。
- [Stages] タブをクリックします。
- Stageリストで API文書を確認する Stage名をクリックします。
- Stageリスト右側に表示された詳細情報画面で [Document] タブをクリックします。
- API文書内容を確認します。
- リリースされた APIの内容を Swagger UI形式で確認するには、 [プレビュー] ボタンをクリックします。
Canaryの有効化とテスト
変更された API明細を Stageにリリースする前に、Canary環境を作って運用環境でテストを実施できます。
Canaryを有効化する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの APIs 列の をクリックします。
- 詳細情報の APIs リストにある API名をクリックして当該 APIが選択された APIリスト画面に移動します。
- APIリストで対象 APIをクリックします。
- [Stages] タブをクリックします。
- Stageリストで、Canaryを有効化する Stageの名前をクリックして選択し、 [Canaryの有効化] ボタンをクリックします。
- Stageリストで、「Stage名+(Canary)」で Canaryが有効になります。
- Stageリストでその Canary(Stage名+(Canary))をクリックします。
- 右側画面に表示された詳細情報で、 [Settings]、 [Export]、 [Document] タブをクリックして情報を確認・設定します。
- [Settings] : Canary設定
- [Export] : Canaryにリリースされた APIを Swagger JSON 2.0、Open API JSON 3.0、Java SDK形式でダウンロード
- [Document] : Canaryにリリースされた API文書を確認。リリースされた APIの内容を Swagger UI形式で確認するには、 [プレビュー] ボタンをクリック。
Canary設定
有効化した Canaryを設定する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの APIs 列の をクリックします。
- 詳細情報の APIs リストにある API名をクリックして当該 APIが選択された APIリスト画面に移動します。
- APIリストで対象 APIをクリックします。
- [Stages] タブをクリックします。
- Stageリストで設定する Canary(Stage名+(Canary))をクリックします。
- 右側画面に表示された詳細情報で [Settings] タブをクリックします。
- 設定画面で設定を変更し、 [保存] ボタンをクリックします。
- Endpointドメイン : Canaryの Endpointドメインを設定
- Certificate名 : Client Certificates証明書を選択(証明書の有効期間は証明書の作成日から1年)
- 分配 : リクエストを Stageと Canaryに分配する方法を設定
- Percentage : Canaryリクエストの実行の割合を指定
- Condition : 設定したヘッダ(Header)・クエリ文字列(Query String)とリクエストが一致すれば、Canaryリクエストを実行
- APIキャッシュ : Stageの APIキャッシュを利用して Canary APIキャッシュを有効化。Stageの APIキャッシュが有効化されていない場合は使用不可
- TTL : キャッシュを維持する秒数(sec)を入力
- Throttling : 登録したメソッド別に1秒当たりのリクエスト数を制限してバックエンドサーバを保護
Canaryの昇格
テストを完了した Canaryを Stageにリリースできます。
Canaryを Stageにリリースする方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの APIs 列の をクリックします。
- 詳細情報の APIs リストにある API名をクリックして当該 APIが選択された APIリスト画面に移動します。
- APIリストで対象 APIをクリックします。
- [Stages] タブをクリックします。
- Stageリストで、リリースする Canary(Stage名+(Canary))をクリックして選択し、 [Canaryの昇格] ボタンをクリックします。
- Canaryの昇格ポップアップで内容を確認し、 [はい] ボタンをクリックします。
- Canaryの昇格を完了すると、Canaryは無効化状態に切り替わり、Stageリストから削除されます。
- リリース履歴を確認するには、Stage名をクリックし、右側に表示された [Deployment History] タブをクリックします。詳細は、リリース履歴の確認と管理をご参照ください。
Canaryの無効化
有効化した Canaryは無効化(削除)できます。
Canaryを無効化する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの APIs 列の をクリックします。
- 詳細情報の APIs リストにある API名をクリックして当該 APIが選択された APIリスト画面に移動します。
- APIリストで対象 APIをクリックします。
- [Stages] タブをクリックします。
- Stageリストで、無効化する Canary(Stage名+(Canary))をクリックして選択し、 [Canaryの無効化] ボタンをクリックします。
- Canaryの無効化ポップアップで内容を確認し、 [はい] ボタンをクリックします。
- Canaryの無効化を完了すると、Canaryが Stageリストから削除されます。
ゲートウェイレスポンスの定義
予め定義された API Gatewayレスポンス設定を変更できます。
レスポンスの確認と変更
API Gatewayのレスポンスを確認して変更する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの APIs 列の をクリックします。
- 詳細情報の APIs リストにある API名をクリックして当該 APIが選択された APIリスト画面に移動します。
- APIリストで対象 APIをクリックします。
- [Gateway Responses] タブをクリックします。
- レスポンスリストでレスポンスタイプをクリックして詳細情報を確認したり、変更します。
- 詳細情報 の領域
- ステータスコード : 現在定義されているレスポンスコード
- 基本設定 : レスポンスタイプが基本設定か否か
- レスポンスタイプに対するレスポンスコードを変更するには、 状態コード 項目の [変更] ボタンをクリックしてコード(100~599)を変更し、 [保存] ボタンをクリックします。変更をキャンセルするには、 [キャンセル] ボタンをクリックします。
- 変更事項が設定されると、 デフォルト設定 の項目が はい から いいえ に変更されます。
- レスポンスヘッダ の領域
- レスポンスヘッダを追加するには、ヘッダ名とヘッダの値(変数または static)を入力し、 [追加] ボタンをクリックします。
- レスポンスヘッダの名前は、どんな有効な文字列でも構いません。
- レスポンスヘッダの値は、有効なリクエストパラメータや単一引用符で囲んだ static値でも構いません。
- 追加したレスポンスヘッダを削除するには、当該レスポンスヘッダの [削除] ボタンをクリックし、レスポンスヘッダの削除ポップアップで [削除] ボタンをクリックします。
- レスポンスヘッダとレスポンスメッセージに使用できるコンテンツ変数は、コンテンツ変数をご参照ください。
- マッピングテンプレート 領域
- データを返すための本文マッピングテンプレートを指定できます。テンプレートは、Apache Velocity Template Language(VTL)の利用時に宣言されます。
- マッピングテンプレートを追加するには、 [追加] ボタンをクリックしてマッピングテンプレートの追加ポップアップでコンテンツタイプとマッピングテンプレート情報を入力した後、 [追加] ボタンをクリックします。
- マッピングテンプレートを変更するには、リストで変更するマッピングテンプレートをクリックして選択した後、 [変更] ボタンをクリックします。その後、マッピングテンプレート変更のポップアップでマッピングテンプレート情報を変更し、 [変更] ボタンをクリックします。
- マッピングテンプレートを削除するには、リストから削除するマッピングテンプレートをクリックして選択した後、 [削除] ボタンをクリックします。その後、マッピングテンプレート削除のポップアップで [削除] ボタンをクリックします。
- 変更事項をデフォルト値に再設定するには、リストで再設定するレスポンスタイプをクリックして選択し、 [再設定] ボタンをクリックします。その後に再設定のポップアップで内容を確認し、 [再設定] ボタンをクリックします。変更事項が設定されると、 デフォルト設定 の項目が いいえ から はい に変更されます。
- 詳細情報 の領域
コンテンツ変数
レスポンスヘッダとレスポンスメッセージには、以下のコンテンツ変数を使用できます。
コンテンツ変数 | 説明 |
---|---|
${context.productName} | Product名 |
${context.apiName} | API名 |
${context.httpMethod} | メソッド |
${context.error.message} | エラーメッセージ文字列 |
${context.error.messageString} | エラーメッセージ文字列、"$context.error.message" |
${context.error.responseType} | レスポンスタイプ |
${context.identity.accountId} | AccessKeyのアカウント ID(IAM認証を使用した場合) |
${context.identity.apiKey} | API Key(API Keyを使用する場合) |
${context.identity.sourceIp} | 呼び出し側の IPアドレス |
${context.identity.user} | ${context.identity.accountId}と同じ |
${context.identity.userAgent} | User Agent |
${context.path} | URLパス |
${context.protocol} | 呼び出しプロトコル(<예시>HTTP/1.1) |
${context.requestId} | リクエスト ID |
${context.requestTime} | 1970年1月1日00:00:00協定世界時(UTC)からの経過時間をミリ秒(Millisecond)で表した数字 |
${context.resourcePath} | リソースパス |
${context.methodCode} | エンドポイントのメソッド |
${context.methodName} | エンドポイントのメソッド |
${context.status} | レスポンスコード |
${context.stage} | Stage名 |
${method.request.path.PARAM_NAME} | リクエストのパス変数 |
${method.request.queryString.PARAM_NAME} | リクエストのクエリ文字列 |
${method.request.header.PARAM_NAME} | リクエストのヘッダ |
リクエストとレスポンスのボディモデルの定義
API明細で使用するためのボディモデルを定義できます。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの APIs 列の をクリックします。
- 詳細情報の APIs リストにある API名をクリックして当該 APIが選択された APIリスト画面に移動します。
- APIリストで、ボディモデルを定義する APIをクリックします。
- [Models] タブをクリックします。
- 必要に応じてモデルを新たに定義するか、変更・削除します。
- モデルを追加するには、 [追加] ボタンをクリックして Modelの追加ポップアップで情報を入力した後、 [追加] ボタンをクリックします。
- Model名 : 作成する Modelの名前を入力
- 説明 : Modelに対する説明を入力
- Schema : モデルを宣言する際は JSON schemaを使用
- [Schema] タブ: スキーマを作成
- [プレビュー] タブ: 作成したスキーマの動作を予め確認
- 作成のユースケース
{ "title": "Person", "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "age": { "description": "Age in years", "type": "integer", "minimum": 0 } }, "required": ["firstName", "lastName"] }
- モデルを追加するには、 [追加] ボタンをクリックして Modelの追加ポップアップで情報を入力した後、 [追加] ボタンをクリックします。
- モデルを変更するには、リストで変更するモデルをクリックして選択した後、 [変更] ボタンをクリックします。その後、Model変更のポップアップでモデル情報を変更し、 [変更] ボタンをクリックします。
- モデルを削除するには、リストから削除するモデルをクリックして選択した後、 [削除] ボタンをクリックします。その後に削除のポップアップで [削除] ボタンをクリックします。
APIご利用ガイドの Overview作成
APIご利用ガイドの Overviewを Markdown記法で作成できます。
APIご利用ガイドの Overviewを作成する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの APIs 列の をクリックします。
- 詳細情報の APIs リストにある API名をクリックして当該 APIが選択された APIリスト画面に移動します。
- APIリストでご利用ガイドを作成する APIをクリックします。
- [Overview] タブをクリックします。
- [変更] ボタンをクリックします。
- [入力] タブをクリックします。
- 入力欄に Markdown記法で Overviewを作成した後、 [保存] ボタンをクリックします。
- 作成した内容を予め確認するには、 [プレビュー] ボタンをクリックします。
- 作成した Overviewは Catalogで確認でき、Catalog画面でも変更できます。
APIのリリース
登録した APIをリリースする方法は、次の通りです。
APIをリリースするには、まず Stageを作成する必要があります。
Stageを作成する方法は、Stage作成をご参照ください。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストでリリースする APIがある Productの APIs 列の をクリックします。
- 詳細情報の APIs リストにある API名をクリックして当該 APIが選択された APIリスト画面に移動します。
- APIリストでリリースする APIをクリックします。
- [APIのリリース] ボタンをクリックします。
- APIのリリースポップアップで APIのリリース情報を設定し、 [追加] ボタンをクリックします。
- リリースする Stage : リリースする Stageを選択
- 説明 : リリースについての説明を入力
- APIリリース成功のポップアップで [確認] ボタンをクリックします。
- APIは、1つの Stageに複数回リリース可能で、リリース履歴(Deployment History)を通じて管理できます。
API呼び出し
リリースした APIを呼び出すことができます。API設定によって、呼び出す際に認証が必要です。
認証が不要な API呼び出し
認証が必要ない APIを呼び出す場合、以下の例をご参照ください。
curl -i -X GET https://uh7m0wgsis.apigw.ntruss.com/petStore/v1/pets
API Keyが必要な API呼び出し
API Keyが必要な APIを呼び出す場合、以下の内容と例をご参照ください。
ヘッダ | 説明 |
---|---|
x-ncp-apigw-api-key | API Gatewayで発行されたキー(Primary Keyまたは Secondary Key) API Keyが求められる場合にのみ追加 |
curl -i -X GET \
-H "x-ncp-apigw-api-key:cstWXuw4wqp1EfuqDwZeMz5fh0epaTykRRRuy5Ra" \
'https://uh7m0wgsis.apigw.ntruss.com/petStore/v1/pets'
IAM認証が必要な API呼び出し
IAM認証が必要な APIを呼び出す場合、以下の内容と例をご参照ください。
ヘッダ | 説明 |
---|---|
x-ncp-apigw-api-key | API Gatewayで発行されたキー(Primary Keyまたは Secondary Key) API Keyが求められる場合にのみ追加 |
x-ncp-apigw-timestamp | 1970年1月1日00:00:00協定世界時(UTC)からの経過時間をミリ秒(Millisecond)で表したもの API Gatewayサーバとの時間差が5分以上の場合は、無効なリクエストとみなす |
x-ncp-iam-access-key | ポータルまたは Sub Accountが発行した Access Key ID |
x-ncp-apigw-signature-v2 | Access Key IDとマッピングされる SecretKeyで暗号化した署名 HMAC暗号化アルゴリズムは HmacSHA256を使用 |
curl -i -X GET \
-H "x-ncp-apigw-timestamp:1505290625682" \
-H "x-ncp-apigw-api-key:cstWXuw4wqp1EfuqDwZeMz5fh0epaTykRRRuy5Ra" \
-H "x-ncp-iam-access-key:D78BB444D6D3C84CA38A" \
-H "x-ncp-apigw-signature-v2:WTPItrmMIfLUk/UyUIyoQbA/z5hq9o3G8eQMolUzTEo=" \
'https://uh7m0wgsis.apigw.ntruss.com/photos/puppy.jpg?query1=&query2'
Access Key ID、SecretKeyの確認
Access Key ID、SecretKeyは、ポータルのマイページ > アカウントの管理 > 認証キーの管理で確認できます。
Signature作成
リクエスト StringToSign GET /photos/puppy.jpg?query1=&query2
x-ncp-apigw-timestamp={timestamp}
x-ncp-apigw-api-key={apiKey}
x-ncp-iam-access-key={accesskey}
x-ncp-apigw-signature-v2={signature}GET /photos/puppy.jpg?query1=&query2
{timeStamp}
{accessKey}注意リクエストヘッダの x-ncp-apigw-timestampの値と StringToSignの timestampは必ず一致する必要があります。
参考- 署名に使用される URLには、ドメインが含まれません。
- 改行文字は \nを使用します。
リクエストに合わせて StringToSignを作成し、SecretKeyを HmacSHA256アルゴリズムに暗号化した後、Base64にエンコードします。この値を x-ncp-apigw-signature-v2
として使用します。
以下は、コードの種類別サンプルコードです。
Javaサンプルコード
public String makeSignature() { String space = " "; // one space String newLine = "\n"; // new line String method = "GET"; // method String url = "/photos/puppy.jpg?query1=&query2"; // url (include query string) String timestamp = "{timestamp}"; // current timestamp (epoch) String accessKey = "{accessKey}"; // access key id (from portal or sub account) String secretKey = "{secretKey}"; String message = new StringBuilder() .append(method) .append(space) .append(url) .append(newLine) .append(timestamp) .append(newLine) .append(accessKey) .toString(); SecretKeySpec signingKey = new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256"); Mac mac = Mac.getInstance("HmacSHA256"); mac.init(signingKey); byte[] rawHmac = mac.doFinal(message.getBytes("UTF-8")); String encodeBase64String = Base64.getEncoder(rawHmac); return encodeBase64String; }
Javascriptサンプルコード
/* https://code.google.com/archive/p/crypto-js/ https://storage.googleapis.com/google-code-archive-downloads/v2/code.google.com/crypto-js/CryptoJS%20v3.1.2.zip */ /* CryptoJS v3.1.2 code.google.com/p/crypto-js (c) 2009-2013 by Jeff Mott. All rights reserved. code.google.com/p/crypto-js/wiki/License */ function makeSignature() { var space = " "; // one space var newLine = "\n"; // new line var method = "GET"; // method var url = "/photos/puppy.jpg?query1=&query2"; // url (include query string) var timestamp = "{timestamp}"; // current timestamp (epoch) var accessKey = "{accessKey}"; // access key id (from portal or sub account) var secretKey = "{secretKey}"; // secret key (from portal or sub account) var hmac = CryptoJS.algo.HMAC.create(CryptoJS.algo.SHA256, secretKey); hmac.update(method); hmac.update(space); hmac.update(url); hmac.update(newLine); hmac.update(timestamp); hmac.update(newLine); hmac.update(accessKey); var hash = hmac.finalize(); return hash.toString(CryptoJS.enc.Base64); }
Python3サンプルコード
import hashlib import hmac import base64 import time def make_signature(): timestamp = int(time.time() * 1000) timestamp = str(timestamp) access_key = "{accessKey}" # access key id (from portal or sub account) secret_key = "{secretKey}" # secret key (from portal or sub account) secret_key = bytes(secret_key, 'UTF-8') method = "GET" uri = "/photos/puppy.jpg?query1=&query2" message = method + " " + uri + "\n" + timestamp + "\n" + access_key message = bytes(message, 'UTF-8') signingKey = base64.b64encode(hmac.new(secret_key, message, digestmod=hashlib.sha256).digest()) return signingKey
Bashサンプルコード
function makeSignature() { nl=$'\\n' TIMESTAMP=$(echo $(($(date +%s%N)/1000000))) ACCESSKEY="{accessKey}" # access key id (from portal or sub account) SECRETKEY="{secretKey}" # secret key (from portal or sub account) METHOD="GET" URI="/photos/puppy.jpg?query1=&query2" SIG="$METHOD"' '"$URI"${nl} SIG+="$TIMESTAMP"${nl} SIG+="$ACCESSKEY" SIGNATURE=$(echo -n -e "$SIG"|iconv -t utf8 |openssl dgst -sha256 -hmac $SECRETKEY -binary|openssl enc -base64) }
Objective-Cサンプルコード
#include <CommonCrypto/CommonDigest.h> #include <CommonCrypto/CommonHMAC.h> - (NSString*) makeSignature { NSString* space = @" "; NSString* newLine = @"\n"; NSString* method = @"GET"; NSString* url = @"/photos/puppy.jpg?query1=&query2"; NSString* timestamp = @"{timestamp}"; NSString* accessKey = @"{accessKey}"; NSString* secretKey = @"{secretKey}"; NSString* message = [[NSString alloc] init]; message = [message stringByAppendingString:method]; message = [message stringByAppendingString:space]; message = [message stringByAppendingString:url]; message = [message stringByAppendingString:newLine]; message = [message stringByAppendingString:timestamp]; message = [message stringByAppendingString:newLine]; message = [message stringByAppendingString:accessKey]; const char *cKey = [secretKey cStringUsingEncoding:NSASCIIStringEncoding]; const char *cData = [message StringUsingEncoding:NSASCIIStringEncoding]; unsigned char cHMAC[CC_SHA256_DIGEST_LENGTH]; CCHmac(kCCHmacAlgSHA256, cKey, strlen(cKey), cData, strlen(cData), cHMAC); NSData *hash = [[NSData alloc] initWithBytes:cHMAC length:sizeof(cHMAC)]; const uint8_t* input = (const uint8_t*)[hash bytes]; NSInteger length = [theData length]; static char table[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/="; NSMutableData* data = [NSMutableData dataWithLength:((length + 2) / 3) * 4]; uint8_t* output = (uint8_t*)data.mutableBytes; NSInteger i; for (i=0; i < length; i += 3) { NSInteger value = 0; NSInteger j; for (j = i; j < (i + 3); j++) { value <<= 8; if (j < length) { value |= (0xFF & input[j]); } } NSInteger theIndex = (i / 3) * 4; output[theIndex + 0] = table[(value >> 18) & 0x3F]; output[theIndex + 1] = table[(value >> 12) & 0x3F]; output[theIndex + 2] = (i + 1) < length ? table[(value >> 6) & 0x3F] : '='; output[theIndex + 3] = (i + 2) < length ? table[(value >> 0) & 0x3F] : '='; } return [[NSString alloc] initWithData:data encoding:NSASCIIStringEncoding]; }
C#サンプルコード
using System; using System.Text; using System.Security.Cryptography; class ApiGateway { static String MakeSignature() { String method = "GET"; String space = " "; String url = "/photos/puppy.jpg?query1=&query2"; String newLine = "\n"; String timestamp = "{timestamp}"; String accessKey = "{accessKey}"; String secretKey = "{secretKey}"; var message = new StringBuilder(); message.Append(method); message.Append(space); message.Append(url); message.Append(newLine); message.Append(timestamp); message.Append(newLine); message.Append(accessKey); string result = message.ToString(); String signature = string.Empty; byte[] byteSecretKey = Encoding.UTF8.GetBytes(secretKey); using (HMACSHA256 hmacSha256 = new HMACSHA256(byteSecretKey)) { Byte[] dataToHmac = System.Text.Encoding.UTF8.GetBytes(result); signature = Convert.ToBase64String(hmacSha256.ComputeHash(dataToHmac)); } return signature; } }
PHPサンプルコード
<?php function makeSignature() { $StringToSign = 'GET /photos/puppy.jpg?query1=&query2' . PHP_EOL . '{timestamp}' . PHP_EOL . '{accessKey}'; $secret_key = '{secretKey}'; $signature = base64_encode(hash_hmac('sha256', $StringToSign, $secret_key, true)); return $signature; } ?>
エラーコード
API呼び出し時に発生し得るエラーコードの種類と説明は、次の通りです。
HttpStatusCode | ErrorCode | ErrorMessage | 説明 |
---|---|---|---|
400 | 100 | Bad Request Exception | protocol(https)、encoding(UTF-8)などの requestエラー |
401 | 200 | Authentication Failed | 認証失敗 |
401 | 210 | Permission Denied | 権限なし |
404 | 300 | Not Found Exception | Not found |
429 | 400 | Quota Exceeded | Quota超過 |
429 | 410 | Throttle Limited | Rate超過 |
429 | 420 | Rate Limited | Rate超過 |
413 | 430 | Request Entity Too Large | リクエストエンティティサイズの超過 |
415 | 440 | Unsupported Media Type | サポートされていないメディアタイプ |
503 | 500 | Endpoint Error | エンドポイント接続エラー |
504 | 510 | Endpoint Timeout | エンドポイント接続時間の超過 |
500 | 900 | Unexpected Error | 例外処理されていないエラー |
エラーレスポンスの形式
APIの呼び出し時に発生し得るエラーレスポンスの形式は、次の通りです。
リクエスト Content-Typeが application/xmlの場合
<?xml version='1.0' encoding='UTF-8' ?> <Message> <error> <errorCode>210</errorCode> <message>Permission Denied</message> </error> </Message>
その他
{ "error":{ "errorCode":"210", "message":"Permission Denied" } }
文書管理
API文書には、次の3種類があります。各文書の内容は、当該ご利用ガイドをご参照ください。
- APIの Overview: APIご利用ガイドの概要
- Stageの Document: APIガイド
- Productの Catalog: 掲載された API文書の概要(Overview)とご利用ガイド(Document)のセット
Catalog確認
掲載された API文書の概要(Overview)とご利用ガイド(Document)を確認できます。概要の場合、内容を変更できます。
- Catalogを確認するには、まず APIを Stageにリリースした後、当該 Stageを掲載する必要があります。APIの掲載方法は、APIの掲載をご参照ください。
- 他のユーザーが掲載して公開した Catalogを参照し、サブスクリプションできます。詳細は、Published APIsご利用ガイドをご参照ください。
Catalogを確認する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで Catalogを確認する Productの Catalog 列の をクリックします。
- 当該 Productの APIリストで、Catalogを確認する APIの名前をクリックし、情報を確認します。
APIの掲載
開発した APIを、他のユーザーが APIガイドを参照して使用できるように掲載できます。
APIを掲載する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの 掲載 列の をクリックします。
- 当該 Productの Catalogリストで掲載する APIの名前をクリックし、 [掲載] ボタンをクリックします。
- 掲載成功のポップアップが表示されたら、 [確認] ボタンをクリックします。
Stageに API Keyを関連付けして管理
API Keys メニューで作成した API Keyを Stageに登録して、使用状況と API使用量を設定できます。
API Keyの関連付け
Stageに API Keyを関連付ける方法は、次の通りです。
Stageに API Keyを関連付けるために、まず API Keyを作成します。詳細は、API Keysご利用ガイドをご参照ください。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの API Keys 列の をクリックします。
- [マイ API Key追加] ボタンをクリックします。
- マイ API Keyの追加ポップアップで、関連付ける API Keyをクリックして選択し、 [追加] ボタンをクリックします。
- API Keyの名前を入力して をクリックすると必要な API Keyを速やかに検索できます。
- API Keyリスト画面で、Stageに関連付けられた API Keyが追加されたか確認します。
API Keyが関連付けられた後の API Keyリストについての説明は、次の通りです。
領域 | 説明 |
---|---|
① マイ API Key追加 | Stageに API Keyを関連付け |
② 状態変更 | APIに対する API Keyの使用状況を変更 |
③ Usage Plans | API Keyに対する Usage Planの変更 |
④ 検索ボックス | 検索条件を選択して検索キーワードを入力した後、をクリックして項目を検索 |
⑤ フィルタ | API Keyの使用状況に応じてリストをソート |
⑥ ソート | リストのページごとに表示する API Key数の設定 |
⑦ API Keyリスト | 当該 Stageに関連付けた API Keyの項目
|
API Keyの状態変更
APIに対する API Keyの使用状況を変更できます。
API Keyの使用状況を変更する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの API Keys 列の をクリックします。
- API Keyリスト画面で状態を変更する API Keyをクリックして選択した後、 [状態変更] ボタンをクリックします。
- 状態のポップアップで 状態 を選択して変更した後、 [保存] ボタンをクリックします。
- リクエスト : API Keyの承認をリクエストした状態
- 承認 : APIを呼び出すことができる状態
- 拒否 : 承認された API Keyが呼び出しを拒否した状態
- リクエスト拒否 : API Keyの承認リクエストを拒否した状態
- リクエスト遮断 : API Keyの承認リクエストを遮断した状態
API Keyの Usage Plan変更
API Keyの Usage Planを変更する方法は、次の通りです。
- NAVERクラウドプラットフォームコンソールで Services > Application Services > API Gateway メニューを順にクリックします。
- My Products メニューをクリックします。
- Productリストで対象 Productの API Keys 列の をクリックします。
- API Keyリスト画面で、Usage Planを変更する API Keyをクリックして選択した後、 [Usage Plans] ボタンをクリックします。
- Usage Plansリスト画面で対象 APIを選択した後、 [Usage Plan変更] ボタンをクリックします。
- API : API Keyが関連付けられた APIの名前
- Stage : API Keyが関連付けられた Stageの名前
- Usage Plan : Stageに設定されている Usage Planの名前
- リクエスト日時 : API Keyと Stageの関連付けをリクエストした日時
- 変更日時 : Usage Planの設定を変更した日時
- 日別呼び出し数/リクエスト処理限度 : 日別呼び出し数と Usage Planに設定された日別リクエスト処理限度値の表示
- 月別呼び出し数/リクエスト処理限度 : 月別呼び出し数と Usage Planに設定された月別リクエスト処理限度値の表示
- Usage Planの変更ポップアップで Usage Plan を選択して変更し、[保存] ボタンをクリックします。
- 基本 Usage Plan : Stageの [Usage Plans] タブの Default Usage Plan 項目で設定した API使用量(Stageの Usage Plan変更参照)
- Stageに関連付けられた Usage plan: Usage plans メニューで作成して当該 Stageの [Usage Plans] タブで関連付けた Usage planを表示。Usage Planの横の数字は、関連付けられた Stageの数
使用限度
説明 | 制限 |
---|---|
Product作成数 | 60 |
Product当たりに作成可能な API数 | 20 |
API keyの作成数 | 500 |
API当たりの Resource作成数 | 300 |
API当たりの Stage作成数 | 10 |
Usage Planの作成数 | 300 |
TTL設定 | 1~3600秒 |
TTL設定(Stream API) | キャッシュは不可 |
API処理時間 | 600秒 |
Endpoint API処理時間 | 30秒 |
Endpoint API処理時間(Stream API) | 300秒 |
リクエストボディ | 10 MB |
リクエストボディ(Stream API) | 100MB |