第32章 組み込み機能を超える 3scale API 分析値のエクスポート

デフォルトの機能では提供されない情報を取得できるように、組み込まれた 3scale 分析の機能を拡張するスクリプトを作成します。

Account Management API および Analytics API を使用すると (Enterprise のみ)、必要な情報を希望の形式で取得するスクリプトを作成することができます。本項のユースケースを使用して、必要なデータを 3scale から取得する独自のシナリオに役立てることができます。

カスタムスクリプトが重要な理由

3scale では、API Dashboard で利用可能な機能を継続的に改善しています。しかし、お客様が当社の開発プランに先立ち、まだサポートされていない非常に特殊な機能を必要とする場合があります。

API 管理のニーズを満たすために、3scale 管理ポータルはすべてのデータにアクセスするのに必要なツールを提供します。スクリプトの作成にはリソースが必要ですが、カスタマイズしたスクリプトでは、さまざまなユースケースを実装するための完全な柔軟性と制御性が得られます。

32.1. 3scale を使用してアプリケーションの使用状況に関するデータを抽出する例

あるお客様は、毎週、数千人もの新規開発者を受け入れていました。3scale では必要な作業 (キーのプロビジョニング、サインアップワークフロー、電子メールによる連絡など) が自動化されているため、このお客様は受け入れプロセスにある程度対応することができていました。しかし、お客様にとって非常に重要だが、3scale では実施できないことがありました。

お客様は多数の開発者を受け入れていたため、運用およびマーケティングチームが新規開発者とより効果的に交流できるように、API の使用状況に応じて新規開発者を分類するためのシンプルな手段が必要でした。このような機能は、少なくとも求められるレベルの詳細さでは、3scale で提供される組み込み解析ツールではまだ利用することができませんでした。しかし、すべてのデータにはシステムからアクセスすることができたので、3scale の Account API および Analytics API を使用してそのデータを抽出することができました。

例: お客様の要求

お客様は、過去 10 日間に無料の評価版プランにサインアップした新規開発者の数を知り、それをいくつかのグループに分けたいと考えました。

まず、サインアップはしたがお客様の API を全く使用しなかった開発者の数を知りたいと考えました。

次に、API を使用した開発者を以下の 2 つのグループに分けたいと考えました。

  • ある期間 (初めの 5 日間など) API を使用した後、使用を止めた開発者。これらの開発者は、使ってはみたがアクティブではなくなったグループです。
  • API を継続的に使用している開発者。このグループについては、使用率の増加 (または減少) を知りたいと考えました。

この情報は、3scale の組み込み解析機能で利用可能です。問題は、集約データとして表示するビューがないことで、これは非常に面倒な状況です。

32.2. カスタムの手順による 3scale アプリケーションの解析値の抽出

アプリケーションの解析値を抽出するには、ActiveDocs の使用から作業を始めます。3scale ActiveDocs は、管理ポータルの Account Settings > Integrate > 3scale API Docs から利用可能です。3scale の API は、すべて ActiveDocs として利用可能です。したがって、ブラウザーから使用することができます。これにより、ニーズに最適なリクエストを探し、リクエスト (curl に類似) を取得し、レスポンスを得ることができます。ActiveDocs の例を以下の図に示します。

DIY Analytics

これは、スクリプトが解析を抽出するすべてのアプリケーションを取得する API リクエストの ActiveDocs です。

  • ActiveDocs の調査を完了したら、任意のスクリプト言語でリクエストを指定します。この例では Ruby を使用しています。
  • 希望の処理を実行するスクリプトが書き上がるまで、この作業を繰り返します。解析機能の拡張を例に取ると、ここから スクリプトを確認することができます。これをご自分のアカウントで試すことができます。

ActiveDocs により、API のできることを素早く理解することができます。後は、実行したいタスクに必要な 3 つか 4 つのリクエストを探し、スクリプトを 1 つにまとめます。

以下の手順は、例のお客様が希望するカスタム解析機能を実現するステップを示しています。

手順

  1. 全アプリケーションのリストを取得する。この操作にはページネーションが必要です。

    def api_call_applications_list(domain, provider_key)
      done = false
      res = Array.new
      page = 1
    
          while !done
        url = "https://#{domain}/admin/api/applications.xml?provider_key=#{provider_key}&page=#{page}&per_page=100"
        page += 1
        response = RestClient.get url
        raise Exception.new("Wrong response code (#{response.code}) in request #{url}") if response.code!=200
        document = Nokogiri::XML(response.to_str)    done = document.xpath("applications/@current_page").text == document.xpath("applications/@total_pages").text
        document.xpath("//application").each do |item|
          app = Hash.new
          app["created_at"] = DateTime.parse(item.xpath("created_at").text)
          app["plan_name"] = item.xpath("plan/name").text
          app["service_id"] = item.xpath("plan/service_id").text
          app["account_id"] = item.xpath("user_account_id").text
          app["id"] = item.xpath("id").text
          res << app
        end
      end
      return res
    end
  2. 条件を満たしていないアプリケーションを除外する (「評価版」のプランで、かつ 10 日前以降のものに絞り込む)。

    def filter_applications(domain, provider_key, plan_name, num_of_days)
      res = api_call_applications_list(domain, provider_key)
      res.each do |item|
        res.delete(item) if item["plan_name"] != plan_name
        res.delete(item) if item["created_at"] > (DateTime.now - num_of_days)
      end
      return res
    end
  3. 条件を満たすそれぞれのアプリケーションについて、その使用状況 (過去 10 日間のアプリケーションのヒットカウント) を取得する。

    def api_call_application_usage(domain, provider_key, application_id, metric, from, to, granularity)
      url = "https://#{domain}/stats/applications/#{application_id}/usage.xml?provider_key=#{provider_key}&metric_name=#{metric}&since=#{from}&until=#{to}&granularity=#{granularity}"
      response = RestClient.get url
      raise Exception.new("Wrong response code (#{response.code}) in request #{url}") if response.code!=200
      document = Nokogiri::XML(response.to_str)
      return document.xpath("//usage/data/values").text.split(",")
    end
  4. 開発者の情報はアカウントオブジェクトに保存されるため、アプリケーションをアカウントに紐付けする。

    def api_call_account_read(domain, provider_key, account_id)
      url = "https://#{domain}/admin/api/accounts/#{account_id}.xml?provider_key=#{provider_key}"
      response = RestClient.get url
      raise Exception.new("Wrong response code (#{response.code}) in request #{url}") if response.code!=200
      document = Nokogiri::XML(response.to_str)
      account = Hash.new
      account["email"] = document.xpath("//users/user/email").text
      account["name"] = document.xpath("//users/user/first_name").text + " " + document.xpath("//users/user/last_name").text
      return account
    end
  5. すべてを 1 つにまとめてスクリプトを完了する。このスクリプトで、3scale に組み込まれた解析機能ではまだ利用できなかった情報を取得することができます。完成したスクリプト を参照してください。