Recupero di oggetti

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

• Recuperare attributi specifici degli oggetti.
• Recupera le metriche sul rendimento per gli oggetti in base a un intervallo di date.
• Ordina 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 risultati in due modi:

• GoogleAdsService.SearchStream restituisce tutte le righe in una singola risposta di 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 interi insiemi di risultati o elabora le righe come flusso.
• GoogleAdsService.Search suddivide le risposte di grandi dimensioni in pagine di risultati gestibili. Ciò è utile se la tua applicazione interattiva mostra una pagina di risultati alla volta.

Scopri di più sulla paginazione rispetto allo streaming.

Fai una richiesta

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

• customer_id
• Un linguaggio di query Google Ads query che indica la risorsa da interrogare, 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 successivo di risultati quando si utilizza la paginazione (page_size è fisso 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 a Google Ads Query Language.

Elaborare una risposta

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

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 inseriti negli oggetti GoogleAdsRow nella risposta.

Ad esempio, anche se un ad_group_criterion ha 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. Allo stesso modo, 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 insieme di risultati, quindi le righe devono essere visualizzate come oggetti anziché righe fisse di una tabella.

Tipi di enumerazione 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 enum UNKNOWN potrebbero essere state create tramite altre interfacce come 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 di questo potrebbe essere un tipo di campagna o annuncio disponibile nella UI che non è supportato nella versione dell'API che stai interrogando.

Ecco alcune considerazioni da tenere presente:

• Una risorsa di tipo UNKNOWN può essere supportata in una versione successiva dell'API o rimanere UNKNOWN a tempo indeterminato.
• Nuovi oggetti di tipo UNKNOWN possono essere visualizzati in qualsiasi momento. Questi oggetti sono compatibili con le versioni precedenti perché il valore enum UNKNOWN è presente in ogni enum dell'API. Le risorse vengono restituite con UNKNOWN in modo da avere una visualizzazione accurata delle metriche di rendimento complessive del tuo account.
• Alle risorse UNKNOWN possono essere associate metriche dettagliate che possono essere interrogate.
• UNKNOWN sono in genere completamente visibili nell'interfaccia utente di Google Ads.
• Le risorse UNKNOWN in genere 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 a 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 implicitamente 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

risulta in una riga per campagna, non una riga per ogni valore distinto del campo campaign.status.