Recupero oggetti in corso...

Obiettivo: comprendere come recuperare oggetti e statistiche sul rendimento utilizzando GoogleAdsService. Per i concetti relativi ai report, consulta le guide ai report.

GoogleAdsService è il servizio di recupero e generazione di report sugli oggetti unificato dell'API Google Ads. Il servizio dispone di 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 relativi attributi.
• Utilizza le condizioni per indicare quali oggetti vuoi che vengano restituiti nella risposta.
• Limita il numero di oggetti restituiti.

L'operatore GoogleAdsService può restituire risultati in due modi:

• GoogleAdsService.SearchStream restituisce tutte le righe in una singola risposta in streaming,che è più efficiente per i set di risultati di grandi dimensioni (più di 10.000 righe). Questa opzione potrebbe essere più appropriata se la tua applicazione batch vuole scaricare il maggior numero di dati nel più breve tempo possibile.
• GoogleAdsService.Search suddivide le risposte lunghe in pagine di risultati gestibili. Questa opzione potrebbe essere più appropriata se la tua applicazione interattiva mostra una pagina di risultati alla volta.

Scopri di più sulla paginazione rispetto allo streaming.

Fai una richiesta

Il metodo di ricerca richiede un SearchGoogleAdsRequest, costituito dai seguenti attributi:

• Un customer_id
• Un linguaggio di query di Google Ads query 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
• (Solo GoogleAdsService.Search) Un valore page_size per indicare il numero di oggetti da restituire in una singola risposta quando si utilizza la paginazione.
• (Solo GoogleAdsService.Search) Un valore page_token facoltativo per recuperare il batch di risultati successivo quando si utilizza la paginazione.

Per saperne di più sul linguaggio di query di Google Ads, consulta la guida al linguaggio di query di Google Ads.

Elaborare una risposta

GoogleAdsService restituisce un elenco di oggetti GoogleAdsRow.

Ogni GoogleAdsRow rappresenta un oggetto restituito da una query e consiste in un insieme di attributi che vengono 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, 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. 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 rispetto a un'altra riga nello stesso insieme di risultati. Pertanto, le righe devono essere visualizzate come oggetti anziché come righe fisse di una tabella.

Tipi di enum UNKNOWN

Le risorse restituite con un tipo UNKNOWN non sono completamente supportate in quella versione dell'API. Queste risorse potrebbero essere state create tramite altre interfacce, come l'interfaccia utente di Google Ads. Puoi selezionare le metriche quando una risorsa ha un tipo UNKNOWN, ma non puoi modificarla tramite l'API. Un esempio è una nuova campagna o un nuovo annuncio introdotti nell'interfaccia utente, ma non supportati nella versione dell'API a cui esegui la query.

Ecco alcune considerazioni da tenere presenti:

• Una risorsa con un tipo UNKNOWN può essere supportata in un secondo momento o rimanere UNKNOWN indefinitamente.
• I nuovi oggetti con tipo UNKNOWN possono essere visualizzati in qualsiasi momento. Questi oggetti sono compatibili con le versioni precedenti perché il valore dell'enum è già disponibile. Le risorse vengono introdotte con questa modifica man mano che diventano disponibili, in modo da avere una visione accurata del tuo account. La risorsa UNKNOWN può essere visualizzata a causa di nuove attività nel tuo account tramite altre interfacce o quando una risorsa non è più supportata.
• Le risorse UNKNOWN possono avere metriche dettagliate a cui è possibile eseguire query.
• Le risorse UNKNOWN sono in genere completamente visibili nell'interfaccia utente di Google Ads.
• In genere, le risorse UNKNOWN non possono essere sottoposte a mutazione.

Segmentazione

La risposta conterrà un GoogleAdsRow per ogni combinazione di quanto segue:

• Instanza della risorsa principale specificata nella clausola FROM
• Valore di ogni campo segment selezionato

Ad esempio, la risposta per una query che seleziona FROM campaign e contiene segments.ad_network_type e segments.date nella clausola SELECT conterrà 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

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