第31章 API アクセスを管理および最適化するための 3scale API 解析の実装

3scale API 解析を実装して API アクセスを管理および最適化することで、時間と共に変化する使用状況の傾向などを追跡することができます。トラフィックを管理し、ピーク時に対応し、API に最も多くのリクエストを送信しているユーザーを特定するためには、ご自分の API がどのように使用されているかを知ることが重要なステップとなります。

3scale では、以下のレベルで定義可能なメソッドおよびメトリクスに関する API 解析を収集します。

  • プロダクト: Hits は、API へのトラフィックを追跡する組み込みのメトリクスです。追加のメトリクスを作成して、解析を取得する API にメソッドを指定することができます。
  • バックエンド: 3scale では、メソッドおよびメトリクスが API バックエンドに登録されます。これにより、メソッドおよびメトリクスがバックエンドを使用する各プロダクトに属するかのように機能します。バックエンドレベルのメトリクスの制限および課金ルールを、プロダクトレベルで定義されるアプリケーションプランに設定することができます。
  • アプリケーション: 3scale で作成した各アプリケーションの解析レポートを取得することができます。

前提条件

  • スタートガイドの手順 が完了していること。

    『スタートガイド』を使用して、既存の 3scale コードプラグインのいずれかを使用してインテグレーションを実施します。

  • あるいは、他のインテグレーション方法の類似作業フローに従います。利用可能なインテグレーションオプションの詳細については、『API ゲートウェイの管理』の「APIcast の運用」の章を参照してください。

31.1. API の使用状況を把握する 3scale API メトリクスおよびメソッド

3scale は、API プロダクトの統計値に関して無限にスケーラブルなデータリポジトリーとして機能します。メトリクスおよびメソッドを使用して API プロダクトの統計値を取得することで、API へのアクセスを最適に管理するために必要な情報を取得することができます。以下に例を示します。

  • Hits/transactions: API プロダクトへの呼び出しの数。Hits は、すべての API にデフォルトでメトリクスとして含まれています。Hits は、API プロダクトへの全呼び出し数とすることも、API プロダクトの個々のメソッドにブレークダウンすることもできます。
  • Data transfer: API プロダクトを通じてアップロードおよびダウンロードされたデータ量 (MB/GB 単位)
  • CPU hours: API プロダクトへの呼び出しに関連する処理時間 (またはその他の内部リソース)
  • Results returned: 返されているレコードまたはデータオブジェクト数のカウント
  • Disk storage: アカウントにより使用されているディスクストレージの合計

ご自分の API プロダクトに関連するより多くのメトリクスを追跡することができます。時間の経過と共に増加する数量であれば、3scale では任意の数のメトリクスおよびメソッドを追加することができます。

使用するメトリクスを選択したら、「プロダクトおよびバックエンドへのメトリクスの追加」に記載の手順に従って、管理ポータルにそれらのメトリクスを登録します。

選択したプロダクトまたはバックエンドにメトリクスおよびメソッドを追加することができます。それらに分かりやすい名前およびシステム名を設定します (3scale はこれらの名前をプラグイン設定で使用します)。メソッドおよびメトリクスの作成に関する詳細は、「使用状況の詳細を把握するためのメソッドの指定およびメトリクスの追加」を参照してください。

31.2. API メトリクスを取得するための 3scale プラグインの設定

3scale システムで追跡するメトリクスの名前を設定したら、それらのメトリクスを報告するようにプラグインを設定する必要があります。この操作の詳細な手順は、使用しているプラグインまたはインテグレーション手段によって異なります。デフォルトでは、プラグインは Hits (API トランザクション) メトリクスしか報告しません。

前提条件

  • プロダクトまたはバックエンドにメトリクスがすでに設定されている必要があります。

手順

  1. 着信 API コールで決められたとおりに、適切なメトリクス/メソッド名をプラグインに渡します。

    必要なメトリクス/メソッドの値および増分は、プラグインが公開する承認またはレポートメソッドの引数です。

  2. メトリクスで System name メソッドを使用して、特定の API メソッドのトラフィックを報告します。

    これにより、報告されたメソッドと Hits メトリクスの両方のカウンターに、自動的に増分が加算されます。

  3. 管理ポータルの Account Settings > Integrate → 3scale API Docs で、3scale Service Management API を使用してトラフィックを報告します。

さまざまなエンドポイントに関する補足情報については、管理ポータルの Account Settings > Integrate → 3scale API Docs から利用できる3scale API Documentation を参照してください。

