Concetti fondamentali relativi alle attività sui report

Con le attività relative ai report, puoi avviare una richiesta asincrona di lunga durata per creare un report personalizzato sui dati degli eventi di Google Analytics.

La risorsa Attività report generata da questa richiesta può essere utilizzata per accedere a report personalizzati da tutti gli utenti con accesso in lettura alla tua proprietà Google Analytics.

Una volta pronto, un report personalizzato sarà disponibile per 72 ore. Dopo questo periodo, la risorsa dell'attività report corrispondente e i suoi contenuti verranno eliminati automaticamente.

Creare un'attività report

La versione 1 dell'API di dati di Google Analytics utilizza un approccio asincrono per creare attività report. Innanzitutto, è necessaria una richiesta al metodo reportTasks.create per creare un'attività report. Successivamente, viene utilizzato il metodo reportTasks.query per recuperare il report personalizzato generato.

Inoltre, puoi utilizzare reportTasks.get per recuperare i metadati di configurazione su un'attività report specifica e reportTasks.list per elencare tutte le attività report per una proprietà.

Seleziona un'entità segnalante

Tutti i metodi dell'API di dati v1 richiedono l'identificatore della proprietà Google Analytics 4 da specificare all'interno di un percorso di richiesta dell'URL nella forma di properties/GA4_PROPERTY_ID, ad esempio:

  POST  https://analyticsdata.googleapis.com/v1alpha/properties/GA4_PROPERTY_ID/reportTasks

Il report viene generato in base ai dati sugli eventi di Google Analytics raccolti nella proprietà Google Analytics 4 specificata.

Se utilizzi una delle librerie client dell'API di dati, non è necessario modificare manualmente il percorso dell'URL della richiesta. La maggior parte dei client API fornisce un parametro property che prevede una stringa in forma di properties/GA4_PROPERTY_ID. Consulta la guida rapida per esempi di utilizzo delle librerie client.

Richiedere la creazione dell'attività report

Per creare un'attività report, chiama il metodo reportTasks.create utilizzando l'oggetto ReportTask in una richiesta. I seguenti parametri sono obbligatori:

Esempio di richiesta di creazione di un'attività report:

Richiesta HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks
{
  "reportDefinition": {
    "dateRanges": [{ "startDate": "2024-05-01"", "endDate": "2024-05-15" }],
    "dimensions": [{ "name": "country" }],
    "metrics": [{ "name": "activeUsers" }]
  }
}

Una risposta del metodo reportTasks.create contiene il nome dell'attività di report nel campo name (ad esempio properties/1234567/reportTasks/123), che può essere utilizzato nelle query successive per ottenere lo stato di un'attività report e recuperare il report risultante.

Risposta HTTP

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.ReportTask",
    "name": "properties/1234567/reportTasks/123",
    "reportDefinition": {
      "dimensions": [
        {
          "name": "country"
        }
      ],
      "metrics": [
        {
          "name": "activeUsers"
        }
      ],
      "dateRanges": [
        {
          "startDate": "2024-05-01",
          "endDate": "2024-05-15"
        }
      ]
    },
    "reportMetadata": {
      "state": "CREATING",
      "beginCreatingTime": "2024-05-16T00:00:01.133612336Z"
    }
  }
}

Recupero dello stato di idoneità dell'attività di report

La generazione di un report dopo la chiamata a reportTasks.create potrebbe richiedere diversi minuti. Puoi ottenere lo stato di idoneità per un'attività report chiamando il metodo reportTasks.get.

Usa il nome dell'attività report (ad esempio properties/1234567/reportTasks/123) ricevuto da una risposta reportTasks.create per specificare l'attività report.

Esempio:

Richiesta HTTP

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123

Lo stato di idoneità per un'attività report viene restituito nel campo state di una risposta. Al termine della generazione del report, lo stato di un'attività report cambia da CREATING a ACTIVE.

Il campo reportMetadata contiene informazioni generali sul report generato, ad esempio il numero di righe e la quantità di token di quota addebitati.

Risposta HTTP

{
  "reportDefinition": {
    "dimensions": [
      {
        "name": "country"
      }
    ],
    "metrics": [
      {
        "name": "activeUsers"
      }
    ],
    "dateRanges": [
      {
        "startDate": "2024-05-01",
        "endDate": "2024-05-15"
      }
    ]
  },
  "reportMetadata": {
    "state": "ACTIVE",
    "beginCreatingTime": "2024-05-16T00:00:01.133612336Z",
    "creationQuotaTokensCharged": 6,
    "taskRowCount": 167,
    "errorMessage": "",
    "totalRowCount": 167
  }
}

Puoi ottenere lo stato di tutte le attività report chiamando il metodo reportTasks.list.

Recupera il report generato

Dopo aver generato l'attività report creata utilizzando il metodo reportTasks.create, chiama il metodo reportTasks.query e specifica il nome dell'attività report (ad esempio properties/1234567/reportTasks/123).

Richiesta HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123:query

Se l'attività report è pronta, viene restituita una risposta contenente il report generato:

Risposta HTTP

{
  "dimensionHeaders": [
    {
      "name": "country"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [

...

  ],
  "rowCount": 167,
  "metadata": {
    "currencyCode": "USD",
    "timeZone": "America/Los_Angeles"
  }
}