Analiza el contenido de mensajes de API mediante estadísticas personalizadas

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X.
Información

Analytics para la API de Edge recopila y analiza una amplia variedad de información estadística de cada solicitud y respuesta a la API. Esta información se recopila de forma automática y, luego, se puede mostrar en la IU de Edge o mediante la API de métricas. Consulta las metrics y la dimensión para obtener más información sobre estas estadísticas.

También puedes recopilar datos de estadísticas personalizados específicos de proxies de API, apps, productos o desarrolladores. Por ejemplo, es posible que desees recopilar datos de parámetros de búsqueda, encabezados de solicitud, cuerpos de solicitudes y respuestas o variables que definas en tus API.

En este tema, se muestra cómo usar la política de Statistics Collector para extraer datos de estadísticas personalizados de una solicitud o respuesta a la API y proporcionar esos datos a Analytics de la API de Edge. Luego, se muestra cómo ver los datos de estadísticas en un informe en la IU de Edge o con la API de Edge.

Acerca de la API de Google Book

En este tema, se describe cómo capturar datos de estadísticas personalizados de solicitudes del proxy de API a la API de Google Libros. La API de Google Libros te permite buscar libros por título, tema, autor y otras características.

Por ejemplo, realiza solicitudes al extremo /volumes para realizar una búsqueda por título de libro. Pasa un solo parámetro de consulta a la API de Libros que contiene el título del libro:

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

La llamada muestra un arreglo JSON de elementos que coincide con los criterios de búsqueda. A continuación, se muestra el primer elemento del arreglo en la respuesta (ten en cuenta que se omitió parte del contenido por cuestiones de simplicidad):

{
 "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"
    },
...
   }
  }

Observa que se destacaron varias áreas de la respuesta:

  • Cantidad de resultados de la búsqueda
  • Calificación promedio del libro
  • Cantidad de calificaciones
  • Disponibilidad de las versiones PDF del libro

En las siguientes secciones, se describe cómo recopilar estadísticas de estas áreas de la respuesta y, también, del parámetro de búsqueda, q, que contiene los criterios de búsqueda.

Crea un proxy de API para la API de Google Book

Antes de recopilar estadísticas para la API de Google Book, debes crear un proxy de API perimetral que la llame. Luego, invocará ese proxy de API para realizar sus solicitudes a la API de Google Book.

Paso 2: Crea un proxy de API del instructivo para crear un proxy de API, se describe cómo crear un proxy que llame a la API https://mocktarget.apigee.net. Ten en cuenta que el proxy descrito en ese instructivo no requiere una clave de API para llamarlo.

Usa ese mismo procedimiento para crear un proxy de API para el extremo /volumes de la API de Google Book. En el paso 5 del procedimiento, cuando crees el proxy de API, configura las siguientes propiedades para hacer referencia a la API de Google Libros:

  • Nombre del proxy: "mybooksearch"
  • Ruta base del proxy: "/mybooksearch"
  • API existente: "https://www.googleapis.com/books/v1/volumes"

Después de implementar y crear el proxy, deberías poder llamarlo con un comando curl en el formato:

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

En el ejemplo anterior, org_name y env_name especifican la organización y el entorno en el que implementaste el proxy. Por ejemplo:

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

Recopila datos de estadísticas personalizados

La recopilación de datos de estadísticas de una solicitud a la API es un procedimiento de dos pasos:

  1. Extrae los datos de interés y escríbelos en una variable.

    Todos los datos que se pasan a Analytics de la API de Edge provienen de valores almacenados en variables. Algunos datos se almacenan automáticamente en variables de flujo de Edge predefinidas, como los valores de los parámetros de consulta que se pasan al proxy de la API. Consulta Descripción general de las variables de flujo para obtener más información sobre las variables de flujo predefinidas.

    Usa la política Extraer variables para extraer contenido personalizado de una solicitud o respuesta y escribir esos datos en una variable.

  2. Escribe datos de una variable en Analytics de la API de Edge.

    Usa la política del Recopilador de estadísticas para escribir datos de una variable en Analytics de la API de Edge. Los datos pueden provenir de variables de flujo de Edge predefinidas o variables creadas por la política Extraer variables.

