Creare un'esportazione dei segmenti di pubblico

I segmenti di pubblico in Google Analytics ti permettono di suddividere gli utenti in base agli obiettivi più importanti per la tua attività. Con i segmenti di pubblico, puoi raggruppare gli utenti del tuo sito o della tua applicazione in base ad attributi condivisi.

Puoi esportare i tuoi segmenti di pubblico, inclusa una istantanea dei relativi utenti, utilizzando l'API Data.

Consulta la guida Aspettative relative ai dati di esportazione del pubblico per informazioni importanti sui dati visualizzati nelle esportazioni del pubblico.

Panoramica

Invia le seguenti richieste dell'API Data per creare ed eseguire query su un'esportazione di segmenti di pubblico:

  1. Chiama il metodo audienceExports.create per creare un'esportazione del segmento di pubblico.
  2. Il metodo audienceExports.query viene utilizzato per recuperare gli utenti nel segmento di pubblico.

Per ulteriori informazioni, puoi chiamare audienceExports.get per recuperare i metadati di configurazione relativi a un'esportazione di segmenti di pubblico specifica e audienceExports.list per elencare tutte le esportazioni di segmenti di pubblico per una proprietà specifica.

Seleziona un'entità di reporting

Tutti i metodi dell'API Data richiedono che l'identificatore della proprietà Google Analytics sia specificato all'interno di un percorso di richiesta URL, nel formato properties/GA_PROPERTY_ID. Ecco un esempio:

  POST  https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/audienceExports

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 devi modificare 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.

Crea un'esportazione del segmento di pubblico

Per creare un'esportazione del segmento di pubblico, chiama il metodo audienceExports.create utilizzando l'oggetto AudienceExport nella richiesta. Sono necessari i seguenti parametri:

  • Un nome segmento di pubblico valido nel campo audience, formattato come properties/{propertyId}/audiences/{audienceId}. Puoi utilizzare il metodo audiences.list dell'API Google Analytics Admin v1 per ottenere questo valore. Il campo Audience.name della risposta audiences.list contiene il nome del segmento di pubblico.
  • Un elenco valido di dimensioni nel campo dimensions. L'elenco delle dimensioni supportate da questo metodo è disponibile nella documentazione Schema di esportazione dei segmenti di pubblico. Nell'esportazione di un segmento di pubblico vengono inclusi solo i dati per le dimensioni menzionate in questo campo.

Ecco una richiesta di esempio per creare un'esportazione del segmento di pubblico:

Richiesta HTTP

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports
{
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

Una risposta del metodo audienceExports.create contiene il nome dell'esportazione del segmento di pubblico nel campo name, ad esempio properties/1234567/audienceExports/123. Ecco una risposta di esempio:

Risposta HTTP

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceExport",
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "CREATING",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  }
}

Puoi utilizzare name per eseguire query sugli utenti dall'esportazione del segmento di pubblico.

Eseguire query sullo stato di preparazione dell'esportazione del segmento di pubblico

La generazione dell'esportazione del pubblico potrebbe richiedere diversi minuti dopo la chiamata audienceExports.create.

Puoi controllare lo stato di preparazione di un'esportazione di segmenti di pubblico chiamando il metodo audienceExports.get.

Utilizza il nome dell'esportazione del segmento di pubblico da una risposta audienceExports.create per specificare l'esportazione del segmento di pubblico nella richiesta.

Ecco una richiesta di esempio:

Richiesta HTTP

GET https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123

Lo stato di preparazione per un'esportazione di segmenti di pubblico viene restituito nel campo state della risposta. Una volta completata la generazione dell'esportazione del segmento di pubblico, il suo stato passa da CREATING a ACTIVE.

Ecco una risposta di esempio:

Risposta HTTP

{
  "name": "properties/1234567/audienceExports/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "state": "CREATING",
  "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
}

Puoi ottenere lo stato di tutte le esportazioni di segmenti di pubblico chiamando il metodo audienceExports.list.

Recuperare gli utenti da un'esportazione del segmento di pubblico

Una volta generata l'esportazione del pubblico, chiama il metodo audienceExports.query e specifica l'name dell'esportazione del pubblico nella richiesta.

Ecco una richiesta di esempio:

Richiesta HTTP

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123:query

Se l'esportazione del segmento di pubblico è pronta, questa chiamata restituisce l'elenco degli utenti nel segmento di pubblico.

Ecco una risposta di esempio:

Risposta HTTP

{
  "audienceExport": {
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  },
  "audienceRows": [
    {
      "dimensionValues": [
        {
          "value": "1000276123.1681742376"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000374452.1668627377"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000391956.1652750758"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000410539.1682018694"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000703969.1666725875"
        }
      ]
    }
  ],
  "rowCount": 5
}