Guia de início rápido para desenvolvedores da API Google Analytics Data v1

Neste guia de início rápido, você vai criar e enviar solicitações list para a API Data v1 do Google Analytics. Em seguida, vai conferir as respostas para configurar e verificar seu acesso à API.

É possível concluir este guia de início rápido usando um SDK ou a API REST no seu ambiente local ou em uma instância de VM do Google Cloud.

Confira um resumo das etapas:

  • Configure um projeto do Google Cloud e ative a API Google Analytics Data v1.
  • Na máquina local ou na instância de VM do Cloud:
    • Instale, inicialize e faça a autenticação com o Google Cloud.
    • Instale o SDK para sua linguagem (opcional).
  • Configure a autenticação.
  • Configure o acesso ao Google Analytics.
  • Configure um SDK.
  • Faça uma chamada de API.

Configure um projeto do Google Cloud

Clique no botão Ativar a API Data v1 do Google Analytics abaixo para selecionar ou criar um projeto do Google Cloud e ativar automaticamente a API Data v1 do Google Analytics.

Ativar a API Google Analytics Data v1

Configurar o Google Cloud

Na máquina local ou em uma instância de VM do Cloud, configure e faça a autenticação com o Google Cloud.

  1. Instale e inicialize o Google Cloud.

  2. Para garantir que os componentes gcloud estejam atualizados, execute o comando a seguir.

    gcloud components update

Para evitar o fornecimento do ID do projeto ao Google Cloud, use o comando gcloud config set para definir um projeto e uma região padrão.

Configurar a autenticação

Este guia de início rápido usa Application Default Credentials para encontrar credenciais automaticamente com base no ambiente do aplicativo. Assim, você não precisa mudar o código do cliente para autenticar.

A API Google Analytics Data v1 oferece suporte a contas de usuário e contas de serviço:

  • As contas de usuário representam um desenvolvedor, administrador ou qualquer outra pessoa que interaja com as APIs e serviços do Google.
  • As contas de serviço não representam um usuário humano específico. Eles oferecem uma maneira de gerenciar a autenticação e a autorização quando uma pessoa não está diretamente envolvida, como quando um aplicativo precisa acessar recursos do Google Cloud.

Para saber mais sobre autenticação e configuração de credenciais de conta para seu aplicativo, consulte Métodos de autenticação no Google.

Conta de usuário

Gere um arquivo local de credenciais padrão do aplicativo (ADC) executando o comando a seguir. Esse comando inicia um fluxo da Web em que você fornece suas credenciais de usuário.

  gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly"

Especifique os escopos necessários na API Data v1 do Google Analytics no comando. Para mais informações, consulte Configurar o Application Default Credentials.

Conta de serviço

Estas são as etapas para fazer a autenticação com uma conta de serviço usando uma instância de VM do Cloud:

  1. Crie uma conta de serviço.
  2. Anexe a conta de serviço à sua instância de VM do Cloud executando o seguinte comando da CLI gcloud:
  gcloud compute instances stop YOUR-VM-INSTANCE-ID

  gcloud compute instances set-service-account YOUR-VM-INSTANCE-ID \
    --service-account YOUR-SERVICE-ACCOUNT-EMAIL-ALIAS  \
    --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly"

Especifique os escopos necessários pela API Data v1 do Google Analytics no comando. Para mais informações, consulte Configurar o Application Default Credentials.

Configurar o acesso ao Google Analytics

Conceda acesso ao Google Analytics ao e-mail associado à sua conta de usuário ou de serviço.

Configurar o SDK para sua linguagem de programação

Na máquina local, instale o SDK para sua linguagem de programação.

Java

Guia de instalação da biblioteca de cliente do Java

PHP

Guia de instalação da biblioteca de cliente do PHP

Python

Guia de instalação da biblioteca de cliente do Python

Node.js

Guia de instalação da biblioteca de cliente do Node.js

.NET

Guia de instalação da biblioteca de cliente do .NET

Ruby

