第2章 3scale における API トラフィック

本ガイドの手順を完了すると、API トラフィックを API キーで保護し、追跡し、3scale に実装された基本的な流量制御および管理機能で監視することができます。例として使用した架空の「Echo API」を、実際の API に置き換えてください。

以下の手順に従えば、3scale でご自分の API を公開して運用する操作は分かり易く簡単です。API トラフィックのフローを監視し、さらに流量を制御した開発者キーを発行することができます。

実稼働環境用の API がある場合には、既存 API ユーザーへのサービス障害を避けるために、まずステージング/非実稼働環境でこの手順を実施する必要があります。

2.1. 前提条件

このチュートリアルは、3scale SaaS アカウントを使用していること、および管理ポータルにアクセスできることを前提としています。

https://echo-api.3scale.net にホストされたシンプルなテスト API (Echo API) を使用して、以下に示す例を実行します。

API を呼び出す簡単なアプリケーション (例: Curious Echo) が必要です。例としては、コマンドラインコール、モバイルアプリ、またはリモートサーバーを呼び出すことのできる何らかのコード等のシンプルなアプリケーションが挙げられます。

Echo API diagram

2.2. 3scale への Echo API の接続

Echo API を 3scale に接続するには、以下に示す 3 つのシンプルな手順を実施する必要があります。

  1. ご自分の 3scale 管理ポータルにアクセスし、最初のプランおよびメトリクスならびに API キーを設定する。
  2. ステージング環境 (開発用途専用) において、API ゲートウェイを使用して API を 3scale に統合する。
  3. API エンドポイントを 3scale のメソッドおよびメトリクスにマッピングする。

2.2.1. API の定義と最初の API キーの作成

