Concetti fondamentali relativi alle attività sui report

Utilizzando le attività di report, puoi avviare una richiesta asincrona a esecuzione prolungata 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 tutti gli utenti con accesso in lettura alla tua proprietà Google Analytics.

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

Creare un'attività di report

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

Inoltre, puoi utilizzare reportTasks.get per recuperare i metadati di configurazione di 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 URL nel formato 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 degli eventi 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 nel formato properties/GA_PROPERTY_ID. Consulta la guida rapida per esempi di utilizzo delle librerie client.

Richiedere la creazione dell'attività di report

Per creare un'attività di report, chiama il metodo reportTasks.create utilizzando l'oggetto ReportTask in una richiesta. Sono necessari i seguenti parametri:

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 preparazione dell'attività di report

La generazione di un report dopo la chiamata reportTasks.create potrebbe richiedere diversi minuti. Puoi ottenere lo stato di preparazione 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 preparazione 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 di alto livello sul report generato, ad esempio il conteggio delle 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.

Recuperare il report generato

Una volta 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à 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"
  }
}