カスタム分析を使用して API メッセージ コンテンツを分析する

Edge API Analytics は、すべての API リクエストおよびレスポンスからさまざまな統計情報を収集して分析します。この情報は自動的に収集されるため、Edge UI でまたは指標 API を使用して表示できます。これらの統計情報の詳細については、指標とディメンションをご覧ください。

API プロキシ、アプリ、プロダクト、またはデベロッパーに固有のカスタム分析データを収集することもできます。たとえば、クエリ パラメータ、リクエスト ヘッダー、リクエスト本文とレスポンス本文、または API で定義した変数からデータを収集することもできます。

このトピックでは、StatisticsCollector ポリシーを使用して、API リクエスト / レスポンスからカスタム分析データを抽出し、そのデータを Edge API Analytics に入力する方法を示します。その後で、Edge UI のレポートでまたは Edge API を使用して、分析データを表示する方法を示します。

Google Book API について

このトピックでは、API プロキシ リクエストから Google Books API にカスタム分析データをキャプチャする方法について説明します。Google Books API を使用すると、タイトル、主題、著者、またはその他の特性で書籍を検索できます。

たとえば、書籍のタイトルで検索を実行するように /volumes エンドポイントにリクエストを発行します。書籍のタイトルを含む Books API に単一のクエリ パラメータを渡します。

curl https://www.googleapis.com/books/v1/volumes?q=davinci%20code

この呼び出しは、検索条件に一致する項目の JSON 配列を返します。レスポンスの最初の配列要素を以下に示します（簡単にするために一部のコンテンツが省略されているので注意してください）。