3scale 管理ポータル (http://YOURDOMAIN-admin.3scale.net) から、さまざまな設定機能にアクセスすることができます。ここでは、API をデプロイするのに必要な最低限の設定にフォーカスします。

  1. API の定義: メトリクスおよびメソッドを追加する。
  2. API の使用に適用する制御を設定する。
  3. Audience > Accounts > Listing の順に移動し、新たな開発者アカウントおよび API クレデンシャルを作成する。

2.2.1.1. API の定義: メトリクスおよびメソッドの追加

ここでは、メソッドおよびメトリクスを必要なだけ追加することができます。デフォルトでは、お使いのサービスのすべてのプランで使用することができます。

Create new method

メソッドおよびメトリクスの追加方法に関する詳細は、3scale での API の定義 に関するドキュメントを参照してください。

ここでのシンプルなテストでは、「Hits」にメソッドを 2 つだけ追加し、システム名を以下のように設定します。

  • gethello
  • getgoodbye
Hello world example

2.2.1.2. API の使用に対する制御の設定

メトリクス/メソッドを作成するのに加えて、それぞれのプランで API の使用メトリクスに制御を追加することもできます。この API の例に、新たなアプリケーションプランを作成します。[your_API_name] > Overview > Create Application Plan の順に移動してください。

Create application plan

表示されるフォームで、希望の名前 (例: HelloEchoTest) およびシステム名を指定します。続いて Create Application Plan ボタンをクリックします。

Echo API application plan

上記の手順を実施すると、アプリケーションプランのリストが表示されるはずです。プラン「HelloEchoTest」をクリックし、メトリクスおよびメソッドの制御を作成します。前項の手順で定義したすべてのメトリクスおよびメソッドが表示されているはずです。いずれかのメトリクスまたはメソッドの「Limits」アイコンをクリックします。Hits メトリクスに制御を追加すると、Hits の全メソッドにルールが適用されます。メソッドに制御を追加した場合には、ルールはそのメソッドにしか適用されません。別途、さまざまな制御を設定した異なるプランを作成することができます。

Test plan limits

制御により、このプランのアプリケーションが呼び出すことのできる 1 分/時間/日あたりの API コール数が制限されます。

2.2.1.3. 新たな開発者アカウントおよび API クレデンシャルの作成

Audience > Accounts > Listing の順に移動し、Create ボタンをクリックします。

Create new account

API にアクセスする新しい開発者の情報を入力します。

Input information

Create をクリックしたら、リストから新しいアカウントを選択してホームページに移動します。

Accounts エリアには、API の使用をサインアップしたすべての企業および開発者のリストが表示されます。新しい企業は、管理ポータルから、API から、またはデベロッパーポータルのセルフサービスサインアップにより追加することができます。

新たな開発者アカウントを作成すると、そのアカウントに新しいアプリケーションも作成されます。

See application name

それぞれのアプリケーションは、API にアクセスするための固有のキーを持ちます。そのキーを知るには、アプリケーション名をクリックして API Credentials セクションを確認します。

API keys and change plans

これらが、Echo API を呼び出すために「Curious Echo」アプリが使用するキーです。最後のステップとして、アプリケーションの詳細ページの右側の Change Plan のドロップダウンを使用し (上記のスクリーンショットを参照)、前のステップで作成して名前を設定したプラン (この例では「Echo Test」) を選択して変更を確認します。これにより、新しいプランがこのアプリケーションに適用されます。

これで、最初のアプリケーションの管理システムの設定が完了しました。

2.2.2. ステージング環境での API ゲートウェイを使用したインテグレーション

ご自分の 3scale アカウントにサインインしたら、[your_API_name] > Integration > Configuration の順に移動します。

API Gateway staging configuration

ステージング環境での API バックエンドのアドレスを設定します。これは、API を実行中のサーバーのアドレスです。次に、API の有効なリソースパスを入力することができます。このパスは、ステージング環境での API ゲートウェイを検証するのに使用されます。その後、Update & test in Staging Environment をクリックします。すべての設定が適切であれば、ステージング領域に緑色の縦線が表示され、接続を確認するために行った完全なテストコールが表示されます。以下に例を示します。

curl "https://api-xxx.staging.apicast.io/hello?user_key=USER_KEY"

USER_KEY は、3scale アカウントへの初回ログイン時に作成されたいずれかのサンプルアプリケーションのキーです。その手順を実施していない場合には、開発者アカウントを作成し、そのアカウント内にアプリケーションを作成します。

アプリケーションのクレデンシャルを使用せずに統合した API の呼び出しを試み、次に無効なクレデンシャルを使用してみます。認証されたら、定義した流量制御の範囲内および範囲外で、API コールを送信します。

2.2.3. 特定メソッドのトラフィックの把握

デフォルトでは、非常にシンプルなマッピングルールから作業を開始します。

Mapping Rules

このルールは、「/」で始まるすべての GET リクエストが、メトリクス hits の値を 1 つ増やすという意味です。このルールは一般的すぎるので、通常は削除されます。マッピングルールの管理方法について詳しく知るには、ドキュメントの関連ページ を参照してください。

マッピングルールでは、API に対するリクエストに応じてどのメトリクス (およびメソッド) を報告するかを定義します。以下の例は、Echo API のルールです。

proxy mapping Echo API

API エンドポイントを、以前のアプリケーションプランのセクションで定義したメソッドとマッチングさせます。

  • /hello
  • /goodbye

これで、マッピングされたメソッドに対してトラフィックのテストを繰り返し、管理ポータルの Analytics セクションでそのトラフィックを確認することができます。

2.3. 結果

これで、ご自分の API が 3scale に接続されました。API 管理機能を適用して、API のトラフィックを管理したり追跡したりできるようになりました。

2.4. 次のステップ

ステージング環境で 3scale とのインテグレーションをテストしたので、実稼働環境にデプロイするオプションを選択することができます。APIcast ゲートウェイに関する詳しい情報は、以下のドキュメントを参照してください。

2.5. 終わりに

本ガイドの例では、簡素化のために管理ポータルから新しい API クレデンシャルを生成しています。デベロッパーポータルを設定したら、新たな開発者はこれを使用して自動的にアカウントを作成し、クレデンシャルを受け取ることができます。

2.6. ヘルプ

API の設定でトラブルが生じたら、トラブルシューティングのチュートリアル を確認してください。