Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Descripción general

La API de Google Analytics Data v1 te permite generar tablas dinámicas. Las tablas dinámicas son una herramienta de resumen de datos que permite visualizarlos reorganizando la información de la tabla mediante la rotación de los datos en una o varias dimensiones.

Por ejemplo, considera la siguiente tabla de datos sin procesar:

Tabla de datos sin procesar

Con estos datos, es posible construir una tabla dinámica que desglose los datos de las sesiones por navegador, con las dimensiones de país e idioma seleccionadas como tablas dinámicas adicionales.

Tabla de datos dinámicos

Funciones compartidas con los informes de Core

Las solicitudes de informes de tablas dinámicas tienen la misma semántica que las solicitudes de informes principales para muchas funciones compartidas. Por ejemplo, la paginación, los filtros de dimensiones y las propiedades del usuario se comportan de la misma manera en los informes de tablas dinámicas que en los informes principales. Esta guía se centra en las funciones de informes dinámicos. Para familiarizarte con la funcionalidad de informes principales de la API de datos v1, lee la guía de conceptos básicos de informes y la guía de casos de uso avanzados.

Métodos de informes de tablas dinámicas

La versión 1 de la API de datos 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 de tus datos de eventos de Google Analytics. Cada tabla dinámica describe las columnas y filas de dimensiones visibles en la respuesta del informe.
batchRunPivotReports: Es una versión por lotes del método runPivotReport que permite generar varios informes con una sola llamada a la API.

Selecciona una entidad de informes

Todos los métodos de la versión 1 de la API de datos requieren que se especifique el identificador de la propiedad de Google Analytics dentro de una ruta de solicitud de URL con el formato properties/GA_PROPERTY_ID, como se muestra a continuación:

  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 que manipules la ruta de URL de la solicitud de forma manual. La mayoría de los clientes de API proporcionan un parámetro property que espera una cadena con el formato properties/GA_PROPERTY_ID. Consulta la Guía de inicio rápido para ver ejemplos de uso de las bibliotecas cliente.

Solicitud de informe de tabla dinámica

Para crear una solicitud con una tabla dinámica, usa el método runPivotReport o batchRunPivotReports.

Para solicitar datos dinámicos, puedes crear un objeto RunPivotReportRequest. Te recomendamos que comiences 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

A continuación, se muestra 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
      }
    ]
  }

Lista dinámica

Usa objetos Pivot en el campo pivot del cuerpo de la solicitud para definir las tablas dinámicas de los informes. Cada Pivot describe las columnas y filas de dimensiones visibles en la respuesta del informe.

La API de datos v1 admite varias tablas dinámicas, siempre que el producto del parámetro limit de cada tabla dinámica no supere las 100,000.

En el siguiente fragmento, se muestra el uso de pivots para crear un informe de recuentos de sesiones por país, dinámico según la dimensión browser. Observa cómo la consulta usa el campo orderBys para ordenar, y los campos limit 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 app. Por ejemplo, la dimensión city indica la ciudad ("París" o "Nueva York") en la que se originó cada evento. En una solicitud de informe, puedes especificar cero o más dimensiones.

Las dimensiones se deben definir dentro del campo dimensions del cuerpo de la solicitud. Para que sean visibles en un informe, esas dimensiones también deben aparecer en el campo fieldNames de un objeto Pivot. Una dimensión no será visible en un informe si no se usa en ningún pivote de una consulta dinámica. No todas las dimensiones deben estar presentes en el fieldNames de una tabla dinámica. Las dimensiones se pueden usar exclusivamente en filtros y no en el fieldNames de ninguna tabla dinámica.

En el siguiente fragmento, se muestra el uso de los campos dimension y fieldNames para una tabla con tablas dinámicas browser, country y language:

    "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 de tu sitio web o app. En una solicitud de informe, puedes especificar una o más métricas. Consulta las métricas de la API para obtener una lista completa de los nombres de las métricas de la API disponibles que se pueden especificar en las solicitudes.

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

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

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

Agregaciones de métricas

Usa el campo metricAggregations de un objeto Pivot para calcular los valores de métricas agregados de cada tabla dinámica.

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

En el siguiente ejemplo, se muestra un fragmento de una consulta que solicita los totales de la dimensión dinámica browser:

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