{
 "kind": "books#volumes",
 "totalItems": 1799,
 "items": [
  {
   "kind": "books#volume",
   "id": "ohZ1wcYifLsC",
   "etag": "4rzIsMdBMYM",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/ohZ1wcYifLsC",
   "volumeInfo": {
    "title": "The Da Vinci Code",
    "subtitle": "Featuring Robert Langdon",
    "authors": [
     "Dan Brown"
    ],
    "publisher": "Anchor",
    "publishedDate": "2003-03-18",
    "description": "MORE THAN 80 MILLION COPIES SOLD ....",
    "industryIdentifiers": [
     {
      "type": "ISBN_10",
      "identifier": "0385504217"
     },
     {
      "type": "ISBN_13",
      "identifier": "9780385504218"
     }
    ],
    "readingModes": {
     "text": true,
     "image": true
    },
    "pageCount": 400,
    "printType": "BOOK",
    "categories": [
     "Fiction"
    ],
    "averageRating": 4.0,
    "ratingsCount": 710,
    "maturityRating": "NOT_MATURE",
    "allowAnonLogging": true,
    "contentVersion": "0.18.13.0.preview.3",
    "panelizationSummary": {
     "containsEpubBubbles": false,
     "containsImageBubbles": false
    },
...
   "accessInfo": {
    "country": "US",
    "viewability": "PARTIAL",
    "embeddable": true,
    "publicDomain": false,
    "textToSpeechPermission": "ALLOWED_FOR_ACCESSIBILITY",
    "epub": {
     "isAvailable": true,
     "acsTokenLink": "link"
    },
    "pdf": {
     "isAvailable": true,
     "acsTokenLink": "link"
    },
...
   }
  }

レスポンスでは、次の領域が強調表示されています。

  • 検索結果の数
  • 平均書籍評価
  • 評価の数
  • 書籍の PDF バージョンの入手可能性

以降のセクションでは、レスポンスのこれらの領域に関する統計情報と、検索条件を含むクエリ パラメータ q に関する統計情報を収集する方法について説明します。

Google Book API 用の API プロキシを作成する

Google Book API に関する統計を収集する前に、それを呼び出す Edge API プロキシを作成する必要があります。その後、作成した API プロキシを呼び出して、Google Book API にリクエストを発行します。

API プロキシを作成するためのチュートリアルのステップ 2: API プロキシを作成するに、https://mocktarget.apigee.net API を呼び出すプロキシを作成する方法が記載されています。ただし、このチュートリアルで説明されているプロキシに、それを呼び出すための API キーは必要ありません。

同じ手順を使用して、Google Book API の /volumes エンドポイント用の API プロキシを作成します。手順のステップ 5 では、API プロキシを作成するときに、Google Books API を参照するための次のプロパティを設定します。

  • プロキシ名: "mybooksearch"
  • プロキシ ベースパス: "/mybooksearch"
  • 既存の API: "https://www.googleapis.com/books/v1/volumes"

プロキシを作成してデプロイしたら、次の形式で curl コマンドを使用してプロキシを呼び出すことができます。

curl http://org_name-env_name.apigee.net/mybooksearch?q=davinci%20code

ここで、org_name と env_name には、プロキシをデプロイした組織と環境を指定します。次に例を示します。 

curl http://myorg-test.apigee.net/mybooksearch?q=davinci%20code

カスタム分析データを収集する

API リクエストから分析データを収集する手順は、次の 2 つステップで構成されます。

  1. 目的のデータを抽出して、変数に書き込みます。

    Edge API Analytics に渡されるすべてのデータは変数に保存された値から取得されます。一部のデータは、API プロキシに渡されるクエリ パラメータの値など、事前に定義された Edge フロー変数に自動的に保存されます。事前に設定されたフロー変数の詳細については、フロー変数の概要をご覧ください。

    Extract Variables ポリシーを使用して、リクエストまたはレスポンスからカスタム コンテンツを抽出し、そのデータを変数に書き込みます。

  2. 変数のデータを Edge API Analytics に書き込みます。

    Statistics Collector ポリシーを使用して、変数のデータを Edge API Analytics に書き込みます。データは、事前に定義された Edge フロー変数または Extract Variables ポリシーによって作成された変数から抽出できます。

統計データを収集したら、Edge 管理 UI または API を使用して、統計情報を取得してフィルタ処理できます。たとえば、各書籍タイトルの平均評価を示すカスタム レポートを生成できます。この書籍タイトルは、API に渡されるクエリ パラメータの値に対応します。

Extract Variables ポリシーを使用して分析データを抽出する

分析データは、API Analytics に渡す前に抽出し、Edge によって事前に定義されたフロー変数またはユーザー定義のカスタム変数に保存する必要があります。変数にデータを書き込むには、Extract Variables ポリシーを使用します。

Extract Variables ポリシーは、JSONPath または XPath 式を使用してメッセージ ペイロードを解析できます。Google Book API の JSON 検索結果から情報を抽出するには、JSONPath 式を使用します。たとえば、JSON 結果配列の最初の項目から averageRating の値を抽出する JSONPath 式は、次のとおりです。

$.items[0].volumeInfo.averageRating

JSONPath が評価されると、Extract Variables ポリシーが抽出された値を変数に書き込みます。

この例では、Extract Variables ポリシーを使用して、次の 4 つの変数を作成します。

  • responsejson.totalitems
  • responsejson.ratingscount
  • responsejson.avgrating
  • responsejson.pdf

これらの変数のうち、responsejson は変数 prefix、totalitems、ratingscount、avgrating、および pdf は変数 names です。

次の Extract Variables ポリシーは、JSON レスポンスからデータを抽出し、それをカスタム変数に書き込む方法を示しています。各 <Variable> 要素は、カスタム変数名および関連する JSONPath 式を指定する name 属性を使用します。<VariablePrefix> 要素は、変数 prefix を指定します。

このポリシーを Edge UI で API プロキシに追加します。XML で API プロキシを構築している場合は、ポリシーを /apiproxy/policies にある ExtractVars.xml というファイルに追加します。

<ExtractVariables name="ExtractVars">
    <Source>response</Source>
    <JSONPayload>
        <Variable name="totalitems">
            <JSONPath>$.totalItems</JSONPath>
        </Variable>
        <Variable name="ratingscount">
            <JSONPath>$.items[0].volumeInfo.ratingsCount</JSONPath>
        </Variable>
        <Variable name="avgrating">
            <JSONPath>$.items[0].volumeInfo.averageRating</JSONPath>
        </Variable>
        <Variable name="pdf">
            <JSONPath>$.items[0].accessInfo.pdf.isAvailable</JSONPath>
        </Variable>
    </JSONPayload>
    <VariablePrefix>responsejson</VariablePrefix>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Statistics Collector ポリシーを使用してデータを Analytics Service に書き込む

Statistics Collector ポリシーを使用して、変数から Edge API Analytics にデータを書き込みます。Statistics Collectory ポリシーの形式は次のとおりです。

<StatisticsCollector>
<DisplayName>Statistics Collector-1</DisplayName>
    <Statistics>
        <Statistic name="statName" ref="varName" type="dataType">defVal</Statistic>
       …
    </Statistics>
</StatisticsCollector>

ここで

  • statName には、カスタム レポート内の統計データを参照するために使用する名前を指定します。
  • varName には、収集する分析データを含む変数の名前を指定します。この変数は Edge に組み込むことも、Extract Variables ポリシーによって作成されるカスタム変数にすることもできます。

  • dataType には、記録されたデータのデータ型を string、integer、float、long、double、または boolean として指定します。

    データ型が string の場合は、カスタム レポートに記載された統計データをディメンションとして参照します。データ型が数値（integer / float / long / double）の場合は、カスタム レポートに記載された統計データをディメンションまたは指標として参照します。

  • defValue は、オプションでカスタム変数のデフォルト値を提供します。変数が解決できない場合や変数が未定義の場合は、API Analytics に送信されます。

以下の例では、Statistics Collector ポリシーを使用して、Extract Variables ポリシーによって作成された変数に関するデータを収集します。また、各 API 呼び出しに渡されるクエリ パラメータの値も収集します。事前に定義されたフロー変数を使用して、クエリ パラメータを参照します。

request.queryparam.queryParamName

「q」というクエリ パラメータは、次のように参照します。

request.queryparam.q

このポリシーを Edge UI で API プロキシに追加します。XML で API プロキシを構築している場合は、次のコンテンツを /apiproxy/policies にある AnalyzeBookResults.xml, というファイルに追加します。

<StatisticsCollector name="AnalyzeBookResults">
 <Statistics>
        <Statistic name="totalitems" ref="responsejson.totalitems" type="integer">0</Statistic>
        <Statistic name="ratingscount" ref="responsejson.ratingscount" type="integer">0</Statistic>
        <Statistic name="avgrating" ref="responsejson.avgrating" type="float">0.0</Statistic>
        <Statistic name="pdf" ref="responsejson.pdf" type="boolean">true</Statistic>
        <Statistic name="booktitle" ref="request.queryparam.q" type="string">none</Statistic>
 </Statistics>
</StatisticsCollector>

ProxyEndpoint レスポンス フローにポリシーを接続する

処理が適切に行われるようにするには、ポリシーを API プロキシフローの適切な場所に接続する必要があります。このユースケースでは、Google Book API からレスポンスを受信してから、そのレスポンスをリクエスト元のクライアントに送信するまでの間に、ポリシーを実行しなければなりません。そのため、ポリシーを ProxyEndpoint レスポンス PreFlow に接続します。

次の ProxyEndpoint 構成の例では、最初に ExtractVars というポリシーが実行されてから、レスポンス メッセージが解析されます。その後で、AnalyzeBookResults というポリシーによって、それらの値が API Analytics に転送されます。

<ProxyEndpoint name="default">
    ><PreFlow name="PreFlow">
        <Request/>
        <Response>
            <Step>
                <Name>Extract-Vars</Name>
            </Step>
            <Step>
                <Name>AnalyzeBookResults</Name>
            </Step>
        </Response>
    </PreFlow>
 <HTTPProxyConnection>
  <!-- Base path used to route inbound requests to this API proxy -->
  <BasePath>/mybooksearch</BasePath>
  <!-- The named virtual host that defines the base URL for requests to this proxy -->
  <VirtualHost>default</VirtualHost>
 </HTTPProxyConnection>
 <RouteRule name="default">
 <!-- Connects the proxy to the target defined under /targets -->
  <TargetEndpoint>default</TargetEndpoint>
 </RouteRule>
</ProxyEndpoint>

API プロキシをデプロイする

これらの変更が終了したら、構成した API プロキシをデプロイする必要があります。

分析データを入力する

API プロキシをデプロイしたら、プロキシを呼び出して API Analytics にデータを入力します。これを行うには、それぞれ異なる書籍タイトルを使用する次のコマンドを実行します。

Mobey Dick:

curl https://org_name-env_name.apigee.net/mybooksearch?q=mobey%20dick

The Da Vinci Code:

curl https://org_name-env_name.apigee.net/mybooksearch?q=davinci%20code

Gone Girl:

curl https://org_name-env_name.apigee.net/mybooksearch?q=gone%20girl

Game of Thrones:

curl https://org_name-env_name.apigee.net/mybooksearch?q=game%20of%20thrones

アナリティクス データを表示する

Edge は次の 2 つの方法でカスタム分析データを表示します。

  • Edge UI は、データをグラフィカルなチャートで表示可能なカスタム レポートをサポートしています。
  • 指標 API を使用すれば、Edge API に対する REST 呼び出しによって、分析データを取得できます。API を使用して、ポータルまたはカスタムアプリに埋め込むことが可能なカスタム ウィジェットの形態で独自の可視化を構築できます。

Edge UI を使用して統計情報のレポートを生成する

カスタム レポートを使用すると、特定の API 統計情報にドリルダウンして、確認が必要な正確なデータを表示できます。Edge に組み込まれている任意の指標やディメンションを使用して、カスタム レポートを作成できます。加えて、StatisticsCollector ポリシーを使用して抽出した分析データのいずれかを使用できます。

Statistics Collector ポリシーを作成するときには、収集されるデータのデータ型を指定します。string データ型については、カスタム レポートで統計データをディメンションとして参照します。数値データ型（integer / float / long / double）については、カスタム レポートで統計データをディメンションまたは指標として参照します。詳細については、カスタム レポートの管理をご覧ください。

Edge UI を使用したカスタム レポートの生成:

  1. 下記の手順に従って [Custom Reports] ページにアクセスします。

    Edge

    Edge UI を使用して [Custom Reports] ページにアクセスするには:

    1. apigee.com/edge にログインします。
    2. 左側のナビゲーション バーで、[Analyze] > [Custom Reports] > [Reports] を選択します。

    Classic Edge（Private Cloud）

    Classic Edge UI を使用して [Custom Reports] ページにアクセスするには:

    1. http://ms-ip:9000 にログインします。ここで、ms-ip は、Management Server ノードの IP アドレスまたは DNS 名です。

    2. 上部のナビゲーション バーで [Analtyics] > [Reports] を選択します。

  2. [Custom Reports] ページで、[+Custom Report] をクリックします。
  3. mybookreport などの [Report Name] を指定します。

  4. [Traffic] などの組み込み [Metric] と [Sum] などの [Aggregate function] を選択します。

    または、StatisticsCollector ポリシーを使用して作成した数値データ統計情報のいずれかを選択します。たとえば、[ratingscount] と [Sum] の [Aggregate function] を選択します。

  5. [API Proxy] などの組み込み [Dimension] あるいは StatisticsCollector ポリシーを使用して作成した文字列または数値統計情報のいずれかを選択します。

    たとえば、[booktitle] を選択します。これで、[booktitle] 別の [ratingscount] の合計がレポートに表示されます。

    カスタム書籍レポート
  6. [Save] を選択します。レポートがすべてのカスタム レポートのリストに表示されます。

  7. レポートを実行するには、レポート名を選択します。デフォルトでは、レポートには過去 1 時間のデータが表示されます。

  8. 時間範囲を設定するには、右上の日付表示を選択して [Date selector] ポップアップを開きます。

  9. [Last 7 days] を選択します。レポートが更新されて、書籍タイトルごとの評価の合計が表示されます。

    書籍レポート チャート

Edge API を使用して統計情報を取得する

Edge 指標 API を使用して、カスタム分析データに関する統計情報を取得します。次にリクエストの例を示します。

  • /stats の後ろの URL へのリソースが必要なディメンションを指定します。この例では、ディメンション booktitle に関するデータを取得します。
  • 取得する指標を指定するための select クエリ パラメータ。このリクエストは、ratingscount の合計に基づく分析を返します。

  • timeRange パラメータは、返されるデータの時間間隔を指定します。時間範囲は次の形式です。

    MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM

完全な API 呼び出しは次のとおりです。

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/org_name/environments/env_name/stats/booktitle?select=sum(ratingscount)&timeRange=04/21/2019&2014:00:00~04/22/2019&2014:00:00" /
-u email:password

レスポンスは次の形式で表示されます。

{
  "environments": [
    {
      "dimensions": [
        {
          "metrics": [
            {
              "name": "sum(ratingscount)",
              "values": [
                "5352.0"
              ]
            }
          ],
          "name": "gone girl"
        },
        {
          "metrics": [
            {
              "name": "sum(ratingscount)",
              "values": [
                "4260.0"
              ]
            }
          ],
          "name": "davinci code"
        },
        {
          "metrics": [
            {
              "name": "sum(ratingscount)",
              "values": [
                "1836.0"
              ]
            }
          ],
          "name": "game of thrones"
        },
        {
          "metrics": [
            {
              "name": "sum(ratingscount)",
              "values": [
                "1812.0"
              ]
            }
          ],
          "name": "mobey dick"
        }
      ],
      "name": "prod"
    }
  ],
  "metaData": {
    "errors": [],
    "notices": [
      "query served by:9b372dd0-ed30-4502-8753-73a6b09cc028",
      "Table used: uap-prod-gcp-us-west1.edge.edge_api_raxgroup021_fact",
      "Source:Big Query"
    ]
  }
}

Edge 指標 API には複数のオプションがあります。たとえば、結果を昇順または降順に並べ替えることができます。次の例では、昇順を使用します。

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/org_name/environments/env_name/stats/booktitle?select=sum(ratingscount)&timeRange=04/21/2019&2014:00:00~04/22/2019&2014:00:00&sort=ASC" /
-u email:password

目的のディメンションの値を指定して、結果をフィルタ処理することもできます。次の例では、「Gone Girl」と「The Da Vinci Code」の結果でレポートがフィルタ処理されています。

$ curl -X GET "https://api.enterprise.apigee.com/v1/organizations/org_name/environments/env_name/stats/booktitle?select=sum(ratingscount)&timeRange=04/21/2019&2014:00:00~04/22/2019&2014:00:00&filter=(booktitle%20in%20'gone%20girl'%2C%20'davinci%20code')" /
-u email:password

Solution Builder を使用してカスタム分析変数を作成する

Solution Builder を使用すると、使いやすい管理 UI ダイアログからカスタム分析変数を作成できます。

必要に応じて、前のセクションのカスタム分析データを収集するをご覧ください。Extract Variables ポリシーと Statistics Collector ポリシーを組み合わせてカスタム変数を Edge API Analytics に入力する方法が説明されています。ご覧のとおり、UI はこれと同じパターンに従いますが、UI を使用して全体を構成するための簡単な方法があります。必要に応じて、ポリシーを手動で編集して接続するのではなく、UI を使用して Google Books API の例をお試しください。

[Solution Builder] ダイアログでは、アナリティクス変数を UI で直接構成できます。このツールを使用すると、自動的にポリシーが生成されて API プロキシに接続されます。ポリシーにより、リクエストまたはレスポンスから目的の変数が抽出され、その変数が Edge API Analytics に渡されます。

Solution Builder では、新しい Extract Variables ポリシーと Statistics Collector ポリシーが作成され、一意の名前が付けられます。Solution Builder では、一度特定のプロキシ リビジョンで作成されたポリシーを遡って変更することはできません。変更を加えるには、生成されたポリシーをポリシー エディタで直接編集します。

  1. Edge UI でプロキシの [Overview] ページに移動します。
  2. [Develop] をクリックします。
  3. [Develop] ページで、[Tools] メニューから [Custom Analytics Collection] を選択します。[Solution Builder] ダイアログが表示されます。
  4. [Solution Builder] ダイアログで、まず Extract Variables ポリシーと Statistics Collector ポリシーの 2 つを構成します。次に、これらのポリシーの接続先を構成します。
  5. 抽出するデータを指定します。
    • Location Type: 収集するデータのタイプとその収集元を選択します。リクエスト側またはレスポンス側のいずれかのデータを選択できます。たとえば、[Request: Query Parameter] または [Response: XML Body] を選択します。
    • Location Source: 収集するデータを識別します。たとえば、クエリ パラメータの名前を指定したり、レスポンス本文内の XML データの XPath を指定したりします。
  6. 抽出されたデータを識別するために Statistics Collector ポリシーで使用される変数の名前（および型）を指定します。このトピックに記載の命名規則をご覧ください。

    使用する名前が、カスタム レポート ビルダー UI のディメンションまたは指標に関するプルダウン メニューに表示されます。
  7. API プロキシフローで、生成された Extract Variables ポリシーと Statistics Collector ポリシーの接続先を選択します。ガイダンスについては、「ProxyEndpoint レスポンス フローにポリシーを接続する」をご覧ください。処理が適切に行われるようにするには、ポリシーを API プロキシフローの適切な場所に接続する必要があります。ポリシーは、フローにおいて、トラップ対象の変数がスコープ内にある（つまり、変数に値が入力される）間に接続する必要があります。
  8. [+Collector] をクリックして、カスタム変数をさらに追加します。

  9. 完了したら、[Build Solution] をクリックします。

  10. プロキシを保存してデプロイします。

これで、上記のとおり、データのカスタム レポートを生成できるようになりました。