Guia de instalação da biblioteca de cliente do Ruby

Go

go get google.golang.org/genproto/googleapis/analytics/data/v1beta

REST

Insira o comando abaixo para configurar as variáveis de ambiente. Substitua PROJECT_ID pelo ID do seu projeto do Google Cloud e PROPERTY_ID pelo ID da sua propriedade do Google Analytics.

  export PROJECT_ID=PROJECT_ID
  export PROPERTY_ID=PROPERTY_ID

Fazer uma chamada de API

Execute o código a seguir para fazer a primeira chamada:

Java

import com.google.analytics.data.v1beta.BetaAnalyticsDataClient;
import com.google.analytics.data.v1beta.DateRange;
import com.google.analytics.data.v1beta.Dimension;
import com.google.analytics.data.v1beta.Metric;
import com.google.analytics.data.v1beta.Row;
import com.google.analytics.data.v1beta.RunReportRequest;
import com.google.analytics.data.v1beta.RunReportResponse;

/**
 * Google Analytics Data API sample quickstart application.
 *
 * <p>This application demonstrates the usage of the Analytics Data API using service account
 * credentials.
 *
 * <p>Before you start the application, please review the comments starting with "TODO(developer)"
 * and update the code to use correct values.
 *
 * <p>To run this sample using Maven:
 *
 * <pre>{@code
 * cd google-analytics-data
 * mvn compile exec:java -Dexec.mainClass="com.google.analytics.data.samples.QuickstartSample"
 * }</pre>
 */
public class QuickstartSample {

  public static void main(String... args) throws Exception {
    /**
     * TODO(developer): Replace this variable with your Google Analytics 4 property ID before
     * running the sample.
     */
    String propertyId = "YOUR-GA4-PROPERTY-ID";
    sampleRunReport(propertyId);
  }

  // This is an example snippet that calls the Google Analytics Data API and runs a simple report
  // on the provided GA4 property id.
  static void sampleRunReport(String propertyId) throws Exception {
    // Using a default constructor instructs the client to use the credentials
    // specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
    try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {

      RunReportRequest request =
          RunReportRequest.newBuilder()
              .setProperty("properties/" + propertyId)
              .addDimensions(Dimension.newBuilder().setName("city"))
              .addMetrics(Metric.newBuilder().setName("activeUsers"))
              .addDateRanges(DateRange.newBuilder().setStartDate("2020-03-31").setEndDate("today"))
              .build();

      // Make the request.
      RunReportResponse response = analyticsData.runReport(request);

      System.out.println("Report result:");
      // Iterate through every row of the API response.
      for (Row row : response.getRowsList()) {
        System.out.printf(
            "%s, %s%n", row.getDimensionValues(0).getValue(), row.getMetricValues(0).getValue());
      }
    }
  }
}

PHP

require 'vendor/autoload.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\RunReportRequest;

/**
 * TODO(developer): Replace this variable with your Google Analytics 4
 *   property ID before running the sample.
 */
$property_id = 'YOUR-GA4-PROPERTY-ID';

// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
$client = new BetaAnalyticsDataClient();

// Make an API call.
$request = (new RunReportRequest())
    ->setProperty('properties/' . $property_id)
    ->setDateRanges([
        new DateRange([
            'start_date' => '2020-03-31',
            'end_date' => 'today',
        ]),
    ])
    ->setDimensions([new Dimension([
            'name' => 'city',
        ]),
    ])
    ->setMetrics([new Metric([
            'name' => 'activeUsers',
        ])
    ]);
$response = $client->runReport($request);

// Print results of an API call.
print 'Report result: ' . PHP_EOL;

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

Python

from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
    DateRange,
    Dimension,
    Metric,
    RunReportRequest,
)


