Concetti fondamentali relativi alle attività sui report

Utilizzando le attività dei report, puoi avviare una richiesta asincrona di lunga durata per creare un report personalizzato dei dati sugli eventi di Google Analytics.

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

Un report personalizzato sarà disponibile per 72 ore dopo la sua creazione. Al termine di questo periodo, la risorsa dell'attività report corrispondente e i relativi contenuti verranno eliminati automaticamente.

Creare un'attività di generazione di report

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

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

Seleziona un'entità report

Tutti i metodi dell'API di dati v1 richiedono che l'identificatore della proprietà Google Analytics sia specificato all'interno di un percorso della richiesta dell'URL sotto forma di properties/GA_PROPERTY_ID, ad esempio:

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

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

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

Richiedi la creazione dell'attività di generazione del report

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

Esempio di richiesta di creazione di attività di 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 della tâche di report nel campo name (ad es. properties/1234567/reportTasks/123), che può essere utilizzato nelle query successive per ottenere lo stato di una tâche di 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"
    }
  }
}

Ottenere lo stato di idoneità dell'attività di generazione di report

Potrebbero essere necessari diversi minuti per generare un report dopo la chiamata reportTasks.create. Puoi ottenere lo stato di idoneità per un'attività di generazione di report chiamando il metodo reportTasks.get.

Utilizza il nome dell'attività report (ad es. properties/1234567/reportTasks/123) che hai 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à di un'attività di report viene restituito nel state campo di una risposta. Al termine della generazione del report, lo stato di un'attività di report passa da CREATING a ACTIVE.

Il campo reportMetadata contiene le informazioni di alto livello sul report generato, ad esempio il numero di righe e la quantità di token 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à di generazione di report chiamando il metodo reportTasks.list.

Recuperare il report generato

Una volta generata 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à di generazione del 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"
  }
}