Report sulle nozioni di base di Tasks

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

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

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

Crea un'attività di report

L'API Google Analytics Data v1 utilizza un approccio asincrono per creare attività di report. Innanzitutto, per creare un'attività di report è necessaria una richiesta al metodo reportTasks.create. Poi, viene utilizzato il metodo reportTasks.query per recuperare il report personalizzato generato.

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

Seleziona un'entità di reporting

Tutti i metodi dell'API di dati v1 richiedono che l'identificatore della proprietà Google Analytics venga specificato all'interno di un percorso di 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 di dati, non è necessario manipolare manualmente il percorso dell'URL della richiesta. La maggior parte dei client API fornisce un parametro property che prevede una stringa nel formato properties/GA_PROPERTY_ID. Consulta la guida rapida per esempi di utilizzo delle librerie client.

Richiedi la creazione dell'attività di report

Per creare un'attività 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 un'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 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à 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"
    }
  }
}

Ottieni lo stato di idoneità dell'attività di generazione del report

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

Utilizza il nome dell'attività di report (ad esempio properties/1234567/reportTasks/123) che hai ricevuto da una risposta reportTasks.create per specificare l'attività di 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 campo state di una risposta. Una volta completata la generazione del report, lo stato di un'attività di 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à di report chiamando il metodo reportTasks.list.

Recupera il report generato

Quando viene generata l'attività di report creata utilizzando il metodo reportTasks.create, chiama il metodo reportTasks.query e specifica il nome dell'attività di 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"
  }
}

Passaggi successivi