Después de recopilar los datos estadísticos, puedes usar la IU o la API de administración de Edge para recuperar y filtrar estadísticas. Por ejemplo, puedes generar un informe personalizado que muestre la calificación promedio de cada título de un libro, en el que el título del libro corresponde al valor del parámetros de búsqueda que se pasa a la API.

Usa la política de extracción de variables para extraer datos de estadísticas

Los datos de estadísticas se deben extraer y almacenar en una variable, ya sea una variable de flujo predefinida por Edge o variables personalizadas que definas, antes de que se puedan pasar a API Analytics. Para escribir datos en una variable, usa la política Extraer variables.

La política de extracción de variables puede analizar cargas útiles de mensajes con expresiones JSONPath o XPath. Para extraer la información de los resultados de la búsqueda JSON de la API de Google Book, usa una expresión JSONPath. Por ejemplo, para extraer el valor del averageRating del primer elemento del arreglo de resultados JSON, la expresión JSONPath es la siguiente:

$.items[0].volumeInfo.averageRating

Después de evaluar JSONPath, la política Extraer variables escribe el valor extraído en una variable.

En este ejemplo, se usa la política de extracción de variables para crear cuatro variables:

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

Para estas variables, responsejson es la variable prefijo y totalitems, ratingscount, avgrating y pdf son la variable nombres.

En la siguiente política de extracción de las variables, se muestra cómo extraer datos de la respuesta JSON y escribirlos en variables personalizadas. Cada elemento <Variable> usa el atributo name que especifica el nombre de las variables personalizadas y la expresión JSONPath asociada. El elemento <VariablePrefix> especifica el prefijo de variable

Agrega esta política a tu proxy de API en la IU de Edge. Si compilas el proxy de API en XML, agrega la política a un archivo en /apiproxy/policies llamado 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>

Utiliza la política del Recopilador de estadísticas para escribir datos en el servicio de Analytics

Usa la política del Recopilador de estadísticas para escribir datos de una variable en las estadísticas de la API de Edge. La política del Recopilador de estadísticas tiene el siguiente formato:

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

Donde:

  • statName especifica el nombre que usas para hacer referencia a los datos estadísticos de un informe personalizado.
  • varName especifica el nombre de la variable que contiene los datos de estadísticas que se recopilarán. Esta variable se puede compilar en Edge o puede ser una variable personalizada creada por la política Extraer variables.
  • dataType especifica el tipo de datos de los datos registrados como string, número entero, número de punto flotante, largo, doble o booleano.

    Para datos de tipo string, en un informe personalizado, haces referencia a los datos estadísticos como una dimensión. Para los tipos de datos numéricos (número entero/flotante/largo/doble), debes hacer referencia a los datos estadísticos como una dimensión o una métrica en un informe personalizado.

  • De manera opcional, defValue proporciona un valor predeterminado para una variable personalizada, que se envía a Analytics de la API si las variables no se pueden resolver o si la variable no está definida.

En el siguiente ejemplo, se usa la política del Recopilador de estadísticas para recopilar datos de las variables creadas por la política Extrae variables. También recopilas el valor del parámetro de consulta que se pasa a cada llamada a la API. Haz referencia a los parámetros de consulta con la variable de flujo predefinida:

request.queryparam.queryParamName

En el parámetro de consulta llamado "q", haz referencia de la siguiente manera:

request.queryparam.q

Agrega esta política al proxy de tu API en la IU de Edge o, si compilas el proxy de API en XML, agrega un archivo en /apiproxy/policies llamado AnalyzeBookResults.xml, con el siguiente contenido:

<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>

Adjunta políticas al flujo de respuesta ProxyEndpoint

Para que todo funcione de forma correcta, las políticas deben adjuntarse al flujo de proxy de API en la ubicación adecuada. En este caso de uso, las políticas deben ejecutarse después de que se haya recibido la respuesta de la API de Google Book y antes de que la respuesta se envíe al cliente solicitante. Por lo tanto, adjunta las políticas a PreFlow de la respuesta de ProxyEndpoint.

La configuración de ProxyEndpoint de ejemplo primero ejecuta la política llamada ExtractVars para analizar el mensaje de respuesta. Luego, la política llamada AnalyzeBookResults reenvía esos valores a las estadísticas de API:

