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à report generata da questa richiesta può essere utilizzata per accedere report personalizzati da tutti gli utenti con accesso in lettura al tuo account Google Analytics proprietà.

Una volta pronto, il report personalizzato sarà disponibile per 72 ore. Dopo questa data periodo, la corrispondente risorsa dell'attività di report e i suoi contenuti eliminati automaticamente.

Creare un'attività di report

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

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

Seleziona un'entità report

Tutti i metodi dell'API di dati v1 richiedono Identificatore proprietà Google Analytics 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 all'evento Google Analytics. raccolti nella proprietà Google Analytics specificata.

Se utilizzi una delle librerie client dell'API di dati, non occorre manipolare manualmente il percorso dell'URL di richiesta. La maggior parte dei client API fornisce un parametro property che prevede un stringa nel formato properties/GA_PROPERTY_ID. Consulta la Guida rapida per alcuni esempi per l'utilizzo delle librerie client.

Richiedere la creazione di un'attività di report

Per creare un'attività di report, richiama il metodo reportTasks.create utilizzando il metodo 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 report Nome dell'attività nel campo name (ad esempio properties/1234567/reportTasks/123), che può essere utilizzato in per ottenere lo stato di un'attività di report e recuperare 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 report

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

Utilizza il nome dell'attività di segnalazione (ad esempio properties/1234567/reportTasks/123) che hai ricevuto da una risposta reportTasks.create per specificare Segnala attività.

Esempio:

Richiesta HTTP

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

Lo stato di idoneità per 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 cambia da CREATING a ACTIVE.

La reportMetadata contiene informazioni generali 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 richiamando il metodo reportTasks.list .

Recupera il report generato

Dopo aver creato l'attività di reporting utilizzando reportTasks.create , richiama il metodo reportTasks.query e specificare 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"
  }
}