Recupero di oggetti

GoogleAdsService è il servizio unificato di recupero degli oggetti e di generazione di report dell'API Google Ads. Il servizio dispone di metodi che:

  • Recuperare attributi specifici degli oggetti.
  • Recupera le metriche sul rendimento degli oggetti in base a un intervallo di date.
  • Ordinare gli oggetti in base ai loro attributi.
  • Utilizza le condizioni per indicare gli oggetti che vuoi che vengano restituiti nella risposta.
  • Limita il numero di oggetti restituiti.

GoogleAdsService può restituire i risultati in due modi:

  • GoogleAdsService.SearchStream restituisce tutte le righe in un'unica risposta in streaming, il che è più efficiente per set di risultati di grandi dimensioni (più di 10.000 righe). Questa opzione è consigliata se la tua applicazione scarica set di risultati completi o elabora le righe come stream.
  • GoogleAdsService.Search suddivide le risposte di grandi dimensioni in pagine di risultati gestibili. Questa opzione è utile se l'applicazione interattiva visualizza una pagina di risultati alla volta.

Scopri di più su paginazione e streaming.

Fai una richiesta

GoogleAdsService.SearchStream prevede un valore SearchGoogleAdsStreamRequest, mentre GoogleAdsService.Search prevede un valore SearchGoogleAdsRequest. Entrambi i tipi di richiesta includono:

  • customer_id
  • Una query di Google Ads Query Language che indica la risorsa su cui eseguire la query, gli attributi, i segmenti e le metriche da recuperare e le condizioni da utilizzare per limitare gli oggetti restituiti

A seconda del metodo, la richiesta supporta anche campi specifici del metodo:

  • SearchGoogleAdsStreamRequest (solo SearchStream):
    • Un summary_row_setting facoltativo per richiedere una riga di riepilogo contenente metriche aggregate
  • SearchGoogleAdsRequest (solo Search):
    • Un page_token facoltativo per recuperare il batch di risultati successivo quando utilizzi la paginazione (page_size è fissato a 10.000 righe; l'impostazione di page_size nella richiesta genera un errore RequestError.PAGE_SIZE_NOT_SUPPORTED)
    • Un messaggio search_settings facoltativo per configurare return_summary_row, return_total_results_count e omit_results
    • Un valore booleano validate_only facoltativo per convalidare la query senza eseguirla

Per saperne di più su Google Ads Query Language, consulta la guida di Google Ads Query Language.

Elabora una risposta

GoogleAdsService restituisce un elenco di oggetti GoogleAdsRow (all'interno di batch SearchGoogleAdsStreamResponse in streaming o in un SearchGoogleAdsResponse con pagine).

Ogni GoogleAdsRow rappresenta un oggetto restituito da una query ed è costituito da un insieme di attributi compilati in base ai campi richiesti nella clausola SELECT. Gli attributi non inclusi nella clausola SELECT non vengono compilati negli oggetti GoogleAdsRow della risposta.

Ad esempio, sebbene un ad_group_criterion abbia un attributo status, il campo status dell'attributo ad_group_criterion della riga non viene compilato in una risposta per una query in cui la clausola SELECT non include ad_group_criterion.status. Analogamente, l'attributo campaign della riga non viene compilato se la clausola SELECT non include campi della risorsa campaign.

Ogni GoogleAdsRow può avere attributi e metriche diversi da un'altra riga nello stesso set di risultati, pertanto le righe devono essere visualizzate come oggetti anziché come righe fisse di una tabella.

Tipi di enum UNKNOWN e UNSPECIFIED

Le risorse restituite con un valore enum UNKNOWN non sono completamente supportate in quella versione dell'API, mentre UNSPECIFIED indica che un campo enum non è stato impostato o non è stato richiesto nella clausola SELECT. Le risorse con un valore dell'enum UNKNOWN potrebbero essere state create tramite altre interfacce, ad esempio l'interfaccia utente di Google Ads. Puoi selezionare le metriche quando una risorsa ha un tipo di UNKNOWN, ma non puoi modificarla tramite l'API. Un esempio potrebbe essere un tipo di campagna o di annuncio disponibile nell'interfaccia utente, ma non supportato nella versione dell'API su cui stai eseguendo la query.

Ecco alcune considerazioni da tenere presente:

  • Una risorsa con un tipo UNKNOWN può essere supportata in una versione successiva dell'API o rimanere UNKNOWN a tempo indeterminato.
  • Nuovi oggetti di tipo UNKNOWN possono apparire in qualsiasi momento. Questi oggetti sono compatibili con le versioni precedenti perché il valore enum UNKNOWN è presente in ogni enum nell'API. Le risorse vengono restituite con UNKNOWN in modo da avere una visione accurata delle metriche sul rendimento complessivo del tuo account.
  • Le risorse UNKNOWN possono avere metriche dettagliate allegate che possono essere interrogate.
  • Le risorse UNKNOWN sono in genere completamente visibili nell'interfaccia utente di Google Ads.
  • In genere, le risorse UNKNOWN non possono essere modificate tramite l'API.

Segmentazione

La risposta contiene un GoogleAdsRow per ogni combinazione di quanto segue:

  • Istanza della risorsa principale specificata nella clausola FROM
  • Valore di ogni campo segments selezionato

Ad esempio, la risposta per una query che seleziona FROM campaign e ha segments.ad_network_type e segments.date nella clausola SELECT contiene una riga per ogni combinazione di quanto segue:

  • campaign
  • segments.ad_network_type
  • segments.date

I risultati vengono segmentati in modo implicito in base a ogni istanza della risorsa principale, non in base ai valori dei singoli campi selezionati. Ad esempio,

SELECT campaign.status, metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS

genera una riga per campagna, non una riga per valore distinto del campo campaign.status.

Indietro
Modificare gli oggetti
Avanti
Metadati delle risorse