L'API Google Ads dispone di un meccanismo unificato di recupero degli attributi e di generazione di report sulle metriche che ti consente di creare query utilizzando il linguaggio di query di Google Ads. Ciò consente di eseguire query complesse che possono restituire grandi quantità di dati su singoli account Google Ads.
Puoi creare query utilizzando i metodi 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 in un set di risultati utilizzando l'impaginazione. Questo potrebbe essere vantaggioso in caso di larghezza di banda insufficiente o in condizioni di rete inaffidabili, ad esempio per segmentare un insieme di risultati di grandi dimensioni in risposte più piccole che possono essere recuperate nuovamente in caso di interruzione della connessione. Il metodo SearchStream, invece, trasmette l'intero risultato in una singola risposta, il che può essere più efficiente per il recupero collettivo dei dati.
Sia Search che SearchStream usano lo stesso URL di base:
https://googleads.googleapis.com/v16/customers/CUSTOMER_ID/googleAds
Il metodo di ricerca basata sulle pagine richiede un parametro pageSize facoltativo che limita il numero di risultati restituiti in una singola risposta dell'API.
POST /v16/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 nei risultati sono presenti più righe rispetto a pageSize, nella risposta viene restituito un nextPageToken:
{
"results": [
// ...
// ...
// ...
],
"nextPageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B",
"fieldMask": "adGroupCriterion.keyword.text,adGroupCriterion.status"
}
La ripetizione della stessa query con un valore pageToken aggiunto con il valore riportato sopra consente di recuperare
la pagina di risultati successiva:
POST /v16/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 streaming, è sufficiente modificare il metodo di servizio nell'URL in searchStream
(pageSize e pageToken non sono obbligatori per SearchStream):
POST /v16/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'"
}