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

Estás viendo la documentación de Apigee Edge.
Ve a la Documentación de Apigee X.
información

Analytics de la API de Edge recopila y analiza una amplia variedad de información estadística de cada la solicitud y respuesta a la API. Esta información se recopila automáticamente y puede mostrarse en el IU de Edge o mediante la API de Metrics Consulta las métricas 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 utilizar la política StatisticsCollector para extraer datos de estadísticas personalizados de una solicitud o respuesta a la API y enviarlos a las estadísticas de la API de Edge. Luego, se explica cómo ver tus datos de estadísticas en un informe con 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.

Crear un proxy de API para la API de Google Book

Antes de que puedas recopilar estadísticas para la API de Google Books, debes crear un proxy de la API de Edge que lo llama. Luego, usted invoca 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 del 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 las variables. Algunos datos se almacenan automáticamente en variables de flujo predefinidas de Edge, como 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. Escribir datos de una variable en Analytics de la API de Edge

    Utilizar la política Recopilador de estadísticas para escribir datos de una variable en Analytics de la API de Edge. Los datos pueden provenir de fuentes Variables de flujo de Edge o variables creadas con la política de extracción de variables.

Después de recopilar los datos estadísticos, puedes usar la IU o API de Edge Management 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 Las variables perimetrales o personalizadas que definas antes de que se puedan pasar a las estadísticas de la API 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 el elemento JSONPath, la política de extracción de 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>

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

Utilizar la política Recopilador de estadísticas para escribir datos de una variable en Analytics de la API de Edge. La política de Statistics Collectory tiene la siguiente forma:

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

Donde:

  • statName especifica el nombre que utilizas para hacer referencia a los datos estadísticos en 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 integrar en Edge o puede ser una variable personalizada creada por la política Extraer variables.
  • dataType especifica el tipo de datos registrados como string, número entero, número de punto flotante, largo, doble o booleano.

    Para los datos de tipo string, debes hacer referencia a los datos estadísticos como una dimensión. en un informe personalizado. Para los tipos de datos numéricos (número entero/flotante/long/doble), se hace referencia al 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 Estadísticas de API si las variables no se pueden resolver o si la variable no está definida.

En el siguiente ejemplo, se usa la política Recopilador de estadísticas para recopilar datos para las variables que crea la política de extracción de variables. También debes recopilar el valor del parámetro de consulta pasado a cada llamada a la API. Haz referencia a los parámetros de consulta mediante los parámetros variable de flujo:

request.queryparam.queryParamName

Para el parámetro de consulta llamado "q" hacer referencia a él de la siguiente manera:

request.queryparam.q

Agrega esta política a tu proxy de 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 Books. y antes de enviar la respuesta 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 proporciona 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.
  • La API de Metrics te permite recuperar datos de análisis a través de llamadas REST 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.

Genera 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. Puede crear un informe personalizado mediante cualquiera de las métricas. y la 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.

Genera un informe personalizado con la IU de Edge:

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

    Edge

    Para acceder a la página Custom Reports 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.

    Classic Edge (nube privada)

    Para acceder a la página Custom Reports 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 Análisis > 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 el proxy de API, o cualquiera de las strings numéricas o de string que hayas creado mediante la política StatisticsCollector.

    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. Para establecer el intervalo de tiempo, selecciona la fecha que se muestra en la esquina superior derecha a fin de abrir la ventana emergente Date selector.
  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 Edge metrics a 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 métricas 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 Edge metrics 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 Solution Builder te permite crear variables analíticas personalizadas a través de una interfaz fácil de usar de administración de identidades y accesos.

Te recomendamos leer la sección anterior Cómo recopilar datos de estadísticas personalizados. que explica cómo funcionan las políticas de extracción de variables y de recopilador de estadísticas. para enviar 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 solicitudes o respuestas y pasa las variables extraídas a Edge Estadísticas de API.

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 Overview 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 el en una etapa del flujo en la que las variables que atrapa están dentro del alcance (propagado).
  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.