Descripción general

La versión 1 de la API de datos de Google Analytics te permite generar tablas dinámicas. Dinámico las tablas son una herramienta de resumen de datos que visualiza los datos reorganizando los información de la tabla dinamizando (rotando) los datos en uno o varios dimensiones.

A modo de ejemplo, considera la siguiente tabla de datos sin procesar:

Tabla de datos sin procesar

Con estos datos es posible construir una tabla dinámica desglosando los datos de las sesiones por navegador, con las dimensiones de idioma y país seleccionadas como pivotes adicionales.

Tabla de datos dinámica

Funciones compartidas con los informes principales

Las solicitudes de informes dinámicos tienen la misma semántica que las solicitudes de informes principales para muchas funciones compartidas. Por ejemplo: paginación, Filtros de dimensión y Usuarios Las propiedades se comportan de la misma manera en los Informes dinámicos que en los informes principales. Esta se centra en las funciones de informes dinámicos. Para familiarizarse con el Core Funcionalidad de informes de la API de datos v1; lee la guía básica de informes. y la guía de casos de uso avanzados.

Métodos de informes dinámicos

La API de datos v1 admite la funcionalidad de tabla dinámica en los siguientes métodos de informes:

  • runPivotReport Este método devuelve un informe de tabla dinámica personalizado con los datos de eventos de Google Analytics. Cada pivot describe las columnas y filas de las dimensiones visibles en la respuesta del informe.

  • batchRunPivotReports Esto es una versión por lotes del método runPivotReport que permite generar varios informes con una sola llamada a la API.

Cómo seleccionar una entidad denunciante

Todos los métodos de Data API v1 requieren el identificador de propiedad de Google Analytics que se especificará dentro de una ruta de solicitud de URL con el formato properties/GA_PROPERTY_ID, por ejemplo:

  POST  https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport

El informe resultante se generará en función de los datos de eventos de Google Analytics. recopilados en la propiedad de Google Analytics especificada.

Si usas una de las bibliotecas cliente de la API de datos, no es necesario manipular manualmente la ruta de la URL de solicitud. La mayoría de los clientes de API proporciona un parámetro property que espera una cadena en la forma de properties/GA_PROPERTY_ID Consulta la Guía de inicio rápido para ver ejemplos de uso de las bibliotecas cliente.

Solicitud de informe dinámico

Para construir una solicitud con una tabla dinámica, usa runPivotReport o el batchRunPivotReports .

Para solicitar datos dinámicos, puedes construir una RunPivotReportRequest . Recomendamos comenzar con estos parámetros de solicitud:

  • Una entrada válida en el campo dateRanges.
  • Al menos una entrada válida en el campo dimensions.
  • Al menos una entrada válida en el campo metrics.
  • Al menos dos entradas de tabla dinámica válidas en el campo pivots.

Esta es una solicitud de ejemplo con los campos recomendados:

HTTP

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport
  {
    "dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
    "dimensions": [
        { "name": "browser" },
        { "name": "country" },
        { "name": "language" }
      ],
    "metrics": [{ "name": "sessions" }],
    "pivots": [
      {
        "fieldNames": [
          "browser"
        ],
        "limit": 5
      },
      {
        "fieldNames": [
          "country"
        ],
        "limit": 250
      },
      {
        "fieldNames": [
          "language"
        ],
        "limit": 15
      }
    ]
  }

Tablas dinámicas

Usa objetos Pivot en el campo pivot de la solicitud body para definir los pivotes del informe. Cada Pivot describe la dimensión visible y filas en la respuesta del informe.

La API de datos v1 admite varias pivotes siempre y cuando el producto del límite de cada elemento dinámico no supere los 100,000.

A continuación, se muestra un fragmento que muestra el uso de pivots para crear un informe de recuentos de sesiones por país, según la dimensión browser. Observa cómo la usa el campo orderBys ordenamiento, y el límite, y offset para implementar la paginación.

    "pivots": [
      {
        "fieldNames": [
          "country"
        ],
        "limit": 250,
        "orderBys": [
          {
            "dimension": {
              "dimensionName": "country"
            }
          }
        ]
      },
      {
        "fieldNames": [
          "browser"
        ],
        "offset": 3,
        "limit": 3,
        "orderBys": [
          {
            "metric": {
              "metricName": "sessions"
            },
            "desc": true
          }
        ]
      }
    ],
    ...

Dimensiones

Las dimensiones describen y agrupan los datos de eventos de tu sitio web o aplicación. La dimensión city, por ejemplo, indica la ciudad ("París" o "Nueva York") donde se originó cada evento. En una solicitud de informe, puedes especificar cero o más dimensiones.