31.3. 3scale API バックエンドの解析値の表示

バックエンドとして設定された特定の API のトラフィックデータを表示することができます。Traffic ページにエンドポイントへのヒットカウントが表示されます。

前提条件

手順

  1. [Your_backend_name] > Analytics の順に移動します。
  2. レポートの期間を選択します。過去 24 時間、7 日間、30 日間、または 12 カ月間の表示を選択することができます。また、期間を指定することもできます。
  3. (オプション) Hits 以外の解析値 (メソッドまたは他の最上位メトリクスのいずれか) を選択します。

    • 結果がチャートに表示されます。報告するトラフィックがない場合は、There is no data available for the selected period というメッセージが表示されます。
  4. Download CSV リンクをクリックして、データを CSV ファイルにダウンロードします。

31.4. API メトリクスを取得するためのプラグイン設定を確認するためのテストリクエストの送信

API と 3scale 間の接続を確立します。これにより、トラフィックを API プロダクトに送信し、それが API Analytics ダッシュボードに登録されるのを確認することができます。

前提条件

  • 3scale の開発者アカウント
  • 3scale アプリケーションおび API クレデンシャル

手順

  1. Audience > Applications > Listing の順に移動し、既存アプリケーションのリストを表示します。
  2. 名前をクリックしてアプリケーションを選択します。
  3. 選択したアプリケーションの API クレデンシャル を確認します。クレデンシャルは選択した認証タイプによって異なり、ユーザーキー (API キー)、アプリケーション ID とアプリケーションキー、またはクライアント ID とクライアントシークレットのいずれかです。

    利用可能な認証モードの詳細については、「認証パターン」を参照してください。

    図31.1 API クレデンシャル

    API credentials
  4. これらのキーを使用して、通常の方法で API を呼び出します。たとえば、cURL を使用してコマンドラインから呼び出すか、GET メソッドを使用して API エンドポイントのブラウザーから呼び出します。呼び出しの詳細は、実際の API プロダクトのメソッド構造により異なります。これらの呼び出しからのトラフィックが、API プロダクトの Analytics セクションに表示されます。

次のステップ

デフォルトでは、API プロバイダーは管理ポータルを通じて、アプリケーションを作成した開発者はデベロッパーポータルを通じて、それぞれ使用状況の統計を表示することができます。それぞれの開発者は、自分自身のアプリケーションの使用状況の統計しか表示することはできません。デベロッパーポータルから解析ビューを非表示にして、表示できるユーザーをさらに制御することができます。デベロッパーポータルのカスタマイズに関する詳細は、『デベロッパーポータルの作成』を参照してください。

Analytics セクションの使用状況グラフ以外にも、Analytics API を使用して解析データにアクセスすることができます。3scale Analytics API により、API プロダクトのすべての解析データを、XML または JSON いずれかの形式で柔軟に抽出することができます。

31.5. 3scale API の解析が表示されない場合のトラブルシューティングテクニック

トラフィックが [Your_product_name] > Analytics > Traffic の使用状況チャートに表示されない場合は、以下のチェックを行います。

  • 承認/レポート呼び出しは正常に応答しているか?

    すべてのプラグインは 3scale Service Management API を呼び出しますが、この API には事前に定義されたレスポンスコードがあります。有効なキーによる承認呼び出しは、HTTP コード 200 と共にレスポンスを返します。レポート呼び出しは、コード 202 と共に応答します。

  • インテグレーションエラーコンソールにエラーは表示されていないか?

    3scale によって検出されたインテグレーションエラーのログは、[your_product_name] > Analytics > Integration Errors で確認することができます。

  • 正しいメトリクスおよびメソッド名が使用されているか?

    異常が発生する最も一般的な原因は、レポート呼び出しに渡されるメソッドおよびメトリクス名が、ご自分の管理ポータルの API 設定で作成される名前に対応していないことです。それぞれのメトリクス/メソッドについて、正しい システム名 が使用されていることを確認してください。

  • マッピングルールは正しくメトリクスにマッピングされているか?

    マッピングルールが正しくメトリクスにマッピングされていないと、データが Analytics に表示されない場合があります。API プロダクトおよび API バックエンドの両方について、マッピングルールが正しくメトリクスにマッピングされていることを確認します。

    • プロダクト: [Your_product_name] > Integration > Methods & Metrics の順に移動します。
    • バックエンド: [Your_backend_name] > Methods & Metrics の順に移動します。