L'API Google Ads dispone di un meccanismo unificato per il recupero degli attributi e la generazione di report sulle metriche che ti consente di creare query utilizzando il linguaggio di query di Google Ads. In questo modo si possono eseguire query complesse in grado di restituire grandi quantità di dati su singoli account Google Ads.
Puoi creare query utilizzando il metodo Search o SearchStream.
Entrambi i metodi supportano le stesse query e restituiscono risultati equivalenti. Il metodo Search restituisce i dati in dimensioni di pagina personalizzabili, consentendoti di eseguire l'iterazione di un set di risultati utilizzando l'impaginazione. Ciò potrebbe essere vantaggioso in caso di scarsa larghezza di banda o in condizioni di rete inaffidabili, ad esempio segmentare un insieme di risultati di grandi dimensioni in risposte più piccole che possono essere recuperate nuovamente in caso di perdita della connessione. Il metodo SearchStream, invece, trasmette l'intero risultato impostato nuovamente in un'unica risposta, il che può essere più efficiente per il recupero di dati in blocco.
Sia Search sia SearchStream utilizzano lo stesso URL di base:
https://googleads.googleapis.com/v17/customers/CUSTOMER_ID/googleAds
Il metodo di ricerca basata sulle pagine utilizza un parametro facoltativo pageSize che limita
il numero di risultati restituiti in una singola risposta dell'API.
POST /v17/customers/CUSTOMER_ID/googleAds:search HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
{
"pageSize": 10000,
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'"
}
Se i risultati contengono più righe di pageSize, nella risposta viene restituito
un nextPageToken:
{
"results": [
// ...
// ...
// ...
],
"nextPageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B",
"fieldMask": "adGroupCriterion.keyword.text,adGroupCriterion.status"
}
La ripetizione della stessa query con l'aggiunta di pageToken con il valore riportato sopra consente di recuperare
la pagina di risultati successiva:
POST /v17/customers/CUSTOMER_ID/googleAds:search HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
{
"pageSize": 10000,
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'",
"pageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B"
}
Per utilizzare il metodo SearchStream, che restituisce tutti i risultati in un'unica risposta
in modalità flusso, è sufficiente cambiare il metodo del servizio nell'URL in searchStream
(pageSize e pageToken non sono obbligatori per SearchStream):
POST /v17/customers/CUSTOMER_ID/googleAds:searchStream HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
{
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'"
}