Las métricas calculadas se devuelven en el campo aggregates del objeto RunPivotReportResponse. En el caso de 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 de tablas dinámicas te permiten especificar los campos limit y offset en el objeto 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 con el objetivo de limitar la cardinalidad del informe.

La API de datos v1 admite varias tablas dinámicas, siempre que el producto del parámetro limit de cada tabla dinámica no supere las 100,000.

En el siguiente fragmento, se muestra el uso de los campos offset y limit para recuperar las siguientes cinco dimensiones de language con un desplazamiento de 10:

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

Filtros

Al igual que con la funcionalidad de informes principales, se debe usar un filtro de dimensiones con alcance de solicitud si deseas filtrar dimensiones en una solicitud de informes de tabla dinámica.

Ordenar

El comportamiento de ordenamiento de las consultas de informes de tablas dinámicas se puede controlar para cada tabla dinámica de forma individual con el campo orderBys de un objeto Pivot, que contiene una lista de objetos 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, que se usa en consultas dinámicas y ordena los resultados por los valores de una métrica dentro de un grupo de columnas dinámicas.

En este ejemplo, se muestra un fragmento de una definición de tabla dinámica que reorienta el informe en la dimensión browser y ordena 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 tabla dinámica de una solicitud a la API de informe de tabla dinámica es, principalmente, un encabezado y filas.

Encabezados de respuesta

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

Por ejemplo, un informe con las dimensiones de tabla dinámica browser, country y language, y la métrica sessions generará encabezados como este:

{
  "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 la función de cada componente de PivotReportResponse en la renderización del informe de tabla dinámica:

Tabla de datos sin procesar

Filas de respuesta

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

En el siguiente ejemplo, se muestra un fragmento de una respuesta de informe de tabla dinámica para una consulta con las dimensiones de tabla dinámica browser, country y language, y la métrica sessions. Cada celda del informe de tabla dinámica se devuelve 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 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 cómo instalar y configurar las bibliotecas cliente.

En los siguientes ejemplos, se usa la biblioteca cliente para ejecutar una consulta de tabla dinámica y crear un informe de recuentos de sesiones por país, con la dimensión del navegador como tabla dinámica.

PHP

google-analytics-data/src/run_pivot_report.php

Abrir en Cloud Shell Ver en GitHub

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()
        );
    }
}run_pivot_report.php

Python

google-analytics-data/run_pivot_report.py

Abrir en Cloud Shell Ver en GitHub

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)

run_pivot_report.py

Node.js

google-analytics-data/run_pivot_report.js

Abrir en Cloud Shell Ver en GitHub

  // TODO(developer): Uncomment this variable and replace with your
  // Google Analytics 4 property ID before running the sample.
  // propertyId = 'YOUR-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: '2021-01-01',
          endDate: '2021-01-30',
        },
      ],
      pivots: [
        {
          fieldNames: ['country'],
          limit: 250,
          orderBys: [
            {
              dimension: {
                dimensionName: 'country',
              },
            },
          ],
        },
        {
          fieldNames: ['browser'],
          offset: 3,
          limit: 3,
          orderBys: [
            {
              metric: {
                metricName: 'sessions',
              },
              desc: true,
            },
          ],
        },
      ],
      metrics: [
        {
          name: 'sessions',
        },
      ],
      dimensions: [
        {
          name: 'country',
        },
        {
          name: 'browser',
        },
      ],
    });
    printPivotReportResponse(response);
  }

  runPivotReport();

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

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

Aplicación de demostración

Consulta la aplicación de demostración de informes de tabla dinámica de la API de Google Analytics v1 para ver un ejemplo de cómo crear y mostrar un informe de tabla dinámica con JavaScript.

Descripción general Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Funciones compartidas con los informes de Core

Métodos de informes de tablas dinámicas

Selecciona una entidad de informes

Solicitud de informe de tabla dinámica

HTTP

Lista dinámica

Dimensiones

Métricas

Agregaciones de métricas

Paginación

Filtros

Ordenar

Denunciar respuesta

Encabezados de respuesta

Filas de respuesta

Bibliotecas cliente

PHP

Python

Node.js

Aplicación de demostración

Descripción general