<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>

Implementa el proxy de API:

Después de haber realizado estos cambios, debes implementar el proxy de API que configuraste.

Propaga datos de estadísticas

Después de implementar el proxy de API, llame al proxy para propagar los datos en las estadísticas de la API. Puedes hacerlo mediante la ejecución de los siguientes comandos, cada uno de los cuales usa un título diferente para el libro:

Mobey Dick:

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

El código Da Vinci:

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

Perdida:

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

Juego de tronos:

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

Consulta datos de análisis

Edge ofrece dos formas de ver tus datos de estadísticas personalizados:

  • La IU de Edge admite informes personalizados que te permiten ver tus datos en un gráfico gráfico.
  • La API de Metrics te permite recuperar datos de estadísticas mediante llamadas de REST a la API de Edge. Puedes usar la API para compilar tus propias visualizaciones en forma de widgets personalizados que puedes incorporar en portales o apps personalizadas.

Cómo generar un informe de estadísticas con la IU de Edge

Los informes personalizados te permiten desglosar las estadísticas de API específicas para ver los datos exactos que deseas ver. Puedes crear un informe personalizado con cualquiera de las metrics y dimensión integradas en Edge. Además, puedes usar cualquiera de los datos de estadísticas que extrajiste mediante la política StatisticsCollector.

Cuando creas una política de recolector de estadísticas, debes especificar el tipo de datos de los datos recopilados. Para el tipo de datos de string, haz referencia a los datos estadísticos como una dimensión en un informe personalizado. Para los tipos de datos numéricos (número entero, número de punto flotante, largo, doble), haz referencia a la fecha estadística en un informe personalizado como una dimensión o como una métrica. Para obtener más información, consulta el artículo Administra informes personalizados.

Cómo generar un informe personalizado con la IU de Edge:

  1. Accede a la página Informes personalizados, como se describe a continuación.

    Conexión de integración

    Para acceder a la página Informes personalizados con la IU de Edge, sigue estos pasos:

    1. Accede a apigee.com/edge.
    2. En la barra de navegación izquierda, selecciona Analyze > Custom Reports > Reports.

    Versión clásica de Edge (nube privada)

    Para acceder a la página Informes personalizados con la IU clásica de Edge, sigue estos pasos:

    1. Accede a http://ms-ip:9000, donde ms-ip es la dirección IP o el nombre de DNS del nodo del servidor de administración.
    2. Selecciona Analíticos > Informes en la barra de navegación superior.

  2. En la página Informes personalizados, haz clic en +Custom Report.
  3. Especifica un Nombre de informe, como mybookreport.
  4. Selecciona una Métrica incorporada, como Tráfico, y una Función agregada, como Sum.

    O bien, selecciona una de las estadísticas de datos numéricos que creó mediante la política StatisticsCollector. Por ejemplo, selecciona ratingscount y una Función agregada de Sum.

  5. Selecciona una Dimensión integrada, como Proxy de API, o cualquiera de las strings o estadísticas numéricas que hayas creado con la política Statistics Collector.

    Por ejemplo, selecciona booktitle. Ahora, tu informe mostrará la suma de ratingscount por booktitle:

    Informe personalizado de libros
  6. Selecciona Save. El informe aparecerá en la lista de todos los informes personalizados.
  7. Para ejecutar el informe, selecciona el nombre del informe. De forma predeterminada, el informe muestra los datos de la última hora.

  8. Si quieres establecer el intervalo de tiempo, elige la fecha en la esquina superior derecha para abrir la ventana emergente Selector de fecha.
  9. Selecciona los últimos 7 días. El informe se actualiza para mostrar la suma de calificaciones por título del libro:

    Gráfico de informes de libros

Obtén estadísticas con la API de Edge

Usa la API de métricas de Edge para obtener estadísticas sobre tus datos de estadísticas personalizados. En la solicitud de ejemplo que aparece a continuación, ocurre lo siguiente:

  • El recurso de la URL después de /stats especifica la dimensión deseada. En este ejemplo, obtienes datos para la dimensión booktitle.
  • El parámetro de búsqueda select para especificar las metrics que se recuperarán. En esta solicitud, se muestran estadísticas en función de la suma de los ratingscount.
  • El parámetro timeRange especifica el intervalo de los datos que se muestran. El intervalo de tiempo tiene el siguiente formato:

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

