2.3. ベーシックパスの手順

ベーシックパスの手順を、個別にエンドツーエンドで実施することができます。あるいは、必要に応じてこのパスの手順の一部を抜き出して実施することもできます。それぞれのパスは互いに独立していますが、プロトタイプ、ベーシック、および アドバンスト パスは、順に積み上げて高度な設定を行うことが可能です。

2.3.1. API の保護

実稼働環境向けの完全な実装のためには、プロダクトの設定および 3scale とのインテグレーション方法に関して、基本方針を決定する必要があります。

プロダクトトラフィックの認証モードには、いくつかの選択肢があります。利用可能なオプションに関するガイド を確認し、設定を行ってください。

重要

認証の設定を行ったら、認証モードを切り替えないでください。この操作により、既存のクレデンシャルが無効になる可能性があるためです。

API トラフィックマネージャーレイヤーのデプロイメントにも、いくつかのオプションがあります。設定の容易さとパフォーマンスのバランスから、3scale ユーザーの間では APIcast (NGINX ベースの API ゲートウェイ) が好まれています。Hosted APIcast を使用すればすぐに運用を開始することができますが、ボリュームの制約やレイテンシー増加の問題が生じます。一方、APIcast を専用のサーバーにデプロイすれば、最高のパフォーマンスが得られ、トラフィックボリュームの制約から完全に解放されます。

Hosted APIcast

  1. 管理ポータルへの初回ログイン後に、導入ウィザードの手順に従います。
  2. 実稼働環境に適したバージョンが得られるまで、アクセスポリシーの調整などのプロダクト設定を繰り返します。
  3. APIcast 設定を実稼働環境用ゲートウェイにプロモートします。

Self-managed APIcast

  1. OpenShift サーバー上に、API ゲートウェイのテスト用システムを設定します。
  2. 実稼働環境に適したバージョンが得られるまで、アクセスポリシーの調整などの API 設定を繰り返します。
  3. APIcast 設定を実稼働環境用ゲートウェイにプロモートします。
  4. APIcast ポリシー には、API のアクセスポリシーを設定する際の概念が記載されています。

2.3.2. アプリケーションプランによる API アクセスポリシーの設定

「API の保護」の手順を実施すると、認証された呼び出しだけがご自分のプロダクトにアクセスできるようになります。本セクションでは、ポリシーを適用して流量制御を変更します。

3scale では、アプリケーション により API プロダクトにアクセスするためのクレデンシャルが定義されます。アプリケーションには必ず 1 つ アプリケーションプラン が関連付けられ、アクセスポリシーが定義されます。アプリケーションは、開発者アカウント 内に保管されます。3scale の Basic プランでは、1 つのアプリケーションしか許可されません。より高度なプランでは、アカウントごとに複数のアプリケーションが許可されます。

プロトタイプ では、プロダクトの総ヒット数に基づいてアクセスを制御することしかできません。カスタムメソッドおよびメトリクスを使用して初めて、3scale の柔軟性を体感することができます。カスタムメソッドおよびメトリクスを使用することで、アプリケーションプランおよびプロダクトの解析をより高度化することができます。詳細は、解析に関するガイド を参照してください。

重要
  • API の構造と 3scale のメソッドまたはメトリクスとの間のマッピングは論理的です。整合性のとれたルールを定義すれば、3scale からプロダクトの使用状況に関するレポートを受け取ることができます。詳細さのレベルを決める必要があります。一般的には、5 - 20 メソッド/メトリクスを目標とする必要があります。
  • 3scale に報告される値は、増加するだけです。絶対値を設定したりカウンターを減らしたりすることはできません。
  • 新たなメソッドまたはメトリクスを 3scale に追加したら、API ゲートウェイまたはコードプラグインなどのインテグレーションポイントに新しいシステム名を追加することが重要です。
  • 実行時に、再デプロイせずに流量制御などに変更を加えることができます。

Echo API プロダクトのアプリケーションプランにポリシーを追加するには、以下の例に示す手順を実施します。

  1. 操作対象のプロダクトを選択します。
  2. Application Plans セクションで Basic を選択し、3scale へのサインアップまたはインスタンスのデプロイ後に自動的に生成されたプランのいずれかを編集します。
  3. Hits に流量制御が設定されている場合には、その設定を削除します。
  4. プランの Hits メトリックに 新規メソッド を追加し、システム名を test に設定します。
  5. test メソッドの流量制御を 1 時間あたり 5 回に設定します。
  6. 2 つの 新規メトリクス を追加し、システム名を v1 および v2 に設定します。
  7. v2 メトリックの Enabled 列をクリックし、アクセスを無効にします。これは、流量制御をゼロに設定するのと同じ効果を持ちます。

APIcast のデプロイメント

  1. [Your_product_name] > Integration > Configuration の順に移動します。

  2. MAPPING RULES セクションを展開し、以下のマッピングを追加します。

    マッピングルール
    注記

    /のデフォルトのマッピングは削除されています。このデフォルトマッピングを使用すると、ヒット数が二重にカウントされます。

コードプラグインのデプロイメント

  1. 3scale の承認およびレポート呼び出しにカスタムメソッドおよびメトリクスの使用状況を追加するには、プラグインライブラリーの手順および例に従ってください。
  2. URL 構造からカスタムメソッド test へのマッピングを確認します。
  3. URL からカスタムメトリクス v1 および v2 へのマッピングを確認します。

  4. 3scale の Basic プランに関連付けられたアプリケーションのクレデンシャルを使用して、呼び出しをテストします。

    • 呼び出しは許可されます。 

      curl "https://api-2445581407825.staging.apicast.io:443/v1/test?user_key=287d64924e6120d215b1000ac07c063b"

      5 回目以降は、呼び出しが拒否されます。これは、test メソッドに設定した制限のためです。

    • 3scale の Basic プランでは v2 は許可されないので、呼び出しは拒否されます。 

      curl "https://api-2445581407825.staging.apicast.io:443/v2/test?user_key=287d64924e6120d215b1000ac07c063b"

    • missing に設定されたマッピングルールがないので、呼び出しは拒否されます。 

      curl "https://api-2445581407825.staging.apicast.io:443/missing?user_key=287d64924e6120d215b1000ac07c063b"

    • プラグインのマッピングの実装状態によっては、これらの呼び出しは NGINX に対して許可されます。以下の呼び出しで 404 not found のレスポンスが返されるかどうかは、お使いのアプリケーションによります。これを避けるには、マッピングを調整してください。 

      curl "https://api-2445581407825.staging.apicast.io:443/noversion/test?user_key=287d64924e6120d215b1000ac07c063b"

この基本概念により、プロダクトレベルおよびバックエンドレベルの両方で、柔軟に API レイヤーを定義することができます。カスタムメソッドおよびメトリクスに何を使うかについて、早期に決定しておく必要があります。システム名に変更を加えた場合には、ベーシックパスの「API の保護」で説明したように、必ず変更を再デプロイします。

2.3.3. デベロッパーポータルを通じた開発者の参加

デベロッパーポータルの 作成 およびデベロッパーポータルを使用した API の提供 については、関連のドキュメントを参照してください。コンテンツを Textile または Markdown で記述することを検討してください。オプションとして考慮すべき項目を以下に示します。