Las dimensiones deben definirse dentro del dimensiones de la solicitud. Para que se puedan ver en un informe, esas dimensiones también deben deben mostrarse en los campos fieldNames de un objeto Pivot. Una dimensión no será visible en un informe si no se usa en ninguna tabla dinámica de una consulta dinámica. No todas las dimensiones deben estar presentes en la tabla dinámica fieldNames Las dimensiones se pueden utilizar exclusivamente en los filtros y no en el fieldNames de cualquier elemento dinámico.

A continuación, se incluye un fragmento que muestra el uso de los campos dimension y fieldNames para una tabla con browser, country y language pivotes:

    "pivots": [
      {
        "fieldNames": [
          "browser"
        ],
        "limit": 5,
        "orderBys": [
          {
            "metric": {
              "metricName": "sessions"
            },
            "desc": true
          }
        ]
      },
      {
        "fieldNames": [
          "country"
        ],
        "limit": 250,
        "orderBys": [
          {
            "dimension": {
              "dimensionName": "country"
            }
          }
        ]
      },
      {
        "fieldNames": [
          "language"
        ],
        "limit": 10
      }
    ],

Métricas

Las métricas son mediciones cuantitativas de los datos de eventos para tu sitio web o aplicación. En una solicitud de informe, puedes especificar una o más métricas. Consulta las Métricas de la API para ver una lista completa de los nombres de las métricas de la API. disponibles para especificarse en las solicitudes.

En las solicitudes de informes dinámicos, las métricas se definen usando el campo metrics de la del cuerpo de la solicitud, que es similar a los métodos de los informes principales.

En el siguiente ejemplo, se especifica el recuento de sesiones para usar como valor de métrica en un informe:

    "metrics": [
      {
        "name": "sessions"
      }
    ],

Agregaciones de métricas

Usa la clase metricAggregations. campo de un objeto Pivot para calcular la métrica agregada de salida para cada pivot.

Las agregaciones solo se calcularán si metricAggregations campo especificado en una solicitud.

A continuación, se muestra un fragmento de una consulta que solicita los totales para el Dimensión de tabla dinámica browser:

"pivots": [
  {
    "fieldNames": [
      "browser"
    ],
    "limit": 10,
    "metricAggregations": [
      "TOTAL",
    ]
  },
  ...

Las métricas calculadas se muestran en el conjunto de datos agregados campo de RunPivotReportResponse . Para las filas de métricas agregadas, el campo dimensionValues contiene un valor especial de RESERVED_TOTAL, RESERVED_MAX o RESERVED_MIN.

  "aggregates": [
    {
      "dimensionValues": [
        {
          "value": "Chrome"
        },
        {
          "value": "RESERVED_TOTAL"
        },
        {
          "value": "RESERVED_TOTAL"
        }
      ],
      "metricValues": [
        {
          "value": "4"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Firefox"
        },
        {
          "value": "RESERVED_TOTAL"
        },
        {
          "value": "RESERVED_TOTAL"
        }
      ],
      "metricValues": [
        {
          "value": "6"
        }
      ]
    },
  ....

  }

Paginación

Al igual que los métodos de informes principales, las solicitudes dinámicas te permiten para especificar el límite y offset en los Pivot para implementar la paginación. La configuración de paginación se aplica a cada tabla dinámica de forma individual. El campo limit es obligatorio para cada objeto Pivot para limitar la cardinalidad del informe.

La API de datos v1 admite múltiples pivotes siempre y cuando el producto de limit de cada elemento dinámico no supere los 100,000.

A continuación, se muestra un fragmento que muestra el uso de los campos offset y limit para Recupera las siguientes cinco dimensiones de language con un desplazamiento de 10:

      {
        "fieldNames": [
          "language"
        ],
        "offset": 10,
        "limit": 5
      }

Filtros

Al igual que la funcionalidad de informes principales, una filtro de dimensión centrado en la solicitud se debe usar si se desea filtrar las dimensiones en un informe dinámico para cada solicitud.

Ordenar

El comportamiento de ordenamiento de las consultas de los informes de tabla dinámica se puede controlar para cada uno individualmente mediante orderBys de un objeto Pivot, que contiene una lista de OrderBy.

Cada OrderBy puede contener uno de los siguientes elementos:

  • DimensionOrderBy, ordena los resultados según los valores de una dimensión.
  • MetricOrderBy, ordena los resultados según los valores de una métrica.
  • PivotOrderBy, utilizado en dinamizar consultas y ordenar los resultados según los valores de la métrica dentro de un grupo de columnas dinámicas.

Este ejemplo muestra un fragmento de una definición de tabla dinámica que reorienta el informe en la dimensión browser, ordenando los resultados por la métrica sessions en orden descendente.

      {
        "fieldNames": [
          "browser"
        ],
        "limit": 5,
        "orderBys": [
          {
            "metric": {
              "metricName": "sessions"
            },
            "desc": true
          }
        ]
      }

Denunciar respuesta

La Respuesta del informe de Pivot de una tabla dinámica la solicitud a la API de informes es principalmente un encabezado y filas.

Encabezados de respuesta

El encabezado del informe dinámico consta de PivotHeaders, DimensionHeaders y MetricHeaders, que enumeran las columnas de la informe de tabla dinámica.

Por ejemplo, un informe con dimensiones dinámicas browser, country y language y la métrica sessions generará encabezados como estos:

{
  "pivotHeaders": [
    {
      "pivotDimensionHeaders": [
        {
          "dimensionValues": [
            {
              "value": "Chrome"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "Firefox"
            }
          ]
        },
        ...

      ],
      ...
    },
    {
      "pivotDimensionHeaders": [
        {
          "dimensionValues": [
            {
              "value": "United States"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "Canada"
            }
          ]
        },
        ...

      ],
      ...
    },
    {
      "pivotDimensionHeaders": [
        {
          "dimensionValues": [
            {
              "value": "English"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "French"
            }
          ]
        },
        ...

      ],
      ...
    }
  ],
  "dimensionHeaders": [
    {
      "name": "browser"
    },
    {
      "name": "country"
    },
    {
      "name": "language"
    }
  ],
  "metricHeaders": [
    {
      "name": "sessions",
      "type": "TYPE_INTEGER"
    }
  ],
  ...

}

En el siguiente gráfico, se ilustra el rol de cada componente del informe dinámico Respuesta durante la renderización del informe de datos dinámicos:

Tabla de datos sin procesar

Filas de respuesta

La respuesta del informe de elementos dinámicos de runPivotReport y batchRunPivotReports difiere de una respuesta para los métodos de informes principales como runReport y batchRunReports ya que cada fila de respuesta del informe dinámico representa una sola celda del , mientras que, en un informe normal, una sola fila de respuesta representa un línea de la tabla.

A continuación se muestra un fragmento de la respuesta de un informe de datos dinámicos para una con las dimensiones dinámicas browser, country y language, y el sessions. Cada celda del informe dinámico se muestra de forma individual:

  "rows": [
    {
      "dimensionValues": [
        {
          "value": "Chrome"
        },
        {
          "value": "United States"
        },
        {
          "value": "English"
        }
      ],
      "metricValues": [
        {
          "value": "1"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Firefox"
        },
        {
          "value": "Canada"
        },
        {
          "value": "French"
        }
      ],
      "metricValues": [
        {
          "value": "3"
        }
      ]
    },
    ...

  ]

Estos datos corresponden a las dos celdas que aparecen destacadas en la siguiente tabla:

Tabla de datos sin procesar

Bibliotecas cliente

Consulta la Guía de inicio rápido para obtener una explicación de a instalar y configurar bibliotecas cliente.

En los siguientes ejemplos se usa la biblioteca cliente para ejecutar una consulta dinámica y así compilar una informe de recuentos de sesiones por país, controlado por la dimensión del navegador

PHP

use Google\Analytics\Data\V1beta\Client\BetaAnalyticsDataClient;
use Google\Analytics\Data\V1beta\DateRange;
use Google\Analytics\Data\V1beta\Dimension;
use Google\Analytics\Data\V1beta\Metric;
use Google\Analytics\Data\V1beta\OrderBy;
use Google\Analytics\Data\V1beta\OrderBy\DimensionOrderBy;
use Google\Analytics\Data\V1beta\OrderBy\MetricOrderBy;
use Google\Analytics\Data\V1beta\Pivot;
use Google\Analytics\Data\V1beta\RunPivotReportRequest;
use Google\Analytics\Data\V1beta\RunPivotReportResponse;

/**
 * Runs a pivot query to build a report of session counts by country,
 * pivoted by the browser dimension.
 * @param string $propertyId Your GA-4 Property ID
 */
function run_pivot_report(string $propertyId)
{
    // Create an instance of the Google Analytics Data API client library.
    $client = new BetaAnalyticsDataClient();

    // Make an API call.
    $request = (new RunPivotReportRequest())
        ->setProperty('properties/' . $propertyId)
        ->setDateRanges([new DateRange([
            'start_date' => '2021-01-01',
            'end_date' => '2021-01-30',
            ]),
        ])
        ->setPivots([
            new Pivot([
                'field_names' => ['country'],
                'limit' => 250,
                'order_bys' => [new OrderBy([
                    'dimension' => new DimensionOrderBy([
                        'dimension_name' => 'country',
                    ]),
                ])],
            ]),
            new Pivot([
                'field_names' => ['browser'],
                'offset' => 3,
                'limit' => 3,
                'order_bys' => [new OrderBy([
                    'metric' => new MetricOrderBy([
                        'metric_name' => 'sessions',
                    ]),
                    'desc' => true,
                ])],
            ]),
        ])
        ->setMetrics([new Metric(['name' => 'sessions'])])
        ->setDimensions([
            new Dimension(['name' => 'country']),
            new Dimension(['name' => 'browser']),
        ]);
    $response = $client->runPivotReport($request);

    printPivotReportResponse($response);
}

/**
 * Print results of a runPivotReport call.
 * @param RunPivotReportResponse $response
 */
function printPivotReportResponse(RunPivotReportResponse $response)
{
    print 'Report result: ' . PHP_EOL;

    foreach ($response->getRows() as $row) {
        printf(
            '%s %s' . PHP_EOL,
            $row->getDimensionValues()[0]->getValue(),
            $row->getMetricValues()[0]->getValue()
        );
    }
}

Python

from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
    DateRange,
    Dimension,
    Metric,
    OrderBy,
    Pivot,
    RunPivotReportRequest,
)