La llamada a la API completa es la siguiente:

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

Deberías ver una respuesta en el formulario como la siguiente:

{
  "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"
    ]
  }
}

La API de métricas de Edge tiene muchas opciones. Por ejemplo, puedes ordenar los resultados de forma ascendente o descendente. En el siguiente ejemplo, se usa el orden ascendente:

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

También se pueden filtrar los resultados si especificas los valores de las dimensiones de interés. En el siguiente ejemplo, el informe se filtra por los resultados de “Perdida” y “El código Da Vinci”:

$ 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

Crea variables de estadísticas personalizadas con el compilador de soluciones

El Compilador de soluciones te permite crear variables de estadísticas personalizadas a través de un diálogo de IU de administración fácil de usar.

Te recomendamos que leas la sección anterior Recopila datos de estadísticas personalizados, en la que se explica cómo las políticas de extracción de variables y del recopilador de estadísticas funcionan en conjunto para proporcionar variables personalizadas a Analytics de la API de Edge. Como verás, la IU sigue este mismo patrón, pero te brinda una forma conveniente de configurar todo a través de la IU. Si lo deseas, prueba el ejemplo de la API de Google Libros mediante la IU en lugar de editar y adjuntar las políticas de forma manual.

El cuadro de diálogo del compilador de soluciones te permite configurar variables de estadísticas directamente en la IU. Esta herramienta genera políticas y las adjunta al proxy de API para ti. Las políticas extraen variables de interés de las solicitudes o respuestas y pasan las variables extraídas a Analytics de la API de Edge.

El compilador de soluciones crea nuevaspolíticas de extracción de variables y recopilador de estadísticas, y les asigna nombres únicos. El Compilador de soluciones no te permite retroceder y cambiar estas políticas una vez que se crean en una revisión de proxy determinada. Para realizar cambios, edita las políticas generadas directamente desde el editor de políticas.

  1. Ve a la página Descripción general de tu proxy en la IU de Edge.
  2. Haz clic en Develop.
  3. En la página del desarrollador, selecciona Custom Analytics Collection en el menú Herramientas. Aparecerá el cuadro de diálogo del compilador de soluciones.
  4. En el cuadro de diálogo del compilador de soluciones, primero configura dos políticas: Extrae variables y recopilador de estadísticas. Luego, debes configurar dónde adjuntar esas políticas.
  5. Especifica los datos que deseas extraer:
    • Tipo de ubicación: Selecciona el tipo de datos sobre el que desees recopilar datos y de dónde recopilarlos. Puedes seleccionar datos del lado de la solicitud o respuesta. Por ejemplo, solicitud: Parámetro de consulta o respuesta: Cuerpo XML.
    • Fuente de ubicación: Identifica los datos que deseas recopilar. Por ejemplo, el nombre del parámetros de búsqueda o la XPath para datos XML en el cuerpo de respuesta.
  6. Especifica un nombre para la variable (y el tipo) que la política de recolector de estadísticas usará para identificar los datos extraídos. En este tema, consulta las restricciones para asignar nombres.

    El nombre que utilices aparecerá en el menú desplegable de Dimensiones o Métricas en el la IU del Creador de informes personalizados.
  7. Elige en qué lugar del flujo del proxy de API que deseas adjuntar las políticas generadas Extrae variables y recopilador de estadísticas. Para obtener orientación, consulta “Adjunta políticas al flujo de respuesta de ProxyEndpoint”. Para que todo funcione de forma correcta, las políticas deben adjuntarse al flujo de proxy de API en la ubicación adecuada. Debes adjuntar las políticas en una etapa del flujo en la que las variables que capturas estén dentro del alcance (propagadas).
  8. Haga clic en +Recopilador para agregar más variables personalizadas.
  9. Cuando hayas terminado, haz clic en Build Solution.

  10. Guarda e implementa el proxy.

Ahora puede generar un informe personalizado para los datos como se describieron anteriormente.