def sample_run_report(property_id="YOUR-GA4-PROPERTY-ID"):
    """Runs a simple report on a Google Analytics 4 property."""
    # TODO(developer): Uncomment this variable and replace with your
    #  Google Analytics 4 property ID before running the sample.
    # property_id = "YOUR-GA4-PROPERTY-ID"

    # Using a default constructor instructs the client to use the credentials
    # specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
    client = BetaAnalyticsDataClient()

    request = RunReportRequest(
        property=f"properties/{property_id}",
        dimensions=[Dimension(name="city")],
        metrics=[Metric(name="activeUsers")],
        date_ranges=[DateRange(start_date="2020-03-31", end_date="today")],
    )
    response = client.run_report(request)

    print("Report result:")
    for row in response.rows:
        print(row.dimension_values[0].value, row.metric_values[0].value)

Node.js

  /**
   * 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');

  // Using a default constructor instructs the client to use the credentials
  // specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
  const analyticsDataClient = new BetaAnalyticsDataClient();

  // Runs a simple report.
  async function runReport() {
    const [response] = await analyticsDataClient.runReport({
      property: `properties/${propertyId}`,
      dateRanges: [
        {
          startDate: '2020-03-31',
          endDate: 'today',
        },
      ],
      dimensions: [
        {
          name: 'city',
        },
      ],
      metrics: [
        {
          name: 'activeUsers',
        },
      ],
    });

    console.log('Report result:');
    response.rows.forEach((row) => {
      console.log(row.dimensionValues[0], row.metricValues[0]);
    });
  }

  runReport();

.NET

using Google.Analytics.Data.V1Beta;
using System;

namespace AnalyticsSamples
{
    class QuickStart
    {
        static void SampleRunReport(string propertyId="YOUR-GA4-PROPERTY-ID")
        {
            /**
             * TODO(developer): Uncomment this variable and replace with your
             *  Google Analytics 4 property ID before running the sample.
             */
            // propertyId = "YOUR-GA4-PROPERTY-ID";

            // Using a default constructor instructs the client to use the credentials
            // specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
            BetaAnalyticsDataClient client = BetaAnalyticsDataClient.Create();

            // Initialize request argument(s)
            RunReportRequest request = new RunReportRequest
            {
                Property = "properties/" + propertyId,
                Dimensions = { new Dimension{ Name="city"}, },
                Metrics = { new Metric{ Name="activeUsers"}, },
                DateRanges = { new DateRange{ StartDate="2020-03-31", EndDate="today"}, },
            };

            // Make the request
            RunReportResponse response = client.RunReport(request);

            Console.WriteLine("Report result:");
            foreach(Row row in response.Rows)
            {
                Console.WriteLine("{0}, {1}", row.DimensionValues[0].Value, row.MetricValues[0].Value);
            }
        }
        static int Main(string[] args)
        {
            if (args.Length > 0) {
                SampleRunReport(args[0]);
            } else {
                SampleRunReport();
            }
            return 0;
        }
    }
}

REST

Para enviar essa solicitação, execute o comando curl na linha de comando ou inclua a chamada REST no seu aplicativo.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  -d '
  {
    "dateRanges": [
      {
        "startDate": "2025-01-01",
        "endDate": "2025-02-01"
      }
    ],
    "dimensions": [
      {
        "name": "country"
      }
    ],
    "metrics": [
      {
        "name": "activeUsers"
      }
    ]
  }'  https://analyticsdata.googleapis.com/v1beta/properties/${PROPERTY_ID}:runReport

A resposta vai conter um relatório com usuários ativos divididos por país, por exemplo:

{
  "dimensionHeaders": [
    {
      "name": "country"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [
    {
      "dimensionValues": [
        {
          "value": "United States"
        }
      ],
      "metricValues": [
        {
          "value": "3242"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "(not set)"
        }
      ],
      "metricValues": [
        {
          "value": "3015"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "India"
        }
      ],
      "metricValues": [
        {
          "value": "805"
        }
      ]
    }
  ],
  "rowCount": 3,
  "metadata": {
    "currencyCode": "USD",
    "timeZone": "America/Los_Angeles"
  },
  "kind": "analyticsData#runReport"
}