def run_sample():
    """Runs the sample."""
    # TODO(developer): Replace this variable with your Google Analytics 4
    #  property ID before running the sample.
    property_id = "YOUR-GA4-PROPERTY-ID"
    run_pivot_report(property_id)


def run_pivot_report(property_id="YOUR-GA4-PROPERTY-ID"):
    """Runs a pivot query to build a report of session counts by country,
    pivoted by the browser dimension."""
    client = BetaAnalyticsDataClient()

    request = RunPivotReportRequest(
        property=f"properties/{property_id}",
        date_ranges=[DateRange(start_date="2021-01-01", end_date="2021-01-30")],
        pivots=[
            Pivot(
                field_names=["country"],
                limit=250,
                order_bys=[
                    OrderBy(
                        dimension=OrderBy.DimensionOrderBy(dimension_name="country")
                    )
                ],
            ),
            Pivot(
                field_names=["browser"],
                offset=3,
                limit=3,
                order_bys=[
                    OrderBy(
                        metric=OrderBy.MetricOrderBy(metric_name="sessions"), desc=True
                    )
                ],
            ),
        ],
        metrics=[Metric(name="sessions")],
        dimensions=[Dimension(name="country"), Dimension(name="browser")],
    )
    response = client.run_pivot_report(request)
    print_run_pivot_report_response(response)


def print_run_pivot_report_response(response):
    """Prints results of a runPivotReport call."""
    print("Report result:")
    for row in response.rows:
        for dimension_value in row.dimension_values:
            print(dimension_value.value)

        for metric_value in row.metric_values:
            print(metric_value.value)


Node.js

  // TODO(developer): Uncomment this variable and replace with your
  // Google Analytics 4 property ID before running the sample.
  // propertyId = Y'OUR-GA4-PROPERTY-ID;'

  // Imports the Google Analytics Data API client library.
  const {BetaAnalyticsDataClient} = require(@'google-analytics/data)';

  // Initialize client that will be used to send requests. This client only
  // needs to be created once, and can be reused for multiple requests.
  const analyticsDataClient = new BetaAnalyticsDataClient();

  // Runs a pivot query to build a report of session counts by country, pivoted by the browser dimension.
  async function runPivotReport() {
    const [response] = await analyticsDataClient.runPivotReport({
      property: `properties/${propertyId}`,
      dateRanges: [
        {
          startDate: 2'021-01-01,'
          endDate: 2'021-01-30,'
        },
      ],
      pivots: [
        {
          fieldNames: [c'ountry]',
          limit: 250,
          orderBys: [
            {
              dimension: {
                dimensionName: c'ountry,'
              },
            },
          ],
        },
        {
          fieldNames: [b'rowser]',
          offset: 3,
          limit: 3,
          orderBys: [
            {
              metric: {
                metricName: s'essions,'
              },
              desc: true,
            },
          ],
        },
      ],
      metrics: [
        {
          name: s'essions,'
        },
      ],
      dimensions: [
        {
          name: c'ountry,'
        },
        {
          name: b'rowser,'
        },
      ],
    });
    printPivotReportResponse(response);
  }

  runPivotReport();

  // Prints results of a runReport call.
  function printPivotReportResponse(response) {
    console.log(R'eport result:)';
    response.rows.forEach(row = >{
      row.dimensionValues.forEach(dimensionValue = >{
        console.log(dimensionValue.value);
      });

      row.metricValues.forEach(metricValue = >{
        console.log(metricValue.value);
      });
    });
  }r

Aplicación de demostración

Consulta la Demostración del informe dinámico v1 de la API de Google Analytics aplicación para ver un ejemplo de cómo compilar y mostrar un informe dinámico con JavaScript.