Concetti fondamentali relativi alle attività sui report

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

La risorsa Attività di 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 Attività di report corrispondente e i relativi contenuti verranno eliminati automaticamente.

Creare un'attività di report

L'API Google Analytics Data v1 utilizza un approccio asincrono per creare attività di report. Innanzitutto, è necessaria una richiesta al reportTasks.create metodo per creare un'attività di report. Poi, il reportTasks.query metodo 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à.

Selezionare un'entità di reporting

Tutti i metodi dell'API Data v1 richiedono che l' identificatore della proprietà Google Analytics sia specificato all'interno di un percorso della 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 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 nel formato properties/GA_PROPERTY_ID. Per esempi di utilizzo delle librerie client, consulta la guida rapida .

Richiedere la creazione dell'attività di report

Per creare un'attività di report, chiama il reportTasks.create metodo utilizzando l' ReportTask oggetto 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"
    }
  }
}

Ottenere lo stato di preparazione dell'attività di report

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

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 state campo di una risposta. Una volta completata la generazione del report, lo stato di un'attività di report passa da CREATING a ACTIVE.

Il reportMetadata campo contiene le informazioni di alto livello sul report generato, come 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 reportTasks.list metodo.

Recuperare il report generato

Una volta generata l'attività di report creata utilizzando il reportTasks.create metodo, chiama il reportTasks.query metodo 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 